Python API Reference

Read a specified number of rows from the given columns and return a list of objects,
where each object is a sequence of values for a column.

```
abstractmethod (col_names: List[str], count: int) → List[Any]
```

**Parameters**

|  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `col_names` `List[str]` List of column names to read|  |  |  | | --- | --- | --- | | `count` int Maximum number of rows to read | | | | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `List[Any]` List of sequences, one for each column | | | |

### **class** `chdb.rwabc.PyWriter`[​](#pywriter "Direct link to pywriter")

Bases: `ABC`

```
class chdb.rwabc.PyWriter(col_names: List[str], types: List[type], data: Any)
```

---

#### **abstractmethod** finalize[​](#finalize "Direct link to finalize")

Assemble and return the final data from blocks. Must be implemented by subclasses.

```
abstractmethod finalize() → bytes
```

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `bytes` The final serialized data | | | |

---

#### **abstractmethod** `write`[​](#write "Direct link to write")

Save columns of data to blocks. Must be implemented by subclasses.

```
abstractmethod write(col_names: List[str], columns: List[List[Any]]) → None
```

**Parameters**

|  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `col_names` `List[str]` List of column names that are being written|  |  |  | | --- | --- | --- | | `columns` `List[List[Any]]` List of columns data, each column is represented by a list | | | | | | | | |

## Exception Handling[​](#exception-handling "Direct link to Exception Handling")

### **class** `chdb.ChdbError`[​](#chdberror "Direct link to chdberror")

Bases: `Exception`

Base exception class for chDB-related errors.

This exception is raised when chDB query execution fails or encounters
an error. It inherits from the standard Python Exception class and
provides error information from the underlying ClickHouse engine.

The exception message typically contains detailed error information
from ClickHouse, including syntax errors, type mismatches, missing
tables/columns, and other query execution issues.

**Variables**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Variable Type Description|  |  |  | | --- | --- | --- | | `args` - Tuple containing the error message and any additional arguments | | | | | |

**Examples**

```
>>> try:
...     result = chdb.query("SELECT * FROM non_existent_table")
... except chdb.ChdbError as e:
...     print(f"Query failed: {e}")
Query failed: Table 'non_existent_table' doesn't exist
```

```
>>> try:
...     result = chdb.query("SELECT invalid_syntax FROM")
... except chdb.ChdbError as e:
...     print(f"Syntax error: {e}")
Syntax error: Syntax error near 'FROM'
```

Note

This exception is automatically raised by chdb.query() and related
functions when the underlying ClickHouse engine reports an error.
You should catch this exception when handling potentially failing
queries to provide appropriate error handling in your application.

## Version Information[​](#version-information "Direct link to Version Information")

### `chdb.chdb_version = ('3', '6', '0')`[​](#chdb-version "Direct link to chdb-version")

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple.
If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

---

### `chdb.engine_version = '25.5.2.1'`[​](#engine-version "Direct link to engine-version")

```
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
```

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.*\_str*\_() (if defined)
or repr(object).

- encoding defaults to ‘utf-8’.
- errors defaults to ‘strict’.

---

### `chdb.__version__ = '3.6.0'`[​](#version "Direct link to version")

```
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
```

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.*\_str*\_() (if defined)
or repr(object).

- encoding defaults to ‘utf-8’.
- errors defaults to ‘strict’.

- [Core Query Functions](#core-query-functions)
  - [`chdb.query`](#chdb-query)- [`chdb.sql`](#chdb_sql)- [`chdb.to_arrowTable`](#chdb-state-sqlitelike-to_arrowtable)- [`chdb.to_df`](#chdb_to_df)- [Connection and Session Management](#connection-session-management)
    - [`chdb.connect`](#chdb-connect)- [Exception Handling](#chdb-exceptions)
      - [**class** `chdb.ChdbError`](#chdb_chdbError)- [**class** `chdb.session.Session`](#chdb_session_session)- [State Management](#chdb-state-management)
        - [`chdb.state.connect`](#chdb_state_connect)- [**class** `chdb.state.sqlitelike.Connection`](#chdb-state-sqlitelike-connection)- [**class** `chdb.state.sqlitelike.StreamingResult`](#chdb-state-sqlitelike-streamingresult)- [**class** `chdb.state.sqlitelike.Cursor`](#chdb-state-sqlitelike-cursor)- [`chdb.state.sqlitelike`](#state-sqlitelike-to_arrowtable)- [`chdb.state.sqlitelike.to_df`](#state-sqlitelike-to_df)- [DataFrame Integration](#dataframe-integration)
          - [**class** `chdb.dataframe.Table`](#chdb-dataframe-table)- [Database API (DBAPI) 2.0 Interface](#database-api-interface)
            - [Core Functions](#core-functions)- [Type constructors](#type-constructors)- [Connection Class](#connection-class)- [Cursor Class](#cursor-class)- [Error Classes](#error-classes)- [Module Constants](#module-constants)- [Type Constants](#type-constants)- [User-Defined Functions (UDF)](#user-defined-functions)
              - [`chdb.udf.chdb_udf`](#chdb-udf)- [`chdb.udf.generate_udf`](#generate-udf)- [Utilities](#utilities)
                - [`chdb.utils.convert_to_columnar`](#convert-to-columnar)- [`chdb.utils.flatten_dict`](#flatten-dict)- [`chdb.utils.infer_data_type`](#infer-data-type)- [`chdb.utils.infer_data_types`](#infer-data-types)- [Abstract Base Classes](#abstract-base-classes)
                  - [**class** `chdb.rwabc.PyReader`(data: Any)`](#pyreader)- [**class** `chdb.rwabc.PyWriter`](#pywriter)- [Exception Handling](#exception-handling)
                    - [**class** `chdb.ChdbError`](#chdberror)- [Version Information](#version-information)
                      - [`chdb.chdb_version = ('3', '6', '0')`](#chdb-version)- [`chdb.engine_version = '25.5.2.1'`](#engine-version)- [`chdb.__version__ = '3.6.0'`](#version)

Was this page helpful?