Python API Reference

**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**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `pyarrow.Table` PyArrow Table containing the query results | | | |

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | `ImportError` If pyarrow or pandas packages aren't installed | | | |

Note

This function requires both pyarrow and pandas to be installed.
Install them with: `pip install pyarrow pandas`

Warning

Empty results return an empty PyArrow Table with no schema.

**Examples**

```
>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> table = to_arrowTable(result)
>>> print(table.schema)
num: int64
text: string
>>> print(table.to_pandas())
   num   text
0    1  hello
```

---

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

Convert query result to Pandas DataFrame.

This function converts chdb query results to a Pandas DataFrame format
by first converting to PyArrow Table and then to DataFrame. This provides
convenient data analysis capabilities with Pandas API.

**Syntax**

```
chdb.state.sqlitelike.to_df(r)
```

**Parameters:**

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

**Returns:**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `pandas.DataFrame` DataFrame containing the query results with appropriate column names and data types | | | |

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | `ImportError` If pyarrow or pandas packages aren't installed | | | |

Note

This function uses multi-threading for the Arrow to Pandas conversion
to improve performance on large datasets.

**See also**

- [`to_arrowTable()`](#chdb-state-sqlitelike-to_arrowtable) - For PyArrow Table format conversion

**Examples**

```
>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> df = to_df(result)
>>> print(df)
   num   text
0    1  hello
>>> print(df.dtypes)
num      int64
text    object
dtype: object
```

## DataFrame Integration[​](#dataframe-integration "Direct link to DataFrame Integration")

### **class** `chdb.dataframe.Table`[​](#chdb-dataframe-table "Direct link to chdb-dataframe-table")

Bases:

```
class chdb.dataframe.Table(*args: Any, **kwargs: Any)
```

## Database API (DBAPI) 2.0 Interface[​](#database-api-interface "Direct link to Database API (DBAPI) 2.0 Interface")

chDB provides a Python DB-API 2.0 compatible interface for database connectivity, allowing you to use chDB with tools and frameworks that expect standard database interfaces.

The chDB DB-API 2.0 interface includes:

- **Connections**: Database connection management with connection strings
- **Cursors**: Query execution and result retrieval
- **Type System**: DB-API 2.0 compliant type constants and converters
- **Error Handling**: Standard database exception hierarchy
- **Thread Safety**: Level 1 thread safety (threads may share modules but not connections)

---

### Core Functions[​](#core-functions "Direct link to Core Functions")

The Database API (DBAPI) 2.0 Interface implements the following core functions:

#### `chdb.dbapi.connect`[​](#dbapi-connect "Direct link to dbapi-connect")

Initialize a new database connection.

**Syntax**

```
chdb.dbapi.connect(*args, **kwargs)
```

**Parameters**

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  | | --- | --- | --- | --- | | `path` str `None` Database file path. None for in-memory database | | | | | | | |

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`err.Error`](#chdb-dbapi-err-error) If connection can't be established | | | |

---

#### `chdb.dbapi.get_client_info()`[​](#dbapi-get-client-info "Direct link to dbapi-get-client-info")

Get client version information.

Returns the chDB client version as a string for MySQLdb compatibility.

**Syntax**

```
chdb.dbapi.get_client_info()
```

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `str` Version string in format 'major.minor.patch' | | | |

---

### Type constructors[​](#type-constructors "Direct link to Type constructors")

#### `chdb.dbapi.Binary(x)`[​](#dbapi-binary "Direct link to dbapi-binary")

Return x as a binary type.

This function converts the input to bytes type for use with binary
database fields, following the DB-API 2.0 specification.

**Syntax**

```
chdb.dbapi.Binary(x)
```

**Parameters**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  | | --- | --- | --- | | `x` - Input data to convert to binary | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `bytes` The input converted to bytes | | | |

---

### Connection Class[​](#connection-class "Direct link to Connection Class")

#### **class** `chdb.dbapi.connections.Connection(path=None)`[​](#chdb-dbapi-connections-connection "Direct link to chdb-dbapi-connections-connection")

Bases: `object`

DB-API 2.0 compliant connection to chDB database.

This class provides a standard DB-API interface for connecting to and interacting
with chDB databases. It supports both in-memory and file-based databases.

The connection manages the underlying chDB engine and provides methods for
executing queries, managing transactions (no-op for ClickHouse), and creating cursors.

```
class chdb.dbapi.connections.Connection(path=None)
```

**Parameters**

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  | | --- | --- | --- | --- | | `path` str `None` Database file path. If None, uses in-memory database. Can be a file path like 'database.db' or None for ':memory:' | | | | | | | |

**Variables**

|  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Variable Type Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `encoding` str Character encoding for queries, defaults to 'utf8'|  |  |  | | --- | --- | --- | | `open` bool True if connection is open, False if closed | | | | | | | | |

**Examples**

```
>>> # In-memory database
>>> conn = Connection()
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchall()
>>> conn.close()
```

```
>>> # File-based database
>>> conn = Connection('mydata.db')
>>> with conn.cursor() as cur:
...     cur.execute("CREATE TABLE users (id INT, name STRING) ENGINE = MergeTree() order by id")
...     cur.execute("INSERT INTO users VALUES (1, 'Alice')")
>>> conn.close()
```

```
>>> # Context manager usage
>>> with Connection() as cur:
...     cur.execute("SELECT version()")
...     version = cur.fetchone()
```

Note

ClickHouse doesn't support traditional transactions, so commit() and rollback()
operations are no-ops but provided for DB-API compliance.

---

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

Close the database connection.