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 f2bc616c0..f0869dcef 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 @@ -45,6 +45,27 @@ pip3 install apache-iotdb>=2.0 | 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 @@ -488,10 +509,16 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") 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") + res = session.execute_query_statement("select * from table0") + 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 7e2fb95e5..9bf6280f0 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 @@ -45,6 +45,27 @@ pip3 install apache-iotdb>=2.0 | 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 @@ -488,10 +509,16 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") 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") + res = session.execute_query_statement("select * from table0") + 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 1c8316507..da500db6b 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 @@ -556,6 +556,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 8df2a7996..99032ef04 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 @@ -557,6 +557,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 f2bc616c0..c89b353c5 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 @@ -45,6 +45,27 @@ pip3 install apache-iotdb>=2.0 | 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 @@ -488,10 +509,16 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") 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") + res = session.execute_query_statement("select * from table0") + 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 7e2fb95e5..242abc92e 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 @@ -45,6 +45,26 @@ pip3 install apache-iotdb>=2.0 | 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 @@ -488,10 +508,16 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") 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") + res = session.execute_query_statement("select * from table0") + 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 1c8316507..da500db6b 100644 --- a/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md +++ b/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md @@ -556,6 +556,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 8df2a7996..69465a658 100644 --- a/src/UserGuide/latest/API/Programming-Python-Native-API_timecho.md +++ b/src/UserGuide/latest/API/Programming-Python-Native-API_timecho.md @@ -557,6 +557,54 @@ 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 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 63953b310..c6bd9a77c 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 @@ -46,6 +46,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:** @@ -495,10 +515,16 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") while res.has_next(): print(res.next()) - + + # 使用分批DataFrame方式查询表数据(推荐大数据量场景) + print("get data from table0 using batch DataFrame") + res = session.execute_query_statement("select * from table0") + 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 2ebecf58e..af1b1565c 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 @@ -46,6 +46,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:** @@ -495,9 +515,15 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") while res.has_next(): print(res.next()) + + # 使用分批DataFrame方式查询表数据(推荐大数据量场景) + print("get data from table0 using batch DataFrame") + res = session.execute_query_statement("select * from table0") + 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 50a9e07b6..f0da8d6f2 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 @@ -553,6 +553,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 a36c508a0..c4cef58ee 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 @@ -553,6 +553,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 63953b310..c6bd9a77c 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 @@ -46,6 +46,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:** @@ -495,10 +515,16 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") while res.has_next(): print(res.next()) - + + # 使用分批DataFrame方式查询表数据(推荐大数据量场景) + print("get data from table0 using batch DataFrame") + res = session.execute_query_statement("select * from table0") + 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 2ebecf58e..3a64ca31e 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 @@ -46,6 +46,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:** @@ -495,9 +515,15 @@ def query_data(): print(res.next()) print("get data from table1") - res = session.execute_query_statement("select * from table0") + res = session.execute_query_statement("select * from table1") while res.has_next(): print(res.next()) + + # 使用分批DataFrame方式查询表数据(推荐大数据量场景) + print("get data from table0 using batch DataFrame") + res = session.execute_query_statement("select * from table0") + 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 50a9e07b6..f0da8d6f2 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 @@ -553,6 +553,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 a36c508a0..73d1cfafa 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 @@ -553,6 +553,53 @@ 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) 的,如果您想使用该特性,就需要将其安装到您的项目中。