Python API Reference

---

#### `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.

This property returns a list of 7-item tuples describing each column
in the result set of the last executed SELECT query. Each tuple contains:
(name, type\_code, display\_size, internal\_size, precision, scale, null\_ok)

Currently, only name and type\_code are provided, with other fields set to None.

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `list` List of 7-tuples describing each column, or empty list if no SELECT query has been executed | | | |

Note

This follows the DB-API 2.0 specification for cursor.description.
Only the first two elements (name and type\_code) contain meaningful
data in this implementation.

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users LIMIT 1")
>>> for desc in cursor.description:
...     print(f"Column: {desc[0]}, Type: {desc[1]}")
Column: id, Type: Int32
Column: name, Type: String
```

**See also**

- [`column_names()`](#chdb-state-sqlitelike-cursor-column_names) - Get just column names
- [`column_types()`](#chdb-state-sqlitelike-cursor-column_types) - Get just column types

---

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

Execute a SQL query and prepare results for fetching.

This method executes a SQL query and prepares the results for retrieval
using the fetch methods. It handles the parsing of result data and
automatic type conversion for ClickHouse data types.

**Syntax**

```
execute(query: str) → None
```

**Parameters:**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  | | --- | --- | --- | | `query` str SQL query string to execute | | | | | |

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | `Exception` If query execution fails or result parsing fails | | | |

Note

This method follows DB-API 2.0 specifications for `cursor.execute()`.
After execution, use `fetchone()`, `fetchmany()`, or `fetchall()` to
retrieve results.

Note

The method automatically converts ClickHouse data types to appropriate
Python types:

- Int/UInt types → int
- Float types → float
- String/FixedString → str
- DateTime → datetime.datetime
- Date → datetime.date
- Bool → bool

**Examples**

```
>>> cursor = conn.cursor()
>>>
>>> # Execute DDL
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>>
>>> # Execute DML
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>>
>>> # Execute SELECT and fetch results
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)
```

**See also**

- [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) - Fetch single row
- [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - Fetch multiple rows
- [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) - Fetch all remaining rows

---

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

Fetch all remaining rows from the query result.

This method retrieves all remaining rows from the current query result
set starting from the current cursor position. It returns a tuple of
row tuples with appropriate Python type conversion applied.

**Syntax**

```
fetchall() → tuple
```

**Returns:**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `tuple` Tuple containing all remaining row tuples from the result set. Returns empty tuple if no rows are available | | | |

Warning

This method loads all remaining rows into memory at once. For large
result sets, consider using [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) to process results
in batches.

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> all_users = cursor.fetchall()
>>> for user_id, user_name in all_users:
...     print(f"User {user_id}: {user_name}")
```

**See also**

- [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) - Fetch single row
- [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - Fetch multiple rows in batches

---

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

Fetch multiple rows from the query result.

This method retrieves up to ‘size’ rows from the current query result
set. It returns a tuple of row tuples, with each row containing column
values with appropriate Python type conversion.

**Syntax**

```
fetchmany(size: int = 1) → tuple
```

**Parameters**

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  | | --- | --- | --- | --- | | `size` int `1` Maximum number of rows to fetch | | | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `tuple` Tuple containing up to 'size' row tuples. May contain fewer rows if the result set is exhausted | | | |

Note

This method follows DB-API 2.0 specifications. It will return fewer
than ‘size’ rows if the result set is exhausted.

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Process results in batches
>>> while True:
...     batch = cursor.fetchmany(100)  # Fetch 100 rows at a time
...     if not batch:
...         break
...     process_batch(batch)
```

**See also**

- [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) - Fetch single row
- [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) - Fetch all remaining rows

---

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

Fetch the next row from the query result.

This method retrieves the next available row from the current query
result set. It returns a tuple containing the column values with
appropriate Python type conversion applied.

**Syntax**

```
fetchone() → tuple | None
```

**Returns:**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `Optional[tuple]` Next row as a tuple of column values, or None if no more rows are available | | | |

Note

This method follows DB-API 2.0 specifications. Column values are
automatically converted to appropriate Python types based on
ClickHouse column types.

**Examples**

```
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> row = cursor.fetchone()
>>> while row is not None:
...     user_id, user_name = row
...     print(f"User {user_id}: {user_name}")
...     row = cursor.fetchone()
```

**See also**

- [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - Fetch multiple rows
- [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) - Fetch all remaining rows

---

### `chdb.state.sqlitelike`[​](#state-sqlitelike-to_arrowtable "Direct link to state-sqlitelike-to_arrowtable")

Convert query result to PyArrow Table.

This function converts chdb query results to a PyArrow Table format,
which provides efficient columnar data access and interoperability
with other data processing libraries.

**Syntax**

```
chdb.state.sqlitelike.to_arrowTable(res)
```

**Parameters:**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  | | --- | --- | --- | | `res` - Query result object from chdb containing Arrow format data | | | | | |

**Returns**