Python API Reference

---

### **class** `chdb.state.sqlitelike.StreamingResult`[​](#chdb-state-sqlitelike-streamingresult "Direct link to chdb-state-sqlitelike-streamingresult")

Bases: `object`

Streaming result iterator for processing large query results.

This class provides an iterator interface for streaming query results without
loading the entire result set into memory. It supports various output formats
and provides methods for manual result fetching and PyArrow RecordBatch streaming.

```
class chdb.state.sqlitelike.StreamingResult
```

---

#### `fetch`[​](#streamingresult-fetch "Direct link to streamingresult-fetch")

Fetch the next chunk of streaming results.

This method retrieves the next available chunk of data from the streaming
query result. The format of the returned data depends on the format specified
when the streaming query was initiated.

**Syntax**

```
fetch() → Any
```

**Returns**

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Return Type Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `str` For text formats (CSV, JSON)|  |  |  |  | | --- | --- | --- | --- | | `bytes` For binary formats (Arrow, Parquet)|  |  | | --- | --- | | `None` When the result stream is exhausted | | | | | | | |

**Examples**

```
>>> stream = conn.send_query("SELECT * FROM large_table")
>>> chunk = stream.fetch()
>>> while chunk is not None:
...     process_data(chunk)
...     chunk = stream.fetch()
```

---

#### `cancel`[​](#streamingresult-cancel "Direct link to streamingresult-cancel")

Cancel the streaming query and cleanup resources.

This method cancels any ongoing streaming query and releases associated
resources. It should be called when you want to stop processing results
before the stream is exhausted.

**Syntax**

```
cancel() → None
```

**Examples**

```
>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Only process first 10 chunks
...         stream.cancel()
...         break
...     process_data(chunk)
```

---

#### `close`[​](#streamingresult-close "Direct link to streamingresult-close")

Close the streaming result and cleanup resources.

Alias for [`cancel()`](#streamingresult-cancel). Closes the streaming result iterator
and releases any associated resources.

**Syntax**

```
close() → None
```

---

#### `record_batch`[​](#streamingresult-record_batch "Direct link to streamingresult-record_batch")

Create a PyArrow RecordBatchReader for efficient batch processing.

This method creates a PyArrow RecordBatchReader that allows efficient
iteration over the query results in Arrow format. This is the most
efficient way to process large result sets when using PyArrow.

**Syntax**

```
record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader
```

**Parameters**

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  | | --- | --- | --- | --- | | `rows_per_batch` int `1000000` Number of rows per batch | | | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `pa.RecordBatchReader` PyArrow RecordBatchReader for iterating over batches | | | |

Note

This method is only available when the streaming query was initiated
with `format="Arrow"`. Using it with other formats will raise an error.

**Examples**

```
>>> stream = conn.send_query("SELECT * FROM data", format="Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Processing batch: {batch.num_rows} rows")
...     df = batch.to_pandas()
...     process_dataframe(df)
```

---

#### Iterator Protocol[​](#streamingresult-iterator "Direct link to Iterator Protocol")

StreamingResult supports the Python iterator protocol, allowing it to be
used directly in for loops:

```
>>> stream = conn.send_query("SELECT number FROM numbers(1000000)")
>>> for chunk in stream:
...     print(f"Chunk size: {len(chunk)} bytes")
```

---

#### Context Manager Protocol[​](#streamingresult-context-manager "Direct link to Context Manager Protocol")

StreamingResult supports the context manager protocol for automatic
resource cleanup:

```
>>> with conn.send_query("SELECT * FROM data") as stream:
...     for chunk in stream:
...         process(chunk)
>>> # Stream automatically closed
```

---

### **class** `chdb.state.sqlitelike.Cursor`[​](#chdb-state-sqlitelike-cursor "Direct link to chdb-state-sqlitelike-cursor")

Bases: `object`

```
class chdb.state.sqlitelike.Cursor(connection)
```

---

#### `close`[​](#cursor-close-none "Direct link to cursor-close-none")

Close the cursor and cleanup resources.

This method closes the cursor and cleans up any associated resources.
After calling this method, the cursor becomes invalid and can't be
used for further operations.

**Syntax**

```
close() → None
```

Note

This method is idempotent - calling it multiple times is safe.
The cursor is also automatically closed when the connection is closed.

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Cleanup cursor resources
```

---

#### `column_names`[​](#chdb-state-sqlitelike-cursor-column_names "Direct link to chdb-state-sqlitelike-cursor-column_names")

Return a list of column names from the last executed query.

This method returns the column names from the most recently executed
SELECT query. The names are returned in the same order as they appear
in the result set.

**Syntax**

```
column_names() → list
```

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `list` List of column name strings, or empty list if no query has been executed or the query returned no columns | | | |

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name, email FROM users LIMIT 1")
>>> print(cursor.column_names())
['id', 'name', 'email']
```

**See also**

- [`column_types()`](#chdb-state-sqlitelike-cursor-column_types) - Get column type information
- [`description`](#chdb-state-sqlitelike-cursor-description) - DB-API 2.0 column description

---

#### `column_types`[​](#chdb-state-sqlitelike-cursor-column_types "Direct link to chdb-state-sqlitelike-cursor-column_types")

Return a list of column types from the last executed query.

This method returns the ClickHouse column type names from the most
recently executed SELECT query. The types are returned in the same
order as they appear in the result set.

**Syntax**

```
column_types() → list
```

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `list` List of ClickHouse type name strings, or empty list if no query has been executed or the query returned no columns | | | |

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT toInt32(1), toString('hello')")
>>> print(cursor.column_types())
['Int32', 'String']
```

**See also**

- [`column_names()`](#chdb-state-sqlitelike-cursor-column_names) - Get column name information
- [`description`](#chdb-state-sqlitelike-cursor-description) - DB-API 2.0 column description

---

#### `commit`[​](#commit "Direct link to commit")

Commit any pending transaction.

This method commits any pending database transaction. In ClickHouse,
most operations are auto-committed, but this method is provided for
DB-API 2.0 compatibility.

Note

ClickHouse typically auto-commits operations, so explicit commits
are usually not necessary. This method is provided for compatibility
with standard DB-API 2.0 workflow.

**Syntax**

```
commit() → None
```

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
>>> cursor.commit()
```

---

#### `property description : list`[​](#chdb-state-sqlitelike-cursor-description "Direct link to chdb-state-sqlitelike-cursor-description")

Return column description as per DB-API 2.0 specification.