Add note about chunksize blocking the event loop in aio cursors

When chunksize is set, execute() creates a lazy reader instead of
loading all data. Subsequent iteration triggers blocking S3 reads
not wrapped in asyncio.to_thread(). Document this limitation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: laughingman7743

docs/aio.md

@@ -201,4 +201,14 @@ row = await cursor.fetchone()    # Await required — reads from S3
 rows = await cursor.fetchall()   # Await required
 ```
 
+```{note}
+When using AioPandasCursor or AioPolarsCursor with the `chunksize` option,
+`execute()` creates a lazy reader (e.g., pandas `TextFileReader`) instead of
+loading all data at once. Subsequent iteration via `as_pandas()`, `fetchone()`,
+or `async for` triggers chunk-by-chunk S3 reads that are **not** wrapped in
+`asyncio.to_thread()` and will block the event loop. If you need chunked
+processing in an async application, consider wrapping the iteration in
+`asyncio.to_thread()` yourself, or use the default non-chunked mode.
+```
+
 See each cursor's documentation page for detailed usage examples.

docs/pandas.md

@@ -832,3 +832,10 @@ async with await aconnect(s3_staging_dir="s3://YOUR_S3_BUCKET/path/to/",
     await cursor.execute("SELECT * FROM many_rows")
     df = cursor.as_pandas()
 ```
+
+```{note}
+When using AioPandasCursor with the `chunksize` option, `execute()` creates a lazy
+`TextFileReader` instead of loading all data at once. Subsequent iteration via
+`as_pandas()`, `fetchone()`, or `async for` triggers chunk-by-chunk S3 reads that
+are not wrapped in `asyncio.to_thread()` and will block the event loop.
+```

docs/polars.md

@@ -652,3 +652,10 @@ async with await aconnect(s3_staging_dir="s3://YOUR_S3_BUCKET/path/to/",
     await cursor.execute("SELECT * FROM many_rows")
     df = cursor.as_polars()
 ```
+
+```{note}
+When using AioPolarsCursor with the `chunksize` option, `execute()` creates a lazy
+reader instead of loading all data at once. Subsequent iteration via `as_polars()`,
+`fetchone()`, or `async for` triggers chunk-by-chunk S3 reads that are not wrapped
+in `asyncio.to_thread()` and will block the event loop.
+```