This is an automated email from the ASF dual-hosted git repository.
haonan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 16a555c0 add sessiondataset.has_next_df and .next_df to python api
from 2082 (#996)
16a555c0 is described below
commit 16a555c076c048efa6b4fefd00b140d7a5b4efd9
Author: leto-b <[email protected]>
AuthorDate: Tue Mar 31 17:03:31 2026 +0800
add sessiondataset.has_next_df and .next_df to python api from 2082 (#996)
* add sessiondataset.has_next_df and .next_df to python api from 2082
* adjust version beta
* remove beta from timecho
---
.../API/Programming-Python-Native-API_apache.md | 33 +++++++++++++--
.../API/Programming-Python-Native-API_timecho.md | 33 +++++++++++++--
.../API/Programming-Python-Native-API_apache.md | 46 +++++++++++++++++++++
.../API/Programming-Python-Native-API_timecho.md | 48 ++++++++++++++++++++++
.../API/Programming-Python-Native-API_apache.md | 29 ++++++++++++-
.../API/Programming-Python-Native-API_timecho.md | 36 +++++++++++++---
.../API/Programming-Python-Native-API_apache.md | 46 +++++++++++++++++++++
.../API/Programming-Python-Native-API_timecho.md | 48 ++++++++++++++++++++++
.../API/Programming-Python-Native-API_apache.md | 34 +++++++++++++--
.../API/Programming-Python-Native-API_timecho.md | 32 +++++++++++++--
.../API/Programming-Python-Native-API_apache.md | 46 +++++++++++++++++++++
.../API/Programming-Python-Native-API_timecho.md | 47 +++++++++++++++++++++
.../API/Programming-Python-Native-API_apache.md | 33 +++++++++++++--
.../API/Programming-Python-Native-API_timecho.md | 30 +++++++++++++-
.../API/Programming-Python-Native-API_apache.md | 46 +++++++++++++++++++++
.../API/Programming-Python-Native-API_timecho.md | 47 +++++++++++++++++++++
16 files changed, 609 insertions(+), 25 deletions(-)
diff --git
a/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
b/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
index 1b1e629d..d6024740 100644
--- a/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
+++ b/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
@@ -46,6 +46,27 @@ Note: Do not use a newer client to connect to an older
server, as this may cause
| execute_query_statement | Executes a query SQL statement and retrieves
results. | sql: `str` | `SessionDataSet` |
| close | Closes the session and releases resources.
| None | None |
+**Since V2.0.8-beta**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether more data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
+
#### Sample Code
```Python
@@ -491,10 +512,16 @@ def query_data():
print(res.next())
print("get data from table1")
- with session.execute_query_statement("select * from table0") as res:
- while res.has_next():
- print(res.next())
+ with session.execute_query_statement("select * from table1") as res:
+ while res.has_next():
+ print(res.next())
+ # Querying Table Data Using Batch DataFrame (Recommended for Large
Datasets)
+ print("get data from table0 using batch DataFrame")
+ with session.execute_query_statement("select * from table0") as res:
+ while res.has_next_df():
+ print(res.next_df())
+
session.close()
diff --git
a/src/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
b/src/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
index b9193eaa..23d3b2f6 100644
--- a/src/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
+++ b/src/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
@@ -46,6 +46,27 @@ Note: Do not use a newer client to connect to an older
server, as this may cause
| execute_query_statement | Executes a query SQL statement and retrieves
results. | sql: `str` | `SessionDataSet` |
| close | Closes the session and releases resources.
| None | None |
+**Since V2.0.8**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether more data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
+
#### Sample Code
```Python
@@ -491,9 +512,15 @@ def query_data():
print(res.next())
print("get data from table1")
- with session.execute_query_statement("select * from table0") as res:
- while res.has_next():
- print(res.next())
+ with session.execute_query_statement("select * from table1") as res:
+ while res.has_next():
+ print(res.next())
+
+ # Querying Table Data Using Batch DataFrame (Recommended for Large
Datasets)
+ print("get data from table0 using batch DataFrame")
+ with session.execute_query_statement("select * from table0") as res:
+ while res.has_next_df():
+ print(res.next_df())
session.close()
diff --git
a/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
b/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
index 02b83165..b0d43b4a 100644
--- a/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
+++ b/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
@@ -557,6 +557,52 @@ session.close()
df = ...
```
+**Since V2.0.8-beta**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether more data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
+**Usage Example:**
+
+```python
+from iotdb.Session import Session
+
+# Initialize session with fetch_size=2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# Insert 3 records
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# Query and batch retrieve
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # Outputs two DataFrames: first with 2 rows, second with 1 row
+ print(df)
+
+session.close()
+```
## 10. IoTDB Testcontainer
diff --git
a/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
b/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
index c5d95ffc..e7cbea09 100644
--- a/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
+++ b/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
@@ -558,6 +558,54 @@ df = ...
```
+**Since V2.0.8**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether more data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
+**Usage Example:**
+
+```python
+from iotdb.Session import Session
+
+# Initialize session with fetch_size=2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# Insert 3 records
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# Query and batch retrieve
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # Outputs two DataFrames: first with 2 rows, second with 1 row
+ print(df)
+
+session.close()
+```
+
+
## 10. IoTDB Testcontainer
The Test Support is based on the lib `testcontainers`
(https://testcontainers-python.readthedocs.io/en/latest/index.html) which you
need to install in your project if you want to use the feature.
diff --git
a/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
b/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
index 1b1e629d..2d6b6f7e 100644
--- a/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
+++ b/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
@@ -46,6 +46,27 @@ Note: Do not use a newer client to connect to an older
server, as this may cause
| execute_query_statement | Executes a query SQL statement and retrieves
results. | sql: `str` | `SessionDataSet` |
| close | Closes the session and releases resources.
| None | None |
+**Since V2.0.8-beta**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether ore data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
+
#### Sample Code
```Python
@@ -491,10 +512,16 @@ def query_data():
print(res.next())
print("get data from table1")
- with session.execute_query_statement("select * from table0") as res:
+ with session.execute_query_statement("select * from table1") as res:
while res.has_next():
print(res.next())
+ # Querying Table Data Using Batch DataFrame (Recommended for Large
Datasets)
+ print("get data from table0 using batch DataFrame")
+ with session.execute_query_statement("select * from table0") as res:
+ while res.has_next_df():
+ print(res.next_df())
+
session.close()
diff --git
a/src/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
b/src/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
index b9193eaa..65eac650 100644
--- a/src/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
+++ b/src/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
@@ -46,6 +46,26 @@ Note: Do not use a newer client to connect to an older
server, as this may cause
| execute_query_statement | Executes a query SQL statement and retrieves
results. | sql: `str` | `SessionDataSet` |
| close | Closes the session and releases resources.
| None | None |
+**Since V2.0.8**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether more data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
#### Sample Code
```Python
@@ -490,11 +510,17 @@ def query_data():
while res.has_next():
print(res.next())
- print("get data from table1")
- with session.execute_query_statement("select * from table0") as res:
- while res.has_next():
- print(res.next())
-
+ print("get data from table1")
+ with session.execute_query_statement("select * from table1") as res:
+ while res.has_next():
+ print(res.next())
+
+ # Querying Table Data Using Batch DataFrame (Recommended for Large
Datasets)
+ print("get data from table0 using batch DataFrame")
+ with session.execute_query_statement("select * from table0") as res:
+ while res.has_next_df():
+ print(res.next_df())
+
session.close()
diff --git a/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md
b/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md
index 02b83165..b0d43b4a 100644
--- a/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md
+++ b/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md
@@ -557,6 +557,52 @@ session.close()
df = ...
```
+**Since V2.0.8-beta**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether more data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
+**Usage Example:**
+
+```python
+from iotdb.Session import Session
+
+# Initialize session with fetch_size=2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# Insert 3 records
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# Query and batch retrieve
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # Outputs two DataFrames: first with 2 rows, second with 1 row
+ print(df)
+
+session.close()
+```
## 10. IoTDB Testcontainer
diff --git a/src/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
b/src/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
index c5d95ffc..e7cbea09 100644
--- a/src/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
+++ b/src/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
@@ -558,6 +558,54 @@ df = ...
```
+**Since V2.0.8**, `SessionDataSet` provides methods for batch DataFrame
retrieval to efficiently handle large-volume queries:
+
+```python
+# Batch DataFrame retrieval
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # Process DataFrame
+```
+
+**Method Details:**
+- `has_next_df()`: Returns `True`/`False` indicating whether more data exists
+- `next_df()`: Returns a `DataFrame` or `None`. Each call returns `fetchSize`
rows (default: 5000 rows, controlled by Session's `fetch_size` parameter):
+ - If remaining data ≥ `fetchSize`: returns `fetchSize` rows
+ - If remaining data < `fetchSize`: returns all remaining rows
+ - If traversal completes: returns `None`
+- Session validates `fetchSize` at initialization: if ≤0, resets to 5000 and
logs warning: `fetch_size xxx is illegal, use default fetch_size 5000`
+
+**Note:** Avoid mixing different traversal methods (e.g., combining `todf()`
with `next_df()`), which may cause unexpected errors.
+
+**Usage Example:**
+
+```python
+from iotdb.Session import Session
+
+# Initialize session with fetch_size=2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# Insert 3 records
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# Query and batch retrieve
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # Outputs two DataFrames: first with 2 rows, second with 1 row
+ print(df)
+
+session.close()
+```
+
+
## 10. IoTDB Testcontainer
The Test Support is based on the lib `testcontainers`
(https://testcontainers-python.readthedocs.io/en/latest/index.html) which you
need to install in your project if you want to use the feature.
diff --git
a/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
b/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
index 8792f3ca..e19a376a 100644
--- a/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
+++ b/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md
@@ -47,6 +47,26 @@ TableSession是IoTDB的一个核心类，用于与IoTDB数据库进行交互。
| execute_query_statement | 执行查询 SQL 语句并返回结果集 | sql: str
| SessionDataSet |
| close | 关闭会话并释放资源 | None
| None |
+自 V2.0.8-beta 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
#### 2.1.3 接口展示
**TableSession:**
@@ -498,10 +518,16 @@ def query_data():
print(res.next())
print("get data from table1")
- with session.execute_query_statement("select * from table0") as res:
- while res.has_next():
- print(res.next())
-
+ with session.execute_query_statement("select * from table1") as res:
+ while res.has_next():
+ print(res.next())
+
+ # 使用分批DataFrame方式查询表数据（推荐大数据量场景）
+ print("get data from table0 using batch DataFrame")
+ with session.execute_query_statement("select * from table0") as res:
+ while res.has_next_df():
+ print(res.next_df())
+
session.close()
diff --git
a/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
b/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
index 43bdfc3f..7bf6dd1b 100644
--- a/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
+++ b/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_timecho.md
@@ -47,6 +47,26 @@ TableSession是IoTDB的一个核心类，用于与IoTDB数据库进行交互。
| execute_query_statement | 执行查询 SQL 语句并返回结果集 | sql: str
| SessionDataSet |
| close | 关闭会话并释放资源 | None
| None |
+自 V2.0.8 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
#### 2.1.3 接口展示
**TableSession:**
@@ -498,9 +518,15 @@ def query_data():
print(res.next())
print("get data from table1")
- with session.execute_query_statement("select * from table0") as res:
- while res.has_next():
- print(res.next())
+ with session.execute_query_statement("select * from table1") as res:
+ while res.has_next():
+ print(res.next())
+
+ # 使用分批DataFrame方式查询表数据（推荐大数据量场景）
+ print("get data from table0 using batch DataFrame")
+ with session.execute_query_statement("select * from table0") as res:
+ while res.has_next_df():
+ print(res.next_df())
session.close()
diff --git
a/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
b/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
index 9219ce9c..ac5477cc 100644
--- a/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
+++ b/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md
@@ -555,6 +555,52 @@ session.close()
df = ...
```
+自 V2.0.8-beta 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
+**使用示例：**
+```python
+from iotdb.Session import Session
+
+# 初始化 session，设置 fetch_size 为 2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# 写入三条数据
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# 查询出 DataFrame
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # 打印出两个 dataframe，第一个有 2 行，第二个有 1 行
+ print(df)
+
+session.close()
+```
+
## 9. IoTDB Testcontainer
Python 客户端对测试的支持是基于`testcontainers`库
(https://testcontainers-python.readthedocs.io/en/latest/index.html)
的，如果您想使用该特性，就需要将其安装到您的项目中。
diff --git
a/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
b/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
index d210cd39..f06dbb90 100644
--- a/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
+++ b/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_timecho.md
@@ -555,6 +555,53 @@ session.close()
df = ...
```
+自 V2.0.8 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
+**使用示例：**
+```python
+from iotdb.Session import Session
+
+# 初始化 session，设置 fetch_size 为 2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# 写入三条数据
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# 查询出 DataFrame
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # 打印出两个 dataframe，第一个有 2 行，第二个有 1 行
+ print(df)
+
+session.close()
+```
+
+
## 9. IoTDB Testcontainer
Python 客户端对测试的支持是基于`testcontainers`库
(https://testcontainers-python.readthedocs.io/en/latest/index.html)
的，如果您想使用该特性，就需要将其安装到您的项目中。
diff --git
a/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
b/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
index 8792f3ca..92c19afb 100644
--- a/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
+++ b/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md
@@ -47,6 +47,26 @@ TableSession是IoTDB的一个核心类，用于与IoTDB数据库进行交互。
| execute_query_statement | 执行查询 SQL 语句并返回结果集 | sql: str
| SessionDataSet |
| close | 关闭会话并释放资源 | None
| None |
+自 V2.0.8-beta 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
#### 2.1.3 接口展示
**TableSession:**
@@ -498,10 +518,15 @@ def query_data():
print(res.next())
print("get data from table1")
- with session.execute_query_statement("select * from table0") as res:
- while res.has_next():
- print(res.next())
-
+ with session.execute_query_statement("select * from table1") as res:
+ while res.has_next():
+ print(res.next())
+
+ # 使用分批DataFrame方式查询表数据（推荐大数据量场景）
+ print("get data from table0 using batch DataFrame")
+ with session.execute_query_statement("select * from table0") as res:
+ while res.has_next_df():
+ print(res.next_df())
session.close()
diff --git
a/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
b/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
index 43bdfc3f..cd68cae1 100644
--- a/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
+++ b/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_timecho.md
@@ -47,6 +47,26 @@ TableSession是IoTDB的一个核心类，用于与IoTDB数据库进行交互。
| execute_query_statement | 执行查询 SQL 语句并返回结果集 | sql: str
| SessionDataSet |
| close | 关闭会话并释放资源 | None
| None |
+自 V2.0.8 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
#### 2.1.3 接口展示
**TableSession:**
@@ -498,9 +518,15 @@ def query_data():
print(res.next())
print("get data from table1")
+ with session.execute_query_statement("select * from table1") as res:
+ while res.has_next():
+ print(res.next())
+
+ # 使用分批DataFrame方式查询表数据（推荐大数据量场景）
+ print("get data from table0 using batch DataFrame")
with session.execute_query_statement("select * from table0") as res:
- while res.has_next():
- print(res.next())
+ while res.has_next_df():
+ print(res.next_df())
session.close()
diff --git
a/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md
b/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md
index 9219ce9c..ac5477cc 100644
--- a/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md
+++ b/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md
@@ -555,6 +555,52 @@ session.close()
df = ...
```
+自 V2.0.8-beta 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
+**使用示例：**
+```python
+from iotdb.Session import Session
+
+# 初始化 session，设置 fetch_size 为 2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# 写入三条数据
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# 查询出 DataFrame
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # 打印出两个 dataframe，第一个有 2 行，第二个有 1 行
+ print(df)
+
+session.close()
+```
+
## 9. IoTDB Testcontainer
Python 客户端对测试的支持是基于`testcontainers`库
(https://testcontainers-python.readthedocs.io/en/latest/index.html)
的，如果您想使用该特性，就需要将其安装到您的项目中。
diff --git
a/src/zh/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
b/src/zh/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
index d210cd39..f06dbb90 100644
--- a/src/zh/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
+++ b/src/zh/UserGuide/latest/API/Programming-Python-Native-API_timecho.md
@@ -555,6 +555,53 @@ session.close()
df = ...
```
+自 V2.0.8 版本起，SessionDataSet 提供分批获取 DataFrame 的方法，用于高效处理大数据量查询：
+
+```python
+# 分批获取 DataFrame
+has_next = result.has_next_df()
+if has_next:
+ df = result.next_df()
+ # 处理 DataFrame
+```
+
+**方法说明：**
+- `has_next_df()`: 返回 `True`/`False`，表示是否还有数据可返回
+- `next_df()`: 返回 `DataFrame` 或 `None`，每次返回 `fetchSize` 行（默认5000行，由 Session 的
`fetch_size` 参数控制）
+ - 剩余数据 ≥ `fetchSize` 时，返回 `fetchSize` 行
+ - 剩余数据 < `fetchSize` 时，返回剩余所有行
+ - 数据遍历完毕时，返回 `None`
+- 初始化 Session 时检查 `fetchSize`，若 ≤0 则重置为 5000 并打印警告日志
+
+**注意：** 不要混合使用不同的遍历方式，如（todf函数与 next_df 混用），否则会出现预期外的错误。
+
+**使用示例：**
+```python
+from iotdb.Session import Session
+
+# 初始化 session，设置 fetch_size 为 2
+session = Session(
+ host="127.0.0.1", port="6667", fetch_size=2
+)
+session.open(False)
+session.execute_non_query_statement("CREATE DATABASE root.device0")
+
+# 写入三条数据
+session.insert_str_record("root.device0", 123, "pressure", "15.0")
+session.insert_str_record("root.device0", 124, "pressure", "15.0")
+session.insert_str_record("root.device0", 125, "pressure", "15.0")
+
+# 查询出 DataFrame
+with session.execute_query_statement("SELECT * FROM root.device0") as
session_data_set:
+ while session_data_set.has_next_df():
+ df = session_data_set.next_df()
+ # 打印出两个 dataframe，第一个有 2 行，第二个有 1 行
+ print(df)
+
+session.close()
+```
+
+
## 9. IoTDB Testcontainer
Python 客户端对测试的支持是基于`testcontainers`库
(https://testcontainers-python.readthedocs.io/en/latest/index.html)
的，如果您想使用该特性，就需要将其安装到您的项目中。
