Python API Reference

- Table or column not found
- Table or index already exists when creating
- SQL syntax errors in statements
- Wrong number of parameters specified in prepared statements
- Invalid SQL operations (e.g., DROP on non-existent objects)
- Incorrect usage of database API methods

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`ProgrammingError`](#chdb-dbapi-err-programmingerror) When SQL statements or API usage contains errors | | | |

**Examples**

```
>>> # Table not found
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist
```

```
>>> # SQL syntax error
>>> cursor.execute("SELCT * FROM users")
ProgrammingError: You have an error in your SQL syntax
```

```
>>> # Wrong parameter count
>>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',))
ProgrammingError: Column count doesn't match value count
```

---

#### **exception** `chdb.dbapi.err.StandardError`[​](#chdb-dbapi-err-standarderror "Direct link to chdb-dbapi-err-standarderror")

Bases: `Exception`

Exception related to operation with chdb.

This is the base class for all chdb-related exceptions. It inherits from
Python’s built-in Exception class and serves as the root of the exception
hierarchy for database operations.

Note

This exception class follows the Python DB API 2.0 specification
for database exception handling.

---

#### **exception** `chdb.dbapi.err.Warning`[​](#chdb-dbapi-err-warning "Direct link to chdb-dbapi-err-warning")

Bases: [`StandardError`](#chdb-dbapi-err-standarderror)

Exception raised for important warnings like data truncations while inserting, etc.

This exception is raised when the database operation completes but with
important warnings that should be brought to the attention of the application.
Common scenarios include:

- Data truncation during insertion
- Precision loss in numeric conversions
- Character set conversion warnings

Note

This follows the Python DB API 2.0 specification for warning exceptions.

---

### Module Constants[​](#module-constants "Direct link to Module Constants")

#### `chdb.dbapi.apilevel = '2.0'`[​](#apilevel "Direct link to apilevel")

```
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.dbapi.threadsafety = 1`[​](#threadsafety "Direct link to threadsafety")

```
int([x]) -> integer
int(x, base=10) -> integer
```

Convert a number or string to an integer, or return 0 if no arguments
are given. If x is a number, return x.*\_int*\_(). For floating-point
numbers, this truncates towards zero.

If x isn't a number or if base is given, then x must be a string,
bytes, or bytearray instance representing an integer literal in the
given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded
by whitespace. The base defaults to 10. Valid bases are 0 and 2-36.
Base 0 means to interpret the base from the string as an integer literal.

```
>>> int(‘0b100’, base=0)
4
```

---

#### `chdb.dbapi.paramstyle = 'format'`[​](#paramstyle "Direct link to paramstyle")

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

---

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

#### `chdb.dbapi.STRING = frozenset({247, 253, 254})`[​](#string-type "Direct link to string-type")

Extended frozenset for DB-API 2.0 type comparison.

This class extends frozenset to support DB-API 2.0 type comparison semantics.
It allows for flexible type checking where individual items can be compared
against the set using both equality and inequality operators.

This is used for type constants like STRING, BINARY, NUMBER, etc. to enable
comparisons like “field\_type == STRING” where field\_type is a single type value.

**Examples**

```
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False
```

---

#### `chdb.dbapi.BINARY = frozenset({249, 250, 251, 252})`[​](#binary-type "Direct link to binary-type")

Extended frozenset for DB-API 2.0 type comparison.

This class extends frozenset to support DB-API 2.0 type comparison semantics.
It allows for flexible type checking where individual items can be compared
against the set using both equality and inequality operators.

This is used for type constants like STRING, BINARY, NUMBER, etc. to enable
comparisons like “field\_type == STRING” where field\_type is a single type value.

**Examples**

```
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False
```

---

#### `chdb.dbapi.NUMBER = frozenset({0, 1, 3, 4, 5, 8, 9, 13})`[​](#number-type "Direct link to number-type")

Extended frozenset for DB-API 2.0 type comparison.

This class extends frozenset to support DB-API 2.0 type comparison semantics.
It allows for flexible type checking where individual items can be compared
against the set using both equality and inequality operators.

This is used for type constants like STRING, BINARY, NUMBER, etc. to enable
comparisons like “field\_type == STRING” where field\_type is a single type value.

**Examples**

```
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False
```

---

#### `chdb.dbapi.DATE = frozenset({10, 14})`[​](#date-type "Direct link to date-type")

Extended frozenset for DB-API 2.0 type comparison.

This class extends frozenset to support DB-API 2.0 type comparison semantics.
It allows for flexible type checking where individual items can be compared
against the set using both equality and inequality operators.

This is used for type constants like STRING, BINARY, NUMBER, etc. to enable
comparisons like “field\_type == STRING” where field\_type is a single type value.

**Examples**

```
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False
```

---

#### `chdb.dbapi.TIME = frozenset({11})`[​](#time-type "Direct link to time-type")

Extended frozenset for DB-API 2.0 type comparison.

This class extends frozenset to support DB-API 2.0 type comparison semantics.
It allows for flexible type checking where individual items can be compared
against the set using both equality and inequality operators.

This is used for type constants like STRING, BINARY, NUMBER, etc. to enable
comparisons like “field\_type == STRING” where field\_type is a single type value.

**Examples**

```
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False
```

---

#### `chdb.dbapi.TIMESTAMP = frozenset({7, 12})`[​](#timestamp-type "Direct link to timestamp-type")

Extended frozenset for DB-API 2.0 type comparison.