> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Справочник по Python API chDB

> Полный справочник по Python API chDB

## Основные функции для запросов

### `chdb.query`

Выполняет SQL-запрос с помощью движка chDB.

Это основная функция для выполнения SQL-команд с использованием встроенного
движка ClickHouse. Поддерживает различные форматы вывода и может работать с временными
или файловыми базами данных.

**Синтаксис**

```python theme={null}
chdb.query(sql, output_format='CSV', path='', udf_path='')
```

**Параметры**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sql` | str | *required* | Строка SQL-запроса для выполнения |
| `output_format` | str | `"CSV"` | Формат вывода результатов. Поддерживаемые форматы: • `"CSV"` - значения, разделённые запятыми • `"JSON"` - формат JSON • `"Arrow"` - формат Apache Arrow • `"Parquet"` - формат Parquet • `"DataFrame"` - DataFrame в Pandas • `"ArrowTable"` - таблица PyArrow • `"Debug"` - включает подробное логирование |
| `path` | str | `""` | Путь к файлу базы данных. По умолчанию используется временная база данных, данные в которой не сохраняются (эквивалент `":memory:"`). Передайте путь к файлу для сохранения данных на диске |
| `udf_path` | str | `""` | Путь к устаревшему каталогу UDF на основе подпроцессов. Не требуется для нативного UDF Python ([`@func`](#func-decorator) / [`create_function`](#create-function)) |

**Возвращает**

Возвращает результат запроса в указанном формате:

| тип возвращаемого значения | Condition |
| - | - |
| `str` | Для текстовых форматов, таких как CSV и JSON |
| `pd.DataFrame` | Если `output_format` имеет значение `"DataFrame"` или `"dataframe"` |
| `pa.Table` | Если `output_format` имеет значение `"ArrowTable"` или `"arrowtable"` |
| объект результата chDB | Для остальных форматов |

**Вызывает**

| Исключение | Condition |
| - | - |
| `ChdbError` | Если выполнение SQL-запроса завершается ошибкой |
| `ImportError` | Если отсутствуют необходимые зависимости для форматов DataFrame/Arrow |

**Примеры**

```pycon theme={null}
>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"
```

```pycon theme={null}
>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello
```

```pycon theme={null}
>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")
```

***

### `chdb.sql`

Выполняет SQL-запрос с помощью движка chDB.

Это основная функция для выполнения SQL-команд с помощью встроенного
движка ClickHouse. Поддерживает различные форматы вывода и может работать с временными
или файловыми базами данных.

**Синтаксис**

```python theme={null}
chdb.sql(sql, output_format='CSV', path='', udf_path='')
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `sql` | str | *required* | Строка SQL-запроса для выполнения |
| `output_format` | str | `"CSV"` | Формат вывода результатов. Поддерживаемые форматы: • `"CSV"` - значения, разделённые запятыми • `"JSON"` - формат JSON • `"Arrow"` - формат Apache Arrow • `"Parquet"` - формат Parquet • `"DataFrame"` - DataFrame в Pandas • `"ArrowTable"` - таблица PyArrow • `"Debug"` - включает подробное логирование |
| `path` | str | `""` | Путь к файлу базы данных. По умолчанию используется временная, непостоянная база данных (эквивалент `":memory:"`). Передайте путь к файлу, чтобы сохранить данные на диске |
| `udf_path` | str | `""` | Путь к каталогу устаревших UDF на основе подпроцессов. Не требуется для нативных UDF Python ([`@func`](#func-decorator) / [`create_function`](#create-function)) |

**Возвращает**

Возвращает результат запроса в указанном формате:

| Тип возвращаемого значения | Условие |
| - | - |
| `str` | Для текстовых форматов, таких как CSV и JSON |
| `pd.DataFrame` | Если `output_format` имеет значение `"DataFrame"` или `"dataframe"` |
| `pa.Table` | Если `output_format` имеет значение `"ArrowTable"` или `"arrowtable"` |
| объект результата chDB | Для остальных форматов |

**Вызывает**

| Исключение | Условие |
| - | - |
| [`ChdbError`](#chdberror) | Если выполнение SQL-запроса завершается ошибкой |
| `ImportError` | Если отсутствуют необходимые зависимости для форматов DataFrame/Arrow |

**Примеры**

```pycon theme={null}
>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"
```

```pycon theme={null}
>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello
```

```pycon theme={null}
>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")
```

***

### `chdb.to_arrowTable`

Преобразует результат запроса в таблицу PyArrow.

Преобразует результат запроса chDB в таблицу PyArrow для эффективной обработки данных в столбцовом формате.
Возвращает пустую таблицу, если результат отсутствует.

**Синтаксис**

```python theme={null}
chdb.to_arrowTable(res)
```

**Параметры**

| Параметр | Описание |
| - | - |
| `res` | объект результата запроса chDB, содержащий бинарные данные Arrow |

**Возвращаемое значение**

| Тип возвращаемого значения | Описание |
| - | - |
| `pa.Table` | таблица PyArrow с результатами запроса |

**Исключения**

| Тип ошибки | Описание |
| - | - |
| `ImportError` | Если pyarrow или pandas не установлены |

**Пример**

```pycon theme={null}
>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> table = chdb.to_arrowTable(result)
>>> print(table.to_pandas())
   id    msg
0   1  hello
```

***

### `chdb.to_df`

Преобразует результат запроса в pandas DataFrame.

Преобразует результат запроса chDB в pandas DataFrame: сначала в таблицу PyArrow, а затем в pandas с использованием многопоточности для повышения производительности.

**Синтаксис**

```python theme={null}
chdb.to_df(r)
```

**Параметры**

| Параметр | Описание |
| - | - |
| `r` | объект результата запроса chDB, содержащий бинарные данные Arrow |

**Возвращаемое значение**

| Тип возвращаемого значения | Описание |
| - | - |
| `pd.DataFrame` | DataFrame pandas, содержащий результаты запроса |

**Исключения**

| Исключение | Условие |
| - | - |
| `ImportError` | Если pyarrow или pandas не установлены |

**Пример**

```pycon theme={null}
>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> df = chdb.to_df(result)
>>> print(df)
   id    msg
0   1  hello
```

## Управление соединениями и сеансами

Доступны следующие функции сеанса:

### `chdb.connect`

Создаёт соединение с фоновым сервером chDB.

Эта функция устанавливает [соединение](#chdb-state-sqlitelike-connection) с движком базы данных chDB (ClickHouse).
Каждый вызов возвращает независимое соединение, при этом одновременно может быть открыто любое количество соединений с одним и тем же путём к базе данных.

```python theme={null}
chdb.connect(connection_string: str = ':memory:') → Connection
```

**Параметры:**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `connection_string` | str | `":memory:"` | Строка подключения к базе данных. См. форматы ниже. |

**Базовые форматы**

| Формат | Описание |
| - | - |
| `":memory:"` | Временная база данных (по умолчанию) |
| `"test.db"` | Файл базы данных по относительному пути |
| `"file:test.db"` | То же, что относительный путь |
| `"/path/to/test.db"` | Файл базы данных по абсолютному пути |
| `"file:/path/to/test.db"` | То же, что абсолютный путь |

**С параметрами запроса**

| Формат | Описание |
| - | - |
| `"file:test.db?param1=value1&param2=value2"` | Относительный путь с параметрами |
| `"file::memory:?verbose&log-level=test"` | Временная база с параметрами |
| `"///path/to/test.db?param1=value1&param2=value2"` | Абсолютный путь с параметрами |

**Обработка параметров запроса**

Параметры запроса передаются в движок ClickHouse как аргументы запуска.
Специальная обработка параметров:

| Специальный параметр | Преобразуется в | Описание |
| - | - | - |
| `mode=ro` | `--readonly=1` | Режим только для чтения |
| `verbose` | (флаг) | Включает подробное логирование |
| `log-level=test` | (настройка) | Задаёт уровень логирования |

Полный список параметров см. в `clickhouse local --help --verbose`

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| `Connection` | Объект подключения к базе данных, который поддерживает: • создание курсоров через `Connection.cursor()` • выполнение запросов напрямую через `Connection.query()` • потоковые запросы через `Connection.send_query()` • протокол менеджера контекста для автоматической очистки |

**Вызывает**

| Исключение | Условие |
| - | - |
| `RuntimeError` | Если не удалось подключиться к базе данных |

> [!NOTE]
>
> В одном процессе может работать один встроенный движок, привязанный к одному пути базы данных. Несколько подключений к одному и тому же пути могут сосуществовать и выполнять запросы одновременно. Если при наличии открытого подключения открыть *другой* путь, возникнет `RuntimeError`; сначала закройте открытые подключения.

**Примеры**

```pycon theme={null}
>>> # Temporary database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed
```

**См. также**

* [`Connection`](#chdb-state-sqlitelike-connection) — класс подключения к базе данных
* [`Cursor`](#chdb-state-sqlitelike-cursor) — курсор базы данных для операций DB-API 2.0

## Обработка исключений

### **class** `chdb.ChdbError`

Базовый класс: `Exception`

Базовый класс исключений для ошибок, связанных с chDB.

Это исключение возникает, когда выполнение запроса chDB завершается с ошибкой
или в процессе возникает ошибка. Оно наследуется от стандартного класса Python Exception и
предоставляет информацию об ошибке от базового движка ClickHouse.

***

### **class** `chdb.session.Session`

Базовый класс: `object`

Сеанс сохраняет состояние запроса.
Если path имеет значение None, сеанс использует общую для всего процесса временную базу данных (`:memory:`), поэтому все сеансы без path видят таблицы друг друга; её временный каталог удаляется только при закрытии последнего такого сеанса или подключения.
Вы также можете передать path, чтобы создать базу данных по этому пути, где будут храниться ваши данные.

Вы также можете использовать строку подключения, чтобы передать path и другие параметры.

```python theme={null}
class chdb.session.Session(path=None)
```

**Примеры**

| Строка подключения | Описание |
| - | - |
| `":memory:"` | Временная база данных |
| `"test.db"` | Относительный путь |
| `"file:test.db"` | То же, что и выше |
| `"/path/to/test.db"` | Абсолютный путь |
| `"file:/path/to/test.db"` | То же, что и выше |
| `"file:test.db?param1=value1&param2=value2"` | Относительный путь с параметрами запроса |
| `"file::memory:?verbose&log-level=test"` | Временная база данных с параметрами запроса |
| `"///path/to/test.db?param1=value1&param2=value2"` | Абсолютный путь с параметрами запроса |

> [!NOTE]
>
> **Обработка аргументов строки подключения**
>
> Строки подключения, содержащие параметры запроса, например “[file:test.db?param1=value1\&param2=value2](file:test.db?param1=value1\&param2=value2)”, передают
> “param1=value1” движку ClickHouse в качестве аргументов запуска.
>
> Подробнее см. `clickhouse local –help –verbose`
>
> Обработка некоторых специальных аргументов:
>
> * “mode=ro” будет преобразован в “–readonly=1” для ClickHouse (режим только для чтения)

> [!NOTE]
>
> **Важно**
>
> * Несколько сеансов могут сосуществовать, если используют один и тот же путь к базе данных.
> * Чтобы использовать другой путь к базе данных, сначала закройте открытые сеансы.

***

#### `cleanup`

Очистка ресурсов сеанса с обработкой исключений.

Этот метод пытается закрыть сеанс, подавляя все исключения,
которые могут возникнуть в процессе очистки. Он особенно полезен в
сценариях обработки ошибок или когда нужно гарантировать выполнение очистки
независимо от состояния сеанса.

**Синтаксис**

```python theme={null}
cleanup()
```

> [!NOTE]
>
> Этот метод никогда не сгенерирует исключение, поэтому его можно безопасно вызывать в
> блоках finally или в деструкторах.

**Примеры**

```pycon theme={null}
>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Безопасная очистка независимо от ошибок
```

**См. также**

* [`close()`](#chdb-session-session-close) - Для явного закрытия сеанса с пробросом ошибок

***

#### `close`

Закрывает сеанс и освобождает ресурсы.

Этот метод закрывает базовое соединение и сбрасывает глобальное состояние сеанса.
После вызова этого метода сеанс становится недействительным, и его нельзя использовать для
дальнейших запросов.

**Синтаксис**

```python theme={null}
close()
```

> [!NOTE]
>
> Этот метод автоматически вызывается, когда сеанс используется в качестве менеджера контекста
> или когда объект сеанса уничтожается.

> [!WARNING]
>
> **Важно**
>
> Любая попытка использовать сеанс после вызова `close()` приведёт к ошибке.

**Примеры**

```pycon theme={null}
>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close()  # Явно закрываем сеанс
```

***

#### `query`

Выполняет SQL-запрос и возвращает результаты.

Этот метод выполняет SQL-запрос к базе данных текущего сеанса и возвращает
результаты в указанном формате. Метод поддерживает различные форматы вывода
и сохраняет состояние сеанса между запросами.

**Синтаксис**

```python theme={null}
query(sql, fmt='CSV', udf_path='')
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `sql` | str | *обязательно* | Строка SQL-запроса для выполнения |
| `fmt` | str | `"CSV"` | Формат вывода результатов. Доступные форматы: • `"CSV"` - значения, разделённые запятыми • `"JSON"` - формат JSON • `"TabSeparated"` - значения, разделённые символами табуляции • `"Pretty"` - табличный формат Pretty • `"JSONCompact"` - компактный формат JSON • `"Arrow"` - формат Apache Arrow • `"Parquet"` - формат Parquet |
| `udf_path` | str | `""` | Путь к каталогу устаревших UDF на основе подпроцессов. Не требуется для нативных Python UDF ([`@func`](#func-decorator) / [`create_function`](#create-function)). Если не указан, используется путь к UDF, заданный при инициализации сеанса |

**Возвращает**

Возвращает результаты запроса в указанном формате.
Точный возвращаемый тип зависит от параметра `fmt`:

* Строковые форматы (CSV, JSON и т. д.) возвращают str
* Двоичный формат (Arrow, Parquet) возвращает bytes

**Исключения**

| Исключение | Условие |
| - | - |
| `RuntimeError` | Если сеанс закрыт или недействителен |
| `ValueError` | Если SQL-запрос имеет неверный формат |

> [!NOTE]
>
> Формат «Debug» не поддерживается и будет автоматически преобразован
> в «CSV» с предупреждением.
> Для отладки используйте параметры строки подключения.

> [!WARNING]
>
> **Предупреждение**
>
> Этот метод выполняет запрос синхронно и загружает все результаты в
> память. Для больших результирующих наборов рассмотрите возможность использования [`send_query()`](#chdb-session-session-send_query) для
> стриминга результатов.

**Примеры**

```pycon theme={null}
>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1
```

```pycon theme={null}
>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}
```

```pycon theme={null}
>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob
```

**См. также**

* [`send_query()`](#chdb-session-session-send_query) — Для потокового выполнения запросов
* [`sql`](#chdb-session-session-sql) — Псевдоним этого метода

***

#### `send_query`

Выполняет SQL-запрос и возвращает итератор для потокового получения результатов.

Этот метод выполняет SQL-запрос к базе данных сеанса и возвращает
объект потокового результата, который позволяет перебирать результаты, не
загружая всё в память сразу. Это особенно полезно для больших
результирующих наборов.

**Синтаксис**

```python theme={null}
send_query(sql, fmt='CSV') → StreamingResult
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `sql` | str | *required* | Строка SQL-запроса для выполнения |
| `fmt` | str | `"CSV"` | Формат вывода результатов. Доступные форматы: • `"CSV"` - значения, разделённые запятыми • `"JSON"` - формат JSON • `"TabSeparated"` - значения, разделённые табуляцией • `"JSONCompact"` - компактный формат JSON • `"Arrow"` - формат Apache Arrow • `"Parquet"` - формат Parquet |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `StreamingResult` | Итератор потоковых результатов, который возвращает результаты запроса по мере поступления. Итератор можно использовать в циклах for или преобразовывать в другие структуры данных |

**Вызывает исключения**

| Исключение | Условие |
| - | - |
| `RuntimeError` | Если сеанс закрыт или недействителен |
| `ValueError` | Если SQL-запрос имеет неверный формат |

> [!NOTE]
>
> Формат «Debug» не поддерживается и будет автоматически преобразован
> в «CSV» с предупреждением. Для отладки используйте параметры строки подключения.

> [!WARNING]
>
> Возвращаемый объект StreamingResult следует использовать без задержки или сохранить должным образом, так как он сохраняет подключение к базе данных.

**Примеры**

```pycon theme={null}
>>> session = Session("test.db")
>>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id")
>>>
>>> # Вставка большого набора данных
>>> for i in range(1000):
...     session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')")
>>>
>>> # Потоковая передача результатов во избежание проблем с памятью
>>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id")
>>> for chunk in streaming_result:
...     print(f"Processing chunk: {len(chunk)} bytes")
...     # Обработка фрагмента без загрузки всего результирующего набора
```

```pycon theme={null}
>>> # Using with context manager
>>> with session.send_query("SELECT COUNT(*) FROM big_table") as stream:
...     for result in stream:
...         print(f"Count result: {result}")
```

**См. также**

* [`query()`](#chdb-session-session-query) — для выполнения запросов без использования стриминга
* `chdb.state.sqlitelike.StreamingResult` — итератор результатов стриминга

***

#### `sql`

Выполняет SQL-запрос и возвращает результаты.

Этот метод выполняет SQL-запрос к базе данных текущего сеанса и возвращает
результаты в указанном формате. Метод поддерживает различные выходные форматы
и сохраняет состояние сеанса между запросами.

**Синтаксис**

```python theme={null}
sql(sql, fmt='CSV', udf_path='')
```

**Параметры**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sql` | str | *required* | Строка SQL-запроса для выполнения |
| `fmt` | str | `"CSV"` | Формат вывода результатов. Доступные форматы: • `"CSV"` - значения, разделённые запятыми • `"JSON"` - формат JSON • `"TabSeparated"` - значения, разделённые символами табуляции • `"Pretty"` - табличный формат Pretty • `"JSONCompact"` - компактный формат JSON • `"Arrow"` - формат Apache Arrow • `"Parquet"` - формат Parquet |
| `udf_path` | str | `""` | Путь к каталогу устаревших UDF на основе подпроцессов. Не требуется для нативных UDF Python ([`@func`](#func-decorator) / [`create_function`](#create-function)). Если не указан, используется путь UDF, заданный при инициализации сеанса |

**Возвращает**

Возвращает результаты запроса в указанном формате.
Точный тип возвращаемого значения зависит от параметра формата:

* Строковые форматы (CSV, JSON и т. д.) возвращают str
* Двоичные форматы (Arrow, Parquet) возвращают bytes

**Вызывает:**

| Исключение | Condition |
| - | - |
| `RuntimeError` | Если сеанс закрыт или недействителен |
| `ValueError` | Если SQL-запрос имеет неверный формат |

> [!NOTE]
>
> Формат “Debug” не поддерживается и будет автоматически преобразован
> в “CSV” с предупреждением. Для отладки используйте параметры строки подключения
> вместо него.

> [!WARNING]
>
> **Предупреждение**
>
> Этот method выполняет запрос синхронно и загружает все результаты в
> память.
> Для больших результирующих наборов лучше использовать [`send_query()`](#chdb-session-session-send_query) для стриминга результатов.

**Примеры**

```pycon theme={null}
>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1
```

```pycon theme={null}
>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}
```

```pycon theme={null}
>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = MergeTree() order by id")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob
```

**См. также**

* [`send_query()`](#chdb-session-session-send_query) — Для потокового выполнения запросов
* [`sql`](#chdb-session-session-sql) — Псевдоним этого метода

## Управление состоянием

### `chdb.state.connect`

Создаёт [подключение](#chdb-state-sqlitelike-connection) к фоновому серверу chDB.

Эта функция устанавливает подключение к движку базы данных chDB (ClickHouse).
Каждый вызов возвращает независимое подключение, при этом одновременно может быть открыто любое количество подключений к одной и той же базе данных.

**Синтаксис**

```python theme={null}
chdb.state.connect(connection_string: str = ':memory:') → Connection
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `connection_string(str, optional)` | str | `":memory:"` | Строка подключения к базе данных. См. форматы ниже. |

**Базовые форматы**

Поддерживаемые форматы строки подключения:

| Формат | Описание |
| - | - |
| `":memory:"` | База данных в памяти (по умолчанию) |
| `"test.db"` | Файл базы данных по относительному пути |
| `"file:test.db"` | То же, что и относительный путь |
| `"/path/to/test.db"` | Файл базы данных по абсолютному пути |
| `"file:/path/to/test.db"` | То же, что и абсолютный путь |

**С параметрами запроса**

| Формат | Описание |
| - | - |
| `"file:test.db?param1=value1&param2=value2"` | Относительный путь с параметрами |
| `"file::memory:?verbose&log-level=test"` | База в памяти с параметрами |
| `"///path/to/test.db?param1=value1&param2=value2"` | Абсолютный путь с параметрами |

**Обработка параметров запроса**

Параметры запроса передаются движку ClickHouse как аргументы запуска.
Специальная обработка параметров:

| Специальный параметр | Преобразуется в | Описание |
| - | - | - |
| `mode=ro` | `--readonly=1` | Режим только для чтения |
| `verbose` | (флаг) | Включает подробное логирование |
| `log-level=test` | (настройка) | Задает уровень логирования |

Полный список параметров см. в `clickhouse local --help --verbose`

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `Connection` | Объект подключения к базе данных, который поддерживает: • Создание курсоров через `Connection.cursor()` • Прямые запросы через `Connection.query()` • Стриминговые запросы через `Connection.send_query()` • Протокол менеджера контекста для автоматического освобождения ресурсов |

**Выбрасывает исключения**

| Исключение | Условие |
| - | - |
| `RuntimeError` | Если не удалось подключиться к базе данных |

> [!NOTE]
>
> В рамках одного процесса запускается один встроенный движок, привязанный к одному пути к базе данных. Несколько подключений к одному пути могут существовать одновременно и выполнять запросы параллельно. Открытие *другого* пути, пока открыто хотя бы одно подключение, вызывает `RuntimeError`; сначала закройте открытые подключения.

**Примеры**

```pycon theme={null}
>>> # Temporary database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed
```

**См. также**

* `Connection` — класс подключения к базе данных
* `Cursor` — курсор базы данных для операций DB-API 2.0

### **class** `chdb.state.sqlitelike.Connection`

Базовый класс: `object`

**Синтаксис**

```python theme={null}
class chdb.state.sqlitelike.Connection(connection_string: str)
```

***

#### `close`

Закрывает подключение и освобождает ресурсы.

Этот метод закрывает подключение к базе данных и освобождает все связанные с ним
ресурсы, включая активные курсоры. После вызова этого метода
подключение становится недействительным и не может использоваться для дальнейших операций.

**Синтаксис**

```python theme={null}
close() → None
```

> [!NOTE]
>
> Этот метод идемпотентен — его можно безопасно вызывать несколько раз.

> [!WARNING]
>
> **Предупреждение**
>
> Все выполняющиеся в данный момент потоковые запросы будут отменены при закрытии подключения.
> Убедитесь, что все важные данные обработаны до его закрытия.

**Примеры**

```pycon theme={null}
>>> conn = connect("test.db")
>>> # Использовать подключение для запросов
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Закрыть после завершения
>>> conn.close()
```

```pycon theme={null}
>>> # Использование с контекстным менеджером (автоматическая очистка)
>>> with connect("test.db") as conn:
...     conn.query("SELECT 1")
...     # Подключение закрывается автоматически
```

***

#### `cursor`

Создаёт объект [Cursor](#chdb-state-sqlitelike-cursor) для выполнения запросов.

Этот метод создаёт курсор базы данных, предоставляющий стандартный
интерфейс DB-API 2.0 для выполнения запросов и получения результатов.
Курсор позволяет более гибко управлять выполнением запросов
и извлечением результатов.

**Синтаксис**

```python theme={null}
cursor() → Cursor
```

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `Cursor` | Объект курсора для операций с базой данных |

> [!NOTE]
>
> При создании нового курсора любой существующий курсор,
> связанный с этим подключением, будет заменён. Для одного подключения поддерживается только один курсор.

**Примеры**

```pycon theme={null}
>>> conn = connect(":memory:")
>>> cursor = conn.cursor()
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)
```

**См. также**

* [`Cursor`](#chdb-state-sqlitelike-cursor) — Реализация курсора для работы с базой данных

***

#### `query`

Выполняет SQL-запрос и возвращает результат целиком.

Этот метод синхронно выполняет SQL-запрос и возвращает полный
результирующий набор. Он поддерживает различные форматы вывода и автоматически выполняет
постобработку в зависимости от формата.

**Синтаксис**

```python theme={null}
query(query: str, format: str = 'CSV') → Any
```

**Параметры:**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `query` | str | *required* | SQL-запрос для выполнения |
| `format` | str | `"CSV"` | Формат вывода результатов. Поддерживаемые форматы: • `"CSV"` - значения, разделённые запятыми (string) • `"JSON"` - формат JSON (string) • `"Arrow"` - формат Apache Arrow (bytes) • `"Dataframe"` - Pandas DataFrame (требуется pandas) • `"Arrowtable"` - таблица PyArrow (требуется pyarrow) |

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| `str` | Для строковых форматов (CSV, JSON) |
| `bytes` | Для формата Arrow |
| `pandas.DataFrame` | Для формата dataframe |
| `pyarrow.Table` | Для формата arrowtable |

**Вызывает исключения**

| Исключение | Условие |
| - | - |
| `RuntimeError` | Если выполнение запроса завершается ошибкой |
| `ImportError` | Если не установлены пакеты, необходимые для формата |

> [!WARNING]
>
> **Предупреждение**
>
> Этот метод загружает в память весь результирующий набор. Для больших
> результатов рекомендуется использовать [`send_query()`](#chdb-state-sqlitelike-connection-send_query) со стримингом.

**Примеры**

```pycon theme={null}
>>> conn = connect(":memory:")
>>>
>>> # Простой CSV-запрос
>>> result = conn.query("SELECT 1 as num, 'hello' as text")
>>> print(result)
num,text
1,hello
```

```pycon theme={null}
>>> # Формат DataFrame
>>> df = conn.query("SELECT number FROM numbers(5)", "dataframe")
>>> print(df)
   number
0       0
1       1
2       2
3       3
4       4
```

**См. также**

* [`send_query()`](#chdb-state-sqlitelike-connection-send_query) — Для выполнения запросов в потоковом режиме

***

#### `send_query`

Выполняет SQL-запрос и возвращает итератор потокового результата.

Этот метод выполняет SQL-запрос и возвращает объект StreamingResult,
который позволяет перебирать результаты, не загружая всё
сразу в память. Это идеально подходит для обработки больших результирующих наборов.

**Синтаксис**

```python theme={null}
send_query(query: str, format: str = 'CSV') → StreamingResult
```

**Параметры**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | str | *required* | Строка SQL-запроса для выполнения |
| `format` | str | `"CSV"` | Выходной формат результатов. Поддерживаемые форматы: • `"CSV"` - значения, разделённые запятыми • `"JSON"` - формат JSON • `"Arrow"` - формат Apache Arrow (включает метод record\_batch()) • `"dataframe"` - фрагменты Pandas DataFrame • `"arrowtable"` - фрагменты PyArrow Table |

**Возвращает**

| Return Type | Description |
| - | - |
| `StreamingResult` | Потоковый итератор результатов запроса, который поддерживает: • Протокол итератора (циклы for) • Протокол менеджера контекста (операторы with) • Ручное получение данных с помощью метода fetch() • Потоковую передачу PyArrow RecordBatch (только для формата Arrow) |

**Вызывает**

| Exception | Condition |
| - | - |
| `RuntimeError` | Если выполнение запроса завершается ошибкой |
| `ImportError` | Если не установлены пакеты, необходимые для формата |

> [!NOTE]
>
> Только формат «Arrow» поддерживает метод `record_batch()` у возвращаемого StreamingResult.

**Примеры**

```pycon theme={null}
>>> conn = connect(":memory:")
>>>
>>> # Базовый стриминг
>>> stream = conn.send_query("SELECT number FROM numbers(1000)")
>>> for chunk in stream:
...     print(f"Обработка фрагмента: {len(chunk)} байт")
```

```pycon theme={null}
>>> # Использование контекстного менеджера для освобождения ресурсов
>>> with conn.send_query("SELECT * FROM large_table") as stream:
...     chunk = stream.fetch()
...     while chunk:
...         process_data(chunk)
...         chunk = stream.fetch()
```

```pycon theme={null}
>>> # Формат Arrow с потоковой передачей RecordBatch
>>> stream = conn.send_query("SELECT * FROM data", "Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Batch shape: {batch.num_rows} x {batch.num_columns}")
```

**См. также**

* [`query()`](#chdb-state-sqlitelike-connection-query) — для выполнения запросов без стриминга
* [`StreamingResult`](#chdb-state-sqlitelike-streamingresult) — итератор для потоковых результатов

***

### **class** `chdb.state.sqlitelike.StreamingResult`

Базовый класс: `object`

Итератор потоковых результатов для обработки больших результатов запросов.

Этот класс предоставляет интерфейс итератора для потоковой обработки результатов запросов без
загрузки всего результирующего набора в память. Он поддерживает различные выходные форматы
и предоставляет методы для ручного получения результатов и потоковой передачи батчей PyArrow RecordBatch.

```python theme={null}
class chdb.state.sqlitelike.StreamingResult
```

***

#### `fetch`

Возвращает следующий фрагмент результатов стриминга.

Этот метод возвращает следующий доступный фрагмент данных из результата потокового
запроса. Формат возвращаемых данных зависит от формата, указанного
при запуске потокового запроса.

**Синтаксис**

```python theme={null}
fetch() → Any
```

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| `str` | Для текстовых форматов (CSV, JSON) |
| `bytes` | Для двоичных форматов (Arrow, Parquet) |
| `None` | Когда поток результатов исчерпан |

**Примеры**

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

***

#### `cancel`

Отменяет потоковый запрос и освобождает ресурсы.

Этот метод отменяет любой выполняемый потоковый запрос и освобождает связанные с ним
ресурсы. Его следует вызывать, если вы хотите прекратить обработку результатов
до завершения потока.

**Синтаксис**

```python theme={null}
cancel() → None
```

**Примеры**

```pycon theme={null}
>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Обрабатываем только первые 10 фрагментов
...         stream.cancel()
...         break
...     process_data(chunk)
```

***

#### `close`

Закрывает потоковый результат и освобождает ресурсы.

Псевдоним для [`cancel()`](#streamingresult-cancel). Закрывает итератор потокового результата
и освобождает все связанные с ним ресурсы.

**Синтаксис**

```python theme={null}
close() → None
```

***

#### `record_batch`

Создает PyArrow RecordBatchReader для эффективной пакетной обработки.

Этот метод создает PyArrow RecordBatchReader, который позволяет эффективно
перебирать результаты запроса в формате Arrow. Это наиболее
эффективный способ обрабатывать большие результирующие наборы при использовании PyArrow.

**Синтаксис**

```python theme={null}
record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `rows_per_batch` | int | `1000000` | Число строк в батче |

**Возвращаемое значение**

| Возвращаемый тип | Описание |
| - | - |
| `pa.RecordBatchReader` | PyArrow RecordBatchReader для перебора батчей |

> [!NOTE]
>
> Этот метод доступен только в том случае, если потоковый запрос был
> инициирован с `format="Arrow"`. При использовании с другими форматами будет вызвана ошибка.

**Примеры**

```pycon theme={null}
>>> 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)
```

***

#### Протокол итерации

StreamingResult поддерживает протокол итерации Python, поэтому его можно
использовать напрямую в циклах for:

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

***

#### Протокол контекстного менеджера

StreamingResult поддерживает протокол контекстного менеджера для автоматического
освобождения ресурсов:

```pycon theme={null}
>>> with conn.send_query("SELECT * FROM data") as stream:
...     for chunk in stream:
...         process(chunk)
>>> # Поток автоматически закрыт
```

***

### **класс** `chdb.state.sqlitelike.Cursor`

Базовый класс: `object`

```python theme={null}
class chdb.state.sqlitelike.Cursor(connection)
```

***

#### `close`

Закрывает курсор и освобождает ресурсы.

Этот метод закрывает курсор и освобождает все связанные с ним ресурсы.
После вызова этого метода курсор становится недействительным и не может
использоваться для выполнения дальнейших операций.

**Синтаксис**

```python theme={null}
close() → None
```

> [!NOTE]
>
> Этот метод идемпотентен — его можно безопасно вызывать несколько раз.
> При закрытии соединения курсор также закрывается автоматически.

**Примеры**

```pycon theme={null}
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Освобождаем ресурсы курсора
```

***

#### `column_names`

Возвращает список имён столбцов из последнего выполненного запроса.

Этот метод возвращает имена столбцов из последнего выполненного
запроса SELECT. Имена возвращаются в том же порядке, в котором они
указаны в результирующем наборе.

**Синтаксис**

```python theme={null}
column_names() → list
```

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `list` | Список строк с именами столбцов или пустой список, если запрос не выполнялся или не вернул ни одного столбца |

**Примеры**

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

**См. также**

* [`column_types()`](#chdb-state-sqlitelike-cursor-column_types) — Получить информацию о типах столбцов
* [`description`](#chdb-state-sqlitelike-cursor-description) — описание столбца в DB-API 2.0

***

#### `column_types`

Возвращает список типов столбцов из последнего выполненного запроса.

Этот метод возвращает имена типов столбцов ClickHouse из самого
недавно выполненного SELECT-запроса. Типы возвращаются в том же
порядке, в котором они представлены в результирующем наборе.

**Синтаксис**

```python theme={null}
column_types() → list
```

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `list` | Список строк с именами типов ClickHouse либо пустой список, если запрос не выполнялся или не вернул ни одного столбца |

**Примеры**

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

**См. также**

* [`column_names()`](#chdb-state-sqlitelike-cursor-column_names) — получить информацию об именах столбцов
* [`description`](#chdb-state-sqlitelike-cursor-description) — описание столбцов в DB-API 2.0

***

#### `commit`

Зафиксировать любую незавершённую транзакцию.

Этот метод фиксирует любую незавершённую транзакцию базы данных. В ClickHouse
большинство операций фиксируются автоматически, но этот метод предусмотрен
для совместимости с DB-API 2.0.

> [!NOTE]
>
> В ClickHouse операции обычно фиксируются автоматически, поэтому явная фиксация
> обычно не требуется. Этот метод предусмотрен для совместимости
> со стандартным сценарием работы DB-API 2.0.

**Синтаксис**

```python theme={null}
commit() → None
```

**Примеры**

```pycon theme={null}
>>> cursor = conn.cursor()
>>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
>>> cursor.commit()
```

***

#### `свойство description : list`

Возвращает описание столбцов в соответствии со спецификацией DB-API 2.0.

Это свойство возвращает список 7-элементных кортежей, описывающих каждый столбец
в результирующем наборе последнего выполненного запроса SELECT. Каждый кортеж содержит:
(name, type\_code, display\_size, internal\_size, precision, scale, null\_ok)

В настоящее время заполняются только поля name и type\_code, а для остальных установлено значение None.

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `list` | Список 7-элементных кортежей, описывающих каждый столбец, или пустой список, если не был выполнен ни один запрос SELECT |

> [!NOTE]
>
> Это соответствует спецификации DB-API 2.0 для cursor.description.
> Только первые два элемента (name и type\_code) содержат значимые
> данные в данной реализации.

**Примеры**

```pycon theme={null}
>>> 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
```

**См. также**

* [`column_names()`](#chdb-state-sqlitelike-cursor-column_names) — Получить только имена столбцов
* [`column_types()`](#chdb-state-sqlitelike-cursor-column_types) — Получить только типы столбцов

***

#### `execute`

Выполняет SQL-запрос и подготавливает результаты для получения.

Этот метод выполняет SQL-запрос и подготавливает результаты для дальнейшего получения
с помощью методов fetch. Он обрабатывает разбор данных результата и
автоматическое преобразование типов данных ClickHouse.

**Синтаксис**

```python theme={null}
execute(query: str) → None
```

**Параметры:**

| Parameter | Type | Description |
| - | - | - |
| `query` | str | Строка SQL-запроса для выполнения |

**Исключения**

| Exception | Condition |
| - | - |
| `Exception` | Если при выполнении запроса возникает ошибка или не удается разобрать результат |

> [!NOTE]
>
> Этот метод соответствует спецификации DB-API 2.0 для `cursor.execute()`.
> После выполнения используйте `fetchone()`, `fetchmany()` или `fetchall()`,
> чтобы получить результаты.

> [!NOTE]
>
> Метод автоматически преобразует типы данных ClickHouse в соответствующие
> типы Python:
>
> * Int/UInt types → int
> * Float types → float
> * String/FixedString → str
> * DateTime → datetime.datetime
> * Date → datetime.date
> * Bool → bool

**Примеры**

```pycon theme={null}
>>> cursor = conn.cursor()
>>>
>>> # Выполнение DDL
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>>
>>> # Выполнение DML
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>>
>>> # Выполнение SELECT и получение результатов
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)
```

**См. также**

* [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) — Получить одну строку
* [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) — Получить несколько строк
* [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) — Получить все оставшиеся строки

***

#### `fetchall`

Получает все оставшиеся строки из результата запроса.

Этот метод возвращает все оставшиеся строки из текущего набора
результатов запроса, начиная с текущей позиции курсора. Он возвращает кортеж
кортежей строк с соответствующим преобразованием в типы Python.

**Синтаксис**

```python theme={null}
fetchall() → tuple
```

**Возвращает:**

| Возвращаемый тип | Описание |
| - | - |
| `tuple` | Кортеж, содержащий все оставшиеся кортежи строк из результирующего набора. Возвращает пустой кортеж, если доступных строк нет |

> [!WARNING]
>
> **Предупреждение**
>
> Этот метод загружает в память сразу все оставшиеся строки. Для больших
> результирующих наборов рекомендуется использовать [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany), чтобы обрабатывать результаты
> батчами.

**Примеры**

```pycon theme={null}
>>> 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}")
```

**См. также**

* [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) - Выборка одной строки
* [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - Выборка нескольких строк батчами

***

#### `fetchmany`

Извлекает несколько строк из результата запроса.

Этот метод извлекает до ‘size’ строк из текущего набора результатов
запроса. Он возвращает кортеж кортежей строк, где каждая строка содержит значения столбцов
с соответствующим преобразованием в типы Python.

**Синтаксис**

```python theme={null}
fetchmany(size: int = 1) → tuple
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `size` | int | `1` | Максимальное количество строк для выборки |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `tuple` | Tuple, содержащий до 'size' кортежей строк. Может содержать меньше строк, если результирующий набор исчерпан |

> [!NOTE]
>
> Этот метод соответствует спецификации DB-API 2.0. Он вернет меньше
> чем ‘size’ строк, если результирующий набор исчерпан.

**Примеры**

```pycon theme={null}
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Обработка результатов батчами
>>> while True:
...     batch = cursor.fetchmany(100)  # Получить 100 строк за раз
...     if not batch:
...         break
...     process_batch(batch)
```

**См. также**

* [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) — Получить одну строку
* [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) — Получить все оставшиеся строки

***

#### `fetchone`

Извлекает следующую строку из результата запроса.

Этот метод извлекает следующую доступную строку из текущего
результирующего набора запроса. Он возвращает кортеж со значениями столбцов
с соответствующим преобразованием к типам Python.

**Синтаксис**

```python theme={null}
fetchone() → tuple | None
```

**Возвращает:**

| Тип возвращаемого значения | Описание |
| - | - |
| `Optional[tuple]` | Следующая строка в виде кортежа значений столбцов или None, если доступных строк больше нет |

> [!NOTE]
>
> Этот метод соответствует спецификации DB-API 2.0. Значения столбцов
> автоматически преобразуются в соответствующие типы Python в зависимости от
> типов столбцов ClickHouse.

**Примеры**

```pycon theme={null}
>>> 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()
```

**См. также**

* [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - Получить несколько строк
* [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) - Получить все оставшиеся строки

***

### `chdb.state.sqlitelike`

Преобразует результат запроса в таблицу PyArrow.

Эта функция преобразует результаты запроса chdb в таблицу PyArrow,
что обеспечивает эффективный доступ к столбцовым данным и совместимость
с другими библиотеками для обработки данных.

**Синтаксис**

```python theme={null}
chdb.state.sqlitelike.to_arrowTable(res)
```

**Параметры:**

| Parameter | Type | Description |
| - | - | - |
| `res` | - | Объект результата запроса из chdb, содержащий данные в формате Arrow |

**Возвращает**

| Return Type | Description |
| - | - |
| `pyarrow.Table` | Таблица PyArrow с результатами запроса |

**Вызывает**

| Exception | Condition |
| - | - |
| `ImportError` | Если пакеты pyarrow или pandas не установлены |

> [!NOTE]
>
> Для работы этой функции должны быть установлены и pyarrow, и pandas.
> Установите их командой: `pip install pyarrow pandas`

> [!WARNING]
>
> **Предупреждение**
>
> При пустом результате возвращается пустая таблица PyArrow без схемы.

**Примеры**

```pycon theme={null}
>>> 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`

Преобразует результат запроса в DataFrame Pandas.

Эта функция преобразует результаты запросов chdb в DataFrame Pandas:
сначала в таблицу PyArrow, а затем в DataFrame. Это обеспечивает
удобные возможности для анализа данных через API Pandas.

**Синтаксис**

```python theme={null}
chdb.state.sqlitelike.to_df(r)
```

**Параметры:**

| Parameter | Type | Description |
| - | - | - |
| `r` | - | Объект результата запроса из chdb, содержащий данные в формате Arrow |

**Возвращает:**

| Return Type | Description |
| - | - |
| `pandas.DataFrame` | Объект DataFrame, содержащий результаты запроса с соответствующими именами столбцов и типами данных |

**Вызывает**

| Exception | Condition |
| - | - |
| `ImportError` | Если пакеты pyarrow или pandas не установлены |

> [!NOTE]
>
> Эта функция использует многопоточность при преобразовании из Arrow в Pandas,
> чтобы повысить производительность на больших объёмах данных.

**См. также**

* [`to_arrowTable()`](#chdb-state-sqlitelike-to_arrowtable) - Для преобразования в формат таблицы PyArrow

**Примеры**

```pycon theme={null}
>>> 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

### **class** `chdb.dataframe.Table`

Базовые классы:

```python theme={null}
class chdb.dataframe.Table(*args: Any, **kwargs: Any)
```

## Интерфейс Database API (DBAPI) 2.0

chDB предоставляет совместимый с Python DB-API 2.0 интерфейс для работы с базами данных, что позволяет использовать chDB с инструментами и фреймворками, рассчитанными на стандартные интерфейсы баз данных.

Интерфейс chDB DB-API 2.0 включает:

* **Подключения**: Управление подключениями к базе данных с помощью строк подключения
* **Курсоры**: Выполнение запросов и получение результатов
* **Система типов**: Константы типов и конвертеры, совместимые с DB-API 2.0
* **Обработка ошибок**: Стандартная иерархия исключений базы данных
* **Потокобезопасность**: Уровень потокобезопасности 1 (потоки могут совместно использовать модули, но не подключения)

***

### Основные функции

Интерфейс Database API (DBAPI) 2.0 включает следующие основные функции:

#### `chdb.dbapi.connect`

Инициализирует новое соединение с базой данных.

**Синтаксис**

```python theme={null}
chdb.dbapi.connect(*args, **kwargs)
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `path` | str | `None` | Путь к файлу базы данных. None — для временной базы данных без сохранения |

**Вызывает**

| Исключение | Условие |
| - | - |
| [`err.Error`](#chdb-dbapi-err-error) | Если не удаётся установить соединение |

***

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

Возвращает сведения о версии клиента.

Возвращает версию клиента chDB в виде строки для совместимости с MySQLdb.

**Синтаксис**

```python theme={null}
chdb.dbapi.get_client_info()
```

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `str` | Строка версии в формате 'major.minor.patch' |

***

### Конструкторы типов

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

Возвращает x в виде двоичного типа.

Эта функция преобразует входное значение в тип bytes для использования в двоичных
полях базы данных в соответствии со спецификацией DB-API 2.0.

**Синтаксис**

```python theme={null}
chdb.dbapi.Binary(x)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `x` | - | Входные данные, преобразуемые в бинарный формат |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `bytes` | Входные данные, преобразованные в байты |

***

### Класс соединения

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

Базовый класс: `object`

Подключение к базе данных chDB, совместимое с DB-API 2.0.

Этот класс предоставляет стандартный интерфейс DB-API для подключения к базам данных chDB и работы с ними. Поддерживаются как временные, так и файловые базы данных.

Подключение управляет базовым движком chDB и предоставляет методы для
выполнения запросов, управления транзакциями (для ClickHouse это операция-заглушка) и создания курсоров.

```python theme={null}
class chdb.dbapi.connections.Connection(path=None)
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `path` | str | `None` | Путь к файлу базы данных. Если None (значение по умолчанию), используется временная база данных без постоянного хранения (эквивалент `':memory:'`). Передайте путь к файлу, например 'database.db', чтобы сохранить данные на диске. |

**Переменные**

| Переменная | Тип | Описание |
| - | - | - |
| `encoding` | str | Кодировка символов для запросов, по умолчанию 'utf8' |
| `open` | bool | True, если соединение открыто, и False, если закрыто |

**Примеры**

```pycon theme={null}
>>> # Temporary database
>>> conn = Connection()
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchall()
>>> conn.close()
```

```pycon theme={null}
>>> # 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()
```

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

> [!NOTE]
>
> ClickHouse не поддерживает традиционные транзакции, поэтому операции commit() и rollback()
> ничего не делают, но предусмотрены для соответствия DB-API.

***

#### `close`

Закрывает соединение с базой данных.

Закрывает базовое соединение chDB и помечает его как закрытое.
Последующие операции с этим соединением будут вызывать ошибку.

**Синтаксис**

```python theme={null}
close()
```

**Исключения**

| Исключение | Условие |
| - | - |
| [`err.Error`](#chdb-dbapi-err-error) | Если соединение уже закрыто |

***

#### `commit`

Фиксирует текущую транзакцию.

**Синтаксис**

```python theme={null}
commit()
```

> [!NOTE]
>
> Для chDB/ClickHouse это операция-заглушка, так как они не поддерживают
> традиционные транзакции. Предусмотрено для соблюдения требований DB-API 2.0.

***

#### `cursor`

Создает новый курсор для выполнения запросов.

**Синтаксис**

```python theme={null}
cursor(cursor=None)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `cursor` | - | Игнорируется, указан для совместимости |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `Cursor` | Новый объект курсора для этого соединения |

**Вызывает**

| Исключение | Условие |
| - | - |
| [`err.Error`](#chdb-dbapi-err-error) | Если соединение закрыто |

**Пример**

```pycon theme={null}
>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1")
>>> result = cur.fetchone()
```

***

#### `escape`

Экранирование значения для безопасного включения в SQL-запросы.

**Синтаксис**

```python theme={null}
escape(obj, mapping=None)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `obj` | - | Значение для экранирования (строка, байты, число и т. д.) |
| `mapping` | - | Необязательное сопоставление символов для экранирования |

**Возвращаемое значение**

| Возвращаемый тип | Описание |
| - | - |
| - | Экранированная версия входного значения, подходящая для SQL-запросов |

**Пример**

```pycon theme={null}
>>> conn = Connection()
>>> safe_value = conn.escape("O'Reilly")
>>> query = f"SELECT * FROM users WHERE name = {safe_value}"
```

***

#### `escape_string`

Экранирует строковое значение для SQL-запросов.

**Синтаксис**

```python theme={null}
escape_string(s)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `s` | str | Строка для экранирования |

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| `str` | Экранированная строка, безопасная для использования в SQL |

***

#### `свойство open`

Проверяет, открыто ли соединение.

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| `bool` | true, если соединение открыто; false, если закрыто |

***

#### `query`

Выполняет SQL-запрос напрямую и возвращает необработанные результаты.

Этот метод обходит интерфейс курсора и выполняет запросы напрямую.
Для стандартного использования DB-API рекомендуется использовать метод `cursor()`.

**Синтаксис**

```python theme={null}
query(sql, fmt='CSV')
```

**Параметры:**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `sql` | str or bytes | *required* | SQL-запрос для выполнения |
| `fmt` | str | `"CSV"` | Выходной формат. Поддерживаемые форматы включают "CSV", "JSON", "Arrow", "Parquet" и т. д. |

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| - | Результат запроса в указанном формате |

**Вызывает исключения**

| Исключение | Условие |
| - | - |
| [`err.InterfaceError`](#chdb-dbapi-err-interfaceerror) | Если соединение закрыто или выполнение запроса завершается ошибкой |

**Пример**

```pycon theme={null}
>>> conn = Connection()
>>> result = conn.query("SELECT 1, 'hello'", "CSV")
>>> print(result)
"1,hello\n"
```

***

#### `свойство resp`

Возвращает ответ на последний запрос.

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| - | Необработанный ответ последнего вызова query() |

> [!NOTE]
>
> Это свойство обновляется при каждом прямом вызове query().
> Оно не отражает запросы, выполненные через курсоры.

***

#### `rollback`

Откатывает текущую транзакцию.

**Синтаксис**

```python theme={null}
rollback()
```

> [!NOTE]
>
> Для chDB/ClickHouse это не имеет эффекта, так как они не поддерживают традиционные
> транзакции. Предусмотрено для соответствия DB-API 2.0.

***

### Класс Cursor

#### **class** `chdb.dbapi.cursors.Cursor`

Наследует: `object`

Курсор DB-API 2.0 для выполнения запросов и получения результатов.

Курсор предоставляет методы для выполнения SQL-команд, управления результатами запросов
и навигации по результирующим наборам. Он поддерживает привязку параметров, пакетные операции
и соответствует спецификации DB-API 2.0.

Не создавайте экземпляры Cursor напрямую. Вместо этого используйте `Connection.cursor()`.

```python theme={null}
class chdb.dbapi.cursors.Cursor(connection)
```

| Переменная | Тип | Описание |
| - | - | - |
| `description` | tuple | Метаданные столбцов результата последнего запроса |
| `rowcount` | int | Количество строк, затронутых последним запросом (-1, если неизвестно) |
| `arraysize` | int | Количество строк, извлекаемых за один раз по умолчанию (по умолчанию: 1) |
| `lastrowid` | - | ID последней вставленной строки (если применимо) |
| `max_stmt_length` | int | Максимальный размер оператора для executemany() (по умолчанию: 1024000) |

**Примеры**

```pycon theme={null}
>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1 as id, 'test' as name")
>>> result = cur.fetchone()
>>> print(result)  # (1, 'test')
>>> cur.close()
```

> [!NOTE]
>
> См. [объекты Cursor в DB-API 2.0](https://www.python.org/dev/peps/pep-0249/#cursor-objects)
> для получения подробной информации о спецификации.

***

#### `callproc`

Выполняет хранимую процедуру (временная реализация-заглушка).

**Синтаксис**

```python theme={null}
callproc(procname, args=())
```

**Параметры**

| Parameter | Type | Description |
| - | - | - |
| `procname` | str | Имя хранимой процедуры, которую нужно выполнить |
| `args` | sequence | Параметры, передаваемые в процедуру |

**Возвращает**

| Return Type | Description |
| - | - |
| `sequence` | Исходный параметр `args` (без изменений) |

> [!NOTE]
>
> chDB/ClickHouse не поддерживает хранимые процедуры в традиционном понимании.
> Этот метод предоставлен для соответствия DB-API 2.0, но фактически
> не выполняет никаких действий. Для всех SQL-операций используйте execute().

> [!WARNING]
>
> **Совместимость**
>
> Это реализация-заглушка. Традиционные возможности хранимых процедур,
> такие как параметры OUT/INOUT, несколько результирующих наборов и серверные
> переменные, не поддерживаются лежащим в основе движком ClickHouse.

***

#### `close`

Закрывает курсор и освобождает связанные с ним ресурсы.

После закрытия курсор становится непригодным для дальнейшего использования, и любая операция с ним сгенерирует исключение.
При закрытии курсора считываются все оставшиеся данные и освобождается базовый курсор.

**Синтаксис**

```python theme={null}
close()
```

***

#### `execute`

Выполняет SQL-запрос с необязательной привязкой параметров.

Этот метод выполняет один SQL-оператор с необязательной подстановкой параметров.
Поддерживает несколько стилей плейсхолдеров параметров для большей гибкости.

**Синтаксис**

```python theme={null}
execute(query, args=None)
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `query` | str | *обязательно* | SQL-запрос для выполнения |
| `args` | tuple/list/dict | `None` | Параметры для привязки к плейсхолдерам |

**Возвращаемое значение**

| Возвращаемый тип | Описание |
| - | - |
| `int` | Количество затронутых строк (-1, если неизвестно) |

**Стили параметров**

| Стиль | Пример |
| - | - |
| Question mark style | `"SELECT * FROM users WHERE id = ?"` |
| Named style | `"SELECT * FROM users WHERE name = %(name)s"` |
| Format style | `"SELECT * FROM users WHERE age = %s"` (устаревший) |

**Примеры**

```pycon theme={null}
>>> # Параметры с вопросительными знаками
>>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
>>>
>>> # Именованные параметры
>>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
>>>
>>> # Без параметров
>>> cur.execute("SELECT COUNT(*) FROM users")
```

**Вызывает исключения**

| Исключение | Условие |
| - | - |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | Если курсор закрыт или запрос составлен неверно |
| [`InterfaceError`](#chdb-dbapi-err-interfaceerror) | Если во время выполнения возникает ошибка базы данных |

***

#### `executemany(query, args)`

Выполняет запрос несколько раз с разными наборами параметров.

Этот метод позволяет эффективно выполнять один и тот же SQL-запрос несколько раз с
разными значениями параметров. Он особенно полезен при массовой вставке данных.

**Синтаксис**

```python theme={null}
executemany(query, args)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `query` | str | SQL-запрос, выполняемый многократно |
| `args` | sequence | Последовательность кортежей/словарей/списков параметров для каждого выполнения |

**Возвращает**

| Тип возвращаемого значения | Описание |
| - | - |
| `int` | Общее количество затронутых строк во всех выполнениях |

**Примеры**

```pycon theme={null}
>>> # Пакетная вставка с параметрами-заполнителями ?
>>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
>>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
>>>
>>> # Пакетная вставка с именованными параметрами
>>> users_data = [
...     {'id': 1, 'name': 'Alice'},
...     {'id': 2, 'name': 'Bob'}
... ]
>>> cur.executemany(
...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
...     users_data
... )
```

> [!NOTE]
>
> Этот метод повышает производительность операций INSERT и UPDATE сразу для нескольких строк
> за счёт оптимизации процесса выполнения запроса.

***

#### `fetchall()`

Получает все оставшиеся строки из результата запроса.

**Синтаксис**

```python theme={null}
fetchall()
```

**Возвращает**

| Return Type | Описание |
| - | - |
| `list` | Список кортежей со всеми оставшимися строками |

**Вызывает**

| Exception | Условие |
| - | - |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | Если `execute()` не был вызван заранее |

> [!WARNING]
>
> **Предупреждение**
>
> Этот метод может потреблять много памяти при больших результирующих наборах.
> Для больших датасетов рекомендуется использовать `fetchmany()`.

**Пример**

```pycon theme={null}
>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_rows))  # Всего строк
```

***

#### `fetchmany`

Возвращает несколько строк из результата запроса.

**Синтаксис**

```python theme={null}
fetchmany(size=1)
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `size` | int | `1` | Количество строк для получения. Если не указано, используется cursor.arraysize |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `list` | Список кортежей, представляющих полученные строки |

**Вызывает**

| Исключение | Условие |
| - | - |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | Если метод execute() не был вызван перед этим |

**Пример**

```pycon theme={null}
>>> cursor.execute("SELECT id, name FROM users")
>>> rows = cursor.fetchmany(3)
>>> print(rows)  # [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
```

***

#### `fetchone`

Возвращает следующую строку из результата запроса.

**Синтаксис**

```python theme={null}
fetchone()
```

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `tuple or None` | Следующая строка в виде кортежа или None, если строк больше не осталось |

**Исключения**

| Исключение | Условие |
| - | - |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | Если `execute()` ещё не был вызван |

**Пример**

```pycon theme={null}
>>> cursor.execute("SELECT id, name FROM users LIMIT 3")
>>> row = cursor.fetchone()
>>> print(row)  # (1, 'Alice')
>>> row = cursor.fetchone()
>>> print(row)  # (2, 'Bob')
```

***

#### `max_stmt_length = 1024000`

Максимальный размер оператора, создаваемого [`executemany()`](#chdb-dbapi-cursors-cursor-executemany).

Значение по умолчанию — 1024000.

***

#### `mogrify`

Возвращает точную строку запроса, которая будет отправлена в базу данных.

Этот метод показывает итоговый SQL-запрос после подстановки параметров,
что полезно для отладки и логирования.

**Синтаксис**

```python theme={null}
mogrify(query, args=None)
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `query` | str | *обязательно* | SQL-запрос с плейсхолдерами параметров |
| `args` | tuple/list/dict | `None` | Параметры для подстановки |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `str` | Итоговая строка SQL-запроса с подставленными параметрами |

**Пример**

```pycon theme={null}
>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"
```

> [!NOTE]
>
> Этот метод реализован в соответствии с расширением DB-API 2.0, используемым в Psycopg.

***

#### `nextset`

Переход к следующему результирующему набору (не поддерживается).

**Синтаксис**

```python theme={null}
nextset()
```

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `None` | Всегда возвращает None, так как несколько результирующих наборов не поддерживаются |

> [!NOTE]
>
> chDB/ClickHouse не поддерживает несколько результирующих наборов для одного запроса.
> Этот метод предусмотрен для соответствия DB-API 2.0, но всегда возвращает None.

***

#### `setinputsizes`

Устанавливает размеры входных данных для параметров (реализация-заглушка).

**Синтаксис**

```python theme={null}
setinputsizes(*args)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `*args` | - | Спецификации размеров параметров (игнорируются) |

> [!NOTE]
>
> Этот метод ничего не делает, но требуется спецификацией DB-API 2.0.
> chDB автоматически обрабатывает размеры параметров на внутреннем уровне.

***

#### `setoutputsizes`

Установить размеры выходных столбцов (реализация-заглушка).

**Синтаксис**

```python theme={null}
setoutputsizes(*args)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `*args` | - | Спецификации размера столбцов (игнорируются) |

> [!NOTE]
>
> Этот метод ничего не делает, но обязателен по спецификации DB-API 2.0.
> chDB автоматически обрабатывает размер выходных данных на своей стороне.

***

### Классы ошибок

Классы исключений для операций с базой данных chdb.

Этот модуль предоставляет полную иерархию классов исключений для обработки
ошибок, связанных с базой данных, в chdb в соответствии со спецификацией Python Database API v2.0.

Иерархия исключений устроена следующим образом:

```default theme={null}
StandardError
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError
```

Каждый класс исключений представляет отдельную категорию ошибок базы данных:

| Exception | Description |
| - | - |
| `Warning` | Нефатальные предупреждения при операциях с базой данных |
| `InterfaceError` | Проблемы с самим интерфейсом базы данных |
| `DatabaseError` | Базовый класс для всех ошибок, связанных с базой данных |
| `DataError` | Проблемы при обработке данных (недопустимые значения, ошибки типов) |
| `OperationalError` | Ошибки при работе с базой данных (подключение, ресурсы) |
| `IntegrityError` | Нарушения ограничений целостности (внешние ключи, уникальность) |
| `InternalError` | Внутренние ошибки базы данных и повреждение данных |
| `ProgrammingError` | Ошибки синтаксиса SQL и неправильное использование API |
| `NotSupportedError` | Неподдерживаемые возможности или операции |

> [!NOTE]
>
> Эти классы исключений соответствуют спецификации Python DB API 2.0
> и обеспечивают единообразную обработку ошибок в различных операциях с базой данных.

**См. также**

* [Python Database API Specification v2.0](https://peps.python.org/pep-0249/)
* `chdb.dbapi.connections` - Управление подключениями к базе данных
* `chdb.dbapi.cursors` - Операции с курсорами базы данных

**Примеры**

```pycon theme={null}
>>> try:
...     cursor.execute("SELECT * FROM nonexistent_table")
... except ProgrammingError as e:
...     print(f"SQL Error: {e}")
...
SQL Error: Table 'nonexistent_table' doesn't exist
```

```pycon theme={null}
>>> try:
...     cursor.execute("INSERT INTO users (id) VALUES (1), (1)")
... except IntegrityError as e:
...     print(f"Constraint violation: {e}")
...
Constraint violation: Duplicate entry '1' for key 'PRIMARY'
```

***

#### **exception** `chdb.dbapi.err.DataError`

Наследуется от: [`DatabaseError`](#chdb-dbapi-err-databaseerror)

Исключение, возникающее при ошибках, связанных с обрабатываемыми данными.

Это исключение возникает, когда операции с базой данных завершаются с ошибкой из-за проблем с
обрабатываемыми данными, таких как:

* Деление на ноль
* Числовые значения вне допустимого диапазона
* Недопустимые значения даты/времени
* Ошибки усечения строк
* Ошибки преобразования типов
* Недопустимый формат данных для данного типа столбца

**Вызывает**

| Исключение | Условие |
| - | - |
| [`DataError`](#chdb-dbapi-err-dataerror) | Когда проверка или обработка данных завершается ошибкой |

**Примеры**

```pycon theme={null}
>>> # Деление на ноль в SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero
```

```pycon theme={null}
>>> # Неправильный формат даты
>>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
DataError: Invalid date format
```

***

#### **исключение** `chdb.dbapi.err.DatabaseError`

Базовый класс: [`Error`](#chdb-dbapi-err-error)

Исключение, вызываемое при ошибках, связанных с базой данных.

Это базовый класс для всех ошибок, связанных с базой данных. Он охватывает
все ошибки, возникающие при операциях с базой данных и относящиеся к
самой базе данных, а не к интерфейсу.

К распространённым ситуациям относятся:

* Ошибки выполнения SQL
* Проблемы с подключением к базе данных
* Проблемы, связанные с транзакциями
* Нарушения ограничений, специфичных для базы данных

> [!NOTE]
>
> Это родительский класс для более конкретных типов ошибок базы данных,
> таких как [`DataError`](#chdb-dbapi-err-dataerror), [`OperationalError`](#chdb-dbapi-err-operationalerror) и т. д.

***

#### **исключение** `chdb.dbapi.err.Error`

Базовый класс: [`StandardError`](#chdb-dbapi-err-standarderror)

Исключение, которое является базовым классом для всех остальных исключений ошибок (кроме `Warning`).

Это базовый класс для всех исключений ошибок в chdb, кроме предупреждений.
Он служит родительским классом для всех ошибок базы данных, которые препятствуют
успешному завершению операций.

> [!NOTE]
>
> Эта иерархия исключений соответствует спецификации Python DB API 2.0.

**См. также**

* [`Warning`](#chdb-dbapi-err-warning) - Для нефатальных предупреждений, которые не мешают завершению операции

#### **исключение** `chdb.dbapi.err.IntegrityError`

Базовый класс: [`DatabaseError`](#chdb-dbapi-err-databaseerror)

Исключение, которое возникает при нарушении реляционной целостности базы данных.

Это исключение возникает, когда операции с базой данных нарушают ограничения целостности,
в том числе:

* Нарушения ограничений внешнего ключа
* Нарушения первичного ключа или ограничения уникальности (дублирующиеся ключи)
* Нарушения ограничения CHECK
* Нарушения ограничения NOT NULL
* Нарушения ссылочной целостности

**Вызывает**

| Исключение | Условие |
| - | - |
| [`IntegrityError`](#chdb-dbapi-err-integrityerror) | Когда нарушаются ограничения целостности базы данных |

**Примеры**

```pycon theme={null}
>>> # Дубликат первичного ключа
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
IntegrityError: Duplicate entry '1' for key 'PRIMARY'
```

```pycon theme={null}
>>> # Нарушение внешнего ключа
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails
```

***

#### **исключение** `chdb.dbapi.err.InterfaceError`

Базовый класс: [`Error`](#chdb-dbapi-err-error)

Исключение, возникающее при ошибках, связанных с интерфейсом базы данных, а не с самой базой данных.

Это исключение возникает при проблемах в реализации
интерфейса базы данных, например:

* Недопустимые параметры соединения
* Неправильное использование API (вызов методов у закрытых соединений)
* Ошибки протокола на уровне интерфейса
* Сбои при импорте или инициализации модуля

**Возникает**

| Исключение | Условие |
| - | - |
| [`InterfaceError`](#chdb-dbapi-err-interfaceerror) | Когда интерфейс базы данных сталкивается с ошибками, не связанными с операциями базы данных |

> [!NOTE]
>
> Эти ошибки обычно вызваны ошибками в коде или проблемами конфигурации
> и могут быть устранены исправлением клиентского кода или конфигурации.

***

#### **исключение** `chdb.dbapi.err.InternalError`

Базовый класс: [`DatabaseError`](#chdb-dbapi-err-databaseerror)

Исключение, возникающее, когда база данных сталкивается с внутренней ошибкой.

Это исключение возникает, когда система базы данных сталкивается с внутренними
ошибками, не вызванными приложением, например:

* Недопустимое состояние курсора (курсор больше не является действительным)
* Несогласованность состояния транзакции (транзакция не синхронизирована)
* Проблемы, связанные с повреждением базы данных
* Повреждение внутренних структур данных
* Ошибки базы данных на уровне системы

**Вызывает**

| Исключение | Условие |
| - | - |
| [`InternalError`](#chdb-dbapi-err-internalerror) | Когда база данных сталкивается с внутренними несогласованностями |

> [!WARNING]
>
> **Предупреждение**
>
> Внутренние ошибки могут указывать на серьёзные проблемы с базой данных,
> требующие внимания администратора базы данных. Эти ошибки, как правило,
> нельзя устранить с помощью логики повторных попыток на уровне приложения.

> [!NOTE]
>
> Эти ошибки, как правило, находятся вне контроля приложения
> и могут потребовать перезапуска базы данных или операций восстановления.

***

#### **исключение** `chdb.dbapi.err.NotSupportedError`

Базовый класс: [`DatabaseError`](#chdb-dbapi-err-databaseerror)

Исключение, возникающее, когда метод или API базы данных не поддерживается.

Это исключение возникает, когда приложение пытается использовать возможности базы данных
или методы API, которые не поддерживаются текущей конфигурацией
или версией базы данных, например:

* Вызов `rollback()` для соединений без поддержки транзакций
* Использование расширенных возможностей SQL, не поддерживаемых версией базы данных
* Вызов методов, не реализованных текущим драйвером
* Попытка использовать отключённые возможности базы данных

**Вызывает**

| Exception | Condition |
| - | - |
| [`NotSupportedError`](#chdb-dbapi-err-notsupportederror) | При обращении к неподдерживаемым возможностям базы данных |

**Примеры**

```pycon theme={null}
>>> # Попытка отката транзакции в соединении без поддержки транзакций
>>> connection.rollback()
NotSupportedError: Транзакции не поддерживаются
```

```pycon theme={null}
>>> # Использование неподдерживаемого синтаксиса SQL
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version
```

> [!NOTE]
>
> Чтобы избежать
> этих ошибок, ознакомьтесь с документацией по базе данных и возможностями драйвера. По возможности предусмотрите корректный переход на резервные варианты.

***

#### **исключение** `chdb.dbapi.err.OperationalError`

Базовый класс: [`DatabaseError`](#chdb-dbapi-err-databaseerror)

Исключение, возникающее при ошибках, связанных с работой базы данных.

Это исключение возникает при ошибках, происходящих во время работы базы данных
и не обязательно зависящих от программиста, включая:

* Неожиданное отключение от базы данных
* Сервер базы данных не найден или недоступен
* Сбои при обработке транзакций
* Ошибки выделения памяти во время обработки
* Нехватка места на диске или исчерпание ресурсов
* Внутренние ошибки сервера базы данных
* Сбои аутентификации или авторизации

**Вызывает**

| Исключение | Условие |
| - | - |
| [`OperationalError`](#chdb-dbapi-err-operationalerror) | Когда операции с базой данных завершаются сбоем из-за проблем при выполнении |

> [!NOTE]
>
> Эти ошибки обычно носят временный характер и могут быть устранены повторной попыткой
> выполнить операцию или устранением проблем на уровне системы.

> [!WARNING]
>
> **Предупреждение**
>
> Некоторые ошибки при выполнении операций могут указывать на серьёзные проблемы системы,
> требующие вмешательства администратора.

***

#### **исключение** `chdb.dbapi.err.ProgrammingError`

Базовый класс: [`DatabaseError`](#chdb-dbapi-err-databaseerror)

Исключение, возникающее при ошибках программирования в операциях с базой данных.

Это исключение возникает, когда в работе приложения с базой данных
допущены ошибки программирования, в том числе:

* Таблица или столбец не найдены
* Таблица или индекс уже существуют при создании
* Синтаксические ошибки SQL в операторах
* Указано неверное количество параметров в подготовленных операторах
* Недопустимые SQL-операции (например, DROP для несуществующих объектов)
* Некорректное использование методов API базы данных

**Вызывает**

| Исключение | Условие |
| - | - |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | Когда операторы SQL или использование API содержат ошибки |

**Примеры**

```pycon theme={null}
>>> # Таблица не найдена
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist
```

```pycon theme={null}
>>> # Синтаксическая ошибка SQL
>>> cursor.execute("SELCT * FROM users")
ProgrammingError: You have an error in your SQL syntax
```

```pycon theme={null}
>>> # Неверное число параметров
>>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',))
ProgrammingError: Column count doesn't match value count
```

***

#### **исключение** `chdb.dbapi.err.StandardError`

Базовый класс: `Exception`

Исключение, связанное с работой chdb.

Это базовый класс для всех исключений, связанных с chdb. Он наследуется от
встроенного класса Python `Exception` и служит корневым классом в иерархии
исключений для операций с базой данных.

> [!NOTE]
>
> Этот класс исключений соответствует спецификации Python DB API 2.0
> для обработки исключений баз данных.

***

#### **исключение** `chdb.dbapi.err.Warning`

Базовый класс: [`StandardError`](#chdb-dbapi-err-standarderror)

Исключение, возникающее при важных предупреждениях, таких как усечение данных при вставке и т. д.

Это исключение возникает, когда операция с базой данных завершается, но
сопровождается важными предупреждениями, на которые приложение должно обратить внимание.
Распространённые сценарии:

* Усечение данных при вставке
* Потеря точности при числовых преобразованиях
* Предупреждения при преобразовании кодировки

> [!NOTE]
>
> Соответствует спецификации Python DB API 2.0 для исключений-предупреждений.

***

### Константы модуля

#### `chdb.dbapi.apilevel = '2.0'`

```python theme={null}
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
```

Создает новый строковый объект из указанного объекта. Если указаны encoding или
errors, объект должен предоставлять буфер данных,
который будет декодирован с использованием указанной кодировки и обработчика ошибок.
В противном случае возвращается результат `object._\_str_\_()` (если он определен)
или `repr(object)`.

* значение encoding по умолчанию — ‘utf-8’.
* значение errors по умолчанию — ‘strict’.

***

#### `chdb.dbapi.threadsafety = 1`

```python theme={null}
int([x]) -> integer
int(x, base=10) -> integer
```

Преобразует число или строку в целое число или возвращает 0, если аргументы
не указаны. Если x — число, возвращает x.*\_int*\_(). Для чисел с плавающей точкой
это означает усечение к нулю.

Если x не является числом или указан base, то x должен быть строкой,
экземпляром bytes или bytearray, представляющим целочисленный литерал в
заданной системе счисления. Литерал может предваряться символом ‘+’ или ‘-’ и
содержать пробельные символы по краям. По умолчанию base равен 10. Допустимые
значения base: 0 и 2–36. Base 0 означает, что система счисления определяется
по строке, как для целочисленного литерала.

```python theme={null}
>>> int(‘0b100’, base=0)
4
```

***

#### `chdb.dbapi.paramstyle = 'format'`

```python theme={null}
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
```

Создает новый строковый объект из заданного объекта. Если указаны encoding или
errors, объект должен предоставлять буфер данных,
который будет декодирован с использованием указанной кодировки и обработчика ошибок.
В противном случае возвращается результат object.*\_str*\_() (если определен)
или repr(object).
По умолчанию для encoding используется значение ‘utf-8’.
По умолчанию для errors используется значение ‘strict’.

***

### Константы типов

#### `chdb.dbapi.STRING = frozenset({247, 253, 254})`

Расширенный frozenset для сравнения типов в DB-API 2.0.

Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0.
Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать
с набором как с помощью операторов равенства, так и неравенства.

Он используется для таких констант типов, как STRING, BINARY, NUMBER и т. д., чтобы можно было выполнять
сравнения вида “field\_type == STRING”, где field\_type — это отдельное значение типа.

**Примеры**

```pycon theme={null}
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Возвращает True
>>> FIELD_TYPE.INT != string_types     # Возвращает True
>>> FIELD_TYPE.BLOB in string_types    # Возвращает False
```

***

#### `chdb.dbapi.BINARY = frozenset({249, 250, 251, 252})`

Расширенный frozenset для сравнения типов в DB-API 2.0.

Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0.
Он обеспечивает гибкую проверку типов, при которой отдельные элементы можно сравнивать
с набором как с помощью операторов равенства, так и неравенства.

Используется для таких констант типов, как STRING, BINARY, NUMBER и т. д., чтобы можно было выполнять
сравнения вида “field\_type == STRING”, где field\_type — это отдельное значение типа.

**Примеры**

```pycon theme={null}
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Возвращает True
>>> FIELD_TYPE.INT != string_types     # Возвращает True
>>> FIELD_TYPE.BLOB in string_types    # Возвращает False
```

***

#### `chdb.dbapi.NUMBER = frozenset({0, 1, 3, 4, 5, 8, 9, 13})`

Расширенный frozenset для сравнения типов в соответствии с DB-API 2.0.

Этот класс расширяет frozenset, добавляя поддержку семантики сравнения типов из DB-API 2.0.
Он обеспечивает гибкую проверку типов, при которой отдельные элементы можно сравнивать
с набором с помощью операторов равенства и неравенства.

Используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать
сравнения вида “field\_type == STRING”, где field\_type — это отдельное значение типа.

**Примеры**

```pycon theme={null}
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Возвращает True
>>> FIELD_TYPE.INT != string_types     # Возвращает True
>>> FIELD_TYPE.BLOB in string_types    # Возвращает False
```

***

#### `chdb.dbapi.DATE = frozenset({10, 14})`

Расширенный frozenset для сравнения типов в DB-API 2.0.

Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0.
Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать
с множеством с помощью как операторов равенства, так и неравенства.

Он используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать
сравнения вида “field\_type == STRING”, где field\_type — это отдельное значение типа.

**Примеры**

```pycon theme={null}
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Возвращает True
>>> FIELD_TYPE.INT != string_types     # Возвращает True
>>> FIELD_TYPE.BLOB in string_types    # Возвращает False
```

***

#### `chdb.dbapi.TIME = frozenset({11})`

Расширенный frozenset для сравнения типов в DB-API 2.0.

Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0.
Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать
с множеством как с помощью операторов равенства, так и неравенства.

Используется для таких констант типов, как STRING, BINARY, NUMBER и т. д., чтобы можно было выполнять
сравнения вида “field\_type == STRING”, где field\_type — это отдельное значение типа.

**Примеры**

```pycon theme={null}
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Возвращает True
>>> FIELD_TYPE.INT != string_types     # Возвращает True
>>> FIELD_TYPE.BLOB in string_types    # Возвращает False
```

***

#### `chdb.dbapi.TIMESTAMP = frozenset({7, 12})`

Расширенный frozenset для сравнения типов в DB-API 2.0.

Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0.
Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать
с набором с помощью операторов равенства и неравенства.

Это используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать
сравнения вида “field\_type == STRING”, где field\_type — это значение отдельного типа.

**Примеры**

```pycon theme={null}
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Возвращает True
>>> FIELD_TYPE.INT != string_types     # Возвращает True
>>> FIELD_TYPE.BLOB in string_types    # Возвращает False
```

#### `chdb.dbapi.DATETIME = frozenset({7, 12})`

Расширенный frozenset для сравнения типов в DB-API 2.0.

Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0.
Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать
с множеством как с помощью операторов равенства, так и неравенства.

Это используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать
сравнения вида “field\_type == STRING”, где field\_type — это одно значение типа.

**Примеры**

```pycon theme={null}
>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Возвращает True
>>> FIELD_TYPE.INT != string_types     # Возвращает True
>>> FIELD_TYPE.BLOB in string_types    # Возвращает False
```

***

#### `chdb.dbapi.ROWID = frozenset({})`

Расширенный `frozenset` для сравнения типов в DB-API 2.0.

Этот класс расширяет `frozenset`, добавляя поддержку семантики сравнения типов DB-API 2.0.
Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать
с Set с помощью операторов равенства и неравенства.

Используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать
сравнения вида “field\_type == STRING”, где field\_type — это отдельное значение типа.

**Примеры**

```pycon theme={null}
>>> 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
```

**Примеры использования**

Пример базового запроса:

```python theme={null}
import chdb.dbapi as dbapi

print("chdb driver version: {0}".format(dbapi.get_client_info()))

# Create connection and cursor
conn = dbapi.connect()
cur = conn.cursor()

# Execute query
cur.execute('SELECT version()')
print("description:", cur.description)
print("data:", cur.fetchone())

# Clean up
cur.close()
conn.close()
```

Работа с данными:

```python theme={null}
import chdb.dbapi as dbapi

conn = dbapi.connect()
cur = conn.cursor()

# Create table
cur.execute("""
    CREATE TABLE employees (
        id UInt32,
        name String,
        department String,
        salary Decimal(10,2)
    ) ENGINE = Memory
""")

# Insert data
cur.execute("""
    INSERT INTO employees VALUES
    (1, 'Alice', 'Engineering', 75000.00),
    (2, 'Bob', 'Marketing', 65000.00),
    (3, 'Charlie', 'Engineering', 80000.00)
""")

# Query data
cur.execute("SELECT * FROM employees WHERE department = 'Engineering'")

# Fetch results
print("Column names:", [desc[0] for desc in cur.description])
for row in cur.fetchall():
    print(row)

conn.close()
```

Управление соединениями:

```python theme={null}
import chdb.dbapi as dbapi

# Temporary database (default)
conn1 = dbapi.connect()

# Persistent database file
conn2 = dbapi.connect("./my_database.chdb")

# Connection with parameters
conn3 = dbapi.connect("./my_database.chdb?log-level=debug&verbose")

# Read-only connection
conn4 = dbapi.connect("./my_database.chdb?mode=ro")

# Automatic connection cleanup
with dbapi.connect("test.chdb") as conn:
    cur = conn.cursor()
    cur.execute("SELECT count() FROM numbers(1000)")
    result = cur.fetchone()
    print(f"Count: {result[0]}")
    cur.close()
```

**Рекомендации**

1. **Управление соединениями**: Всегда закрывайте соединения и курсоры по завершении работы
2. **Контекстные менеджеры**: Используйте операторы `with` для автоматического освобождения ресурсов
3. **Обработка батчами**: Используйте `fetchmany()` для больших результирующих наборов
4. **Обработка ошибок**: Оборачивайте операции с базой данных в блоки try-except
5. **Привязка параметров**: По возможности используйте параметризованные запросы
6. **Управление памятью**: Избегайте `fetchall()` для очень больших наборов данных

> [!NOTE]
>
> * Интерфейс DB-API 2.0 в chDB совместим с большинством Python-инструментов для работы с базами данных
> * Интерфейс обеспечивает потокобезопасность уровня 1 (потоки могут совместно использовать модули, но не соединения)
> * Строки подключения поддерживают те же параметры, что и сеансы chDB
> * Поддерживаются все стандартные исключения DB-API 2.0

> [!WARNING]
>
> **Предупреждение**
>
> * Всегда закрывайте курсоры и соединения, чтобы избежать утечек ресурсов
> * Большие результирующие наборы следует обрабатывать батчами
> * Синтаксис привязки параметров соответствует стилю format: `%s`

## Пользовательские функции Python (UDF)

chDB поддерживает нативные UDF Python, выполняемые внутри процесса, с типизированными аргументами, автоматическим выводом типов и настраиваемой обработкой NULL и исключений. Функции Python, зарегистрированные как пользовательские функции (UDF), можно вызывать непосредственно из SQL-запросов.

В примерах ниже используется формат вывода CSV по умолчанию. Встроенные комментарии показывают логические значения результатов; в необработанном выводе `NULL` отображается как `\N`, а к строковым значениям и датам применяется CSV-экранирование.

### `chdb.create_function`

Зарегистрируйте функцию Python в качестве SQL-функции chDB.

**Синтаксис**

```python theme={null}
chdb.create_function(name, func, arg_types=None, return_type=None, *, on_null=None, on_error=None)
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `name` | str | *(обязательный)* | Имя регистрируемой SQL-функции |
| `func` | callable | *(обязательный)* | Регистрируемая функция Python |
| `arg_types` | list of ChdbType/str/type, or None | `None` | Список типов аргументов. Если указано `None`, определяются по аннотациям типов |
| `return_type` | ChdbType/str/type, or None | `None` | Возвращаемый тип. Если указано `None`, определяется по аннотации возвращаемого значения функции; регистрация завершится ошибкой, если аннотация также отсутствует |
| `on_null` | str or NullHandling | `None` (skip) | Обработка входных значений NULL: `"skip"` или `"pass"`. Только именованный аргумент |
| `on_error` | str or ExceptionHandling | `None` (propagate) | Обработка исключений: `"propagate"` или `"ignore"`. Только именованный аргумент |

Каждый параметр типа (элементы `arg_types` и `return_type`) принимает:

* Константу `ChdbType`: `INT64`, `STRING`, `FLOAT64` и т. д.
* Строку типа ClickHouse: `"Int64"`, `"String"`, `"DateTime64(6)"`, `"DateTime('UTC')"` и т. д.
* Тип Python: `int`, `float`, `str`, `bool`, `bytes`, `datetime.date`, `datetime.datetime` — сопоставляется согласно разделу [Автоматическое сопоставление типов](#udf-automatic-type-mapping)

Попытка зарегистрировать уже зарегистрированное имя приводит к ошибке — пользовательские функции (UDF) не заменяются автоматически. Чтобы повторно зарегистрировать функцию, сначала вызовите [`drop_function`](#drop-function).

**Пример**

```python theme={null}
from chdb import create_function, drop_function, query
from chdb.sqltypes import INT64, STRING

create_function("strlen", len, arg_types=[STRING], return_type=INT64)
print(query("SELECT strlen('hello')"))  # 5

drop_function("strlen")
```

***

### `chdb.drop_function`

Удаляет ранее зарегистрированную UDF Python. Если функция не зарегистрирована, ничего не происходит, поэтому её можно безопасно вызывать без проверки.

**Синтаксис**

```python theme={null}
chdb.drop_function(name)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `name` | str | Имя SQL-функции, которую нужно удалить |

***

### Декоратор `@func`

Декоратор для регистрации функции Python в качестве SQL-функции chDB. Функцию по-прежнему можно вызывать как обычную функцию Python; одновременно она доступна в SQL-запросах под именем `__name__`.

**Синтаксис**

```python theme={null}
from chdb import func

@func(arg_types=None, return_type=None, *, on_null=None, on_error=None)
def my_function(...):
    ...
```

**Параметры**

Такие же, как у [`create_function`](#create-function), за исключением `name` и `func`, которые определяются декорированной функцией.

**Примеры**

```python theme={null}
from chdb import func, query
from chdb.sqltypes import INT64, STRING

# Explicit types
@func([INT64, INT64], INT64)
def add(a, b):
    return a + b

# Types inferred from annotations
@func()
def multiply(a: int, b: int) -> int:
    return a * b

# Explicit return_type, arg_types inferred from annotations
@func(return_type=STRING)
def greet(name: str):
    return f"Hello, {name}!"

print(query("SELECT add(12, 22)"))       # 34
print(query("SELECT multiply(3, 7)"))    # 21
print(query("SELECT greet('world')"))    # Hello, world!
```

***

### Система типов

#### Доступные типы

Импортируйте типы из `chdb.sqltypes`:

```python theme={null}
from chdb.sqltypes import (
    BOOL,
    INT8, INT16, INT32, INT64, INT128, INT256,
    UINT8, UINT16, UINT32, UINT64, UINT128, UINT256,
    FLOAT32, FLOAT64,
    STRING,
    DATE, DATE32, DATETIME, DATETIME64,
)
```

#### Автоматическое сопоставление типов

Если типы определяются на основе аннотаций Python, используется следующее сопоставление:

| Тип Python | Тип ClickHouse |
| - | - |
| `bool` | `Bool` |
| `int` | `Int64` |
| `float` | `Float64` |
| `str` | `String` |
| `bytes` | `String` |
| `bytearray` | `String` |
| `datetime.date` | `Date` |
| `datetime.datetime` | `DateTime64(6)` |

#### Способы задания типов

Типы можно задавать несколькими способами:

```python theme={null}
from chdb import create_function, func
from chdb.sqltypes import INT64

# 1. ChdbType constants
create_function("f1", lambda x: x, arg_types=[INT64], return_type=INT64)

# 2. ClickHouse type strings
create_function("f2", lambda x: x, arg_types=["Int64"], return_type="Int64")

# 3. Parameterized type strings
create_function("f3", lambda x: x, arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")

# 4. Python types — passed directly or used as annotations
create_function("f4", lambda x: x, arg_types=[int], return_type=int)

@func()
def f5(x: int) -> int:
    return x
```

***

### Обработка NULL

Настройте обработку значений NULL с помощью параметра `on_null`.

| Значение | Enum | Поведение |
| - | - | - |
| `"skip"` | `NullHandling.SKIP` | Вернуть NULL без вызова функции (по умолчанию) |
| `"pass"` | `NullHandling.PASS` | Преобразовать NULL в `None` и вызвать функцию |

```python theme={null}
from chdb import func, query, NullHandling

# Default: NULL in → NULL out, function not called
@func(return_type="Int64")
def add_one(x: int) -> int:
    return x + 1

print(query("SELECT add_one(NULL)"))  # NULL

# Pass NULL as None
@func(return_type="Int64", on_null="pass")
def null_safe(x):
    return 0 if x is None else x + 1

print(query("SELECT null_safe(NULL)"))  # 0
```

***

### Обработка исключений

Управляйте обработкой исключений с помощью параметра `on_error`.

| Значение | Enum | Поведение |
| - | - | - |
| `"propagate"` | `ExceptionHandling.PROPAGATE` | Вызвать исключение в виде SQL-ошибки (по умолчанию) |
| `"ignore"` | `ExceptionHandling.IGNORE` | Перехватить исключение и вернуть NULL |

```python theme={null}
from chdb import func, query

# Default: exception propagates
@func(arg_types=["Int64", "Int64"], return_type="Int64")
def divide(a, b):
    return a // b

# print(query("SELECT divide(1, 0)"))  # Error: division by zero

# Ignore: exception → NULL
@func(arg_types=["Int64", "Int64"], return_type="Int64", on_error="ignore")
def safe_divide(a, b):
    return a // b

print(query("SELECT safe_divide(1, 0)"))   # NULL
print(query("SELECT safe_divide(10, 2)"))  # 5
```

***

### Поддержка DateTime и часовых поясов

Пользовательские функции (UDF) полностью поддерживают типы `Date`, `Date32`, `DateTime` и `DateTime64` с поддержкой часовых поясов.

```python theme={null}
from chdb import func, query
from datetime import datetime, timedelta, date

@func(arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")
def add_one_hour(dt):
    return dt + timedelta(hours=1)

@func()
def get_year(d: date) -> int:
    return d.year

print(query("SELECT add_one_hour(toDateTime('2024-01-01 12:00:00', 'UTC'))"))  # 2024-01-01 13:00:00
print(query("SELECT get_year(toDate('2024-06-15'))"))  # 2024
```

* Входные значения ClickHouse `DateTime`/`DateTime64` преобразуются в объекты Python `datetime` с информацией о часовом поясе
* При возврате в ClickHouse выходные объекты Python `datetime` сохраняют информацию о часовом поясе
* Тип `DATETIME64` из `chdb.sqltypes` по умолчанию имеет scale 6 (микросекунды), что эквивалентно `DateTime64(6)`

***

### Устаревший API

> [!WARNING]
>
> **Устарело:** декоратор `@chdb_udf` — устаревший механизм UDF на основе подпроцессов: он запускает вашу функцию в отдельном процессе Python и передаёт все аргументы в виде строк. Он по-прежнему доступен, но рекомендуется нативный API UDF Python ([`@func`](#func-decorator) / [`create_function`](#create-function)): нативные пользовательские функции (UDF) выполняются в том же процессе, поддерживают типизированные аргументы, обработку NULL и контроль исключений. Полное пошаговое руководство см. в [руководстве по UDF Python](https://clickhouse.com/docs/ru/chdb/guides/python-udf.md).

#### `chdb.udf.chdb_udf`

Декоратор для Python UDF (пользовательская функция) в chDB.

**Синтаксис**

```python theme={null}
chdb.udf.chdb_udf(return_type='String')
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `return_type` | str | `"String"` | Возвращаемый тип функции. Должен быть одним из типов данных ClickHouse |

**Примечания**

1. Функция должна быть без сохранения состояния. Поддерживаются только UDF, а не UDAF.
2. Возвращаемый тип по умолчанию — String. Он должен быть одним из типов данных ClickHouse.
3. Функция должна принимать аргументы типа String. Все аргументы являются строками.
4. Функция будет вызываться для каждой строки входных данных.
5. Функция должна быть чистой функцией Python. Импортируйте все модули, используемые в самой функции.
6. Используется тот же интерпретатор Python, что и для запуска скрипта.

**Пример**

```python theme={null}
@chdb_udf()
def sum_udf(lhs, rhs):
    return int(lhs) + int(rhs)

@chdb_udf()
def func_use_json(arg):
    import json
    # ... use json module
```

***

#### `chdb.udf.generate_udf`

Генерирует файлы конфигурации UDF и исполняемого скрипта.

Эта функция создает необходимые файлы для пользовательской функции (UDF) в chDB:

1. Исполняемый Python-скрипт для обработки входных данных
2. XML-файл конфигурации, который регистрирует UDF в ClickHouse

**Синтаксис**

```python theme={null}
chdb.udf.generate_udf(func_name, args, return_type, udf_body)
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `func_name` | str | Имя функции UDF |
| `args` | list | Список имён аргументов функции |
| `return_type` | str | Возвращаемый тип функции в ClickHouse |
| `udf_body` | str | Тело исходного кода Python для функции UDF |

> [!NOTE]
>
> Эта функция обычно вызывается декоратором @chdb\_udf, и её не следует
> вызывать напрямую.

***

## Утилиты

Служебные функции и вспомогательные средства для chDB.

Этот модуль содержит различные утилиты для работы с chDB, включая
вывод типов, средства преобразования данных и инструменты отладки.

***

### `chdb.utils.convert_to_columnar`

Преобразует список словарей в столбцовый формат.

Эта функция принимает список словарей и преобразует его в словарь,
где каждый ключ соответствует столбцу, а каждое значение — это список значений столбца.
Отсутствующие значения в словарях обозначаются как None.

**Синтаксис**

```python theme={null}
chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `items` | `List[Dict[str, Any]]` | Список словарей для преобразования |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `Dict[str, List[Any]]` | Словарь, в котором ключи — имена столбцов, а значения — списки значений этих столбцов |

**Пример**

```pycon theme={null}
>>> items = [
...     {"name": "Alice", "age": 30, "city": "New York"},
...     {"name": "Bob", "age": 25},
...     {"name": "Charlie", "city": "San Francisco"}
... ]
>>> convert_to_columnar(items)
{
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [30, 25, None],
    'city': ['New York', None, 'San Francisco']
}
```

***

### `chdb.utils.flatten_dict`

Преобразует вложенный словарь в плоский.

Эта функция принимает вложенный словарь и преобразует его в плоский, объединяя вложенные ключи
с помощью разделителя. Списки словарей сериализуются в JSON-строки.

**Синтаксис**

```python theme={null}
chdb.utils.flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') → Dict[str, Any]
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `d` | `Dict[str, Any]` | *required* | Словарь, который нужно преобразовать в плоскую структуру |
| `parent_key` | str | `""` | Базовый ключ, добавляемый в начало каждого ключа |
| `sep` | str | `"_"` | Разделитель между объединёнными ключами |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `Dict[str, Any]` | Словарь в плоском виде |

**Пример**

```pycon theme={null}
>>> nested_dict = {
...     "a": 1,
...     "b": {
...         "c": 2,
...         "d": {
...             "e": 3
...         }
...     },
...     "f": [4, 5, {"g": 6}],
...     "h": [{"i": 7}, {"j": 8}]
... }
>>> flatten_dict(nested_dict)
{
    'a': 1,
    'b_c': 2,
    'b_d_e': 3,
    'f_0': 4,
    'f_1': 5,
    'f_2_g': 6,
    'h': '[{"i": 7}, {"j": 8}]'
}
```

***

### `chdb.utils.infer_data_type`

Определяет наиболее подходящий тип данных для списка значений.

Эта функция анализирует список значений и определяет наиболее подходящий
тип данных, который может представлять все значения в списке. Она учитывает целочисленные,
беззнаковые целочисленные, десятичные типы и типы с плавающей точкой и по умолчанию использует «string», если
значения не могут быть представлены ни одним числовым типом или если все значения — None.

**Синтаксис**

```python theme={null}
chdb.utils.infer_data_type(values: List[Any]) → str
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `values` | `List[Any]` | Список значений для анализа. Значения могут быть любого типа |

**Возвращаемое значение**

| Тип возвращаемого значения | Описание |
| - | - |
| `str` | Строка, представляющая автоматически определённый тип данных. Возможные возвращаемые значения: ”int8”, “int16”, “int32”, “int64”, “int128”, “int256”, “uint8”, “uint16”, “uint32”, “uint64”, “uint128”, “uint256”, “decimal128”, “decimal256”, “float32”, “float64” или “string”. |

> [!NOTE]
>
> * Если все значения в списке — None, функция возвращает “string”.
> * Если хотя бы одно значение в списке является строкой, функция сразу возвращает “string”.
> * Функция предполагает, что числовые значения могут быть представлены как целые числа,
>   десятичные числа или числа с плавающей точкой в зависимости от их диапазона и точности.

***

### `chdb.utils.infer_data_types`

Определяет типы данных для каждого столбца в столбцовой структуре данных.

Эта функция анализирует значения в каждом столбце и определяет наиболее подходящий
тип данных для каждого столбца на основе выборки данных.

**Синтаксис**

```python theme={null}
chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple]
```

**Параметры**

| Параметр | Тип | По умолчанию | Описание |
| - | - | - | - |
| `column_data` | `Dict[str, List[Any]]` | *обязательно* | Словарь, где ключи — имена столбцов, а значения — списки значений этих столбцов |
| `n_rows` | int | `10000` | Количество строк для выборки при выводе типов |

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `List[tuple]` | Список кортежей, каждый из которых содержит имя столбца и автоматически определённый тип данных |

## Абстрактные базовые классы

### **class** `chdb.rwabc.PyReader`(data: Any)\`

Базовый класс: `ABC`

```python theme={null}
class chdb.rwabc.PyReader(data: Any)
```

***

#### **abstractmethod** `read`

Считывает указанное количество строк из заданных столбцов и возвращает список объектов,
где каждый объект содержит последовательность значений одного столбца.

```python theme={null}
abstractmethod (col_names: List[str], count: int) → List[Any]
```

**Параметры**

| Parameter | Type | Description |
| - | - | - |
| `col_names` | `List[str]` | Список имён столбцов для чтения |
| `count` | int | Максимальное количество строк для чтения |

**Возвращаемое значение**

| Return Type | Description |
| - | - |
| `List[Any]` | Список последовательностей, по одной для каждого столбца |

### **class** `chdb.rwabc.PyWriter`

Базовый класс: `ABC`

```python theme={null}
class chdb.rwabc.PyWriter(col_names: List[str], types: List[type], data: Any)
```

***

#### **abstractmethod** finalize

Формирует и возвращает итоговые данные из блоков. Метод должен быть реализован в подклассах.

```python theme={null}
abstractmethod finalize() → bytes
```

**Возвращает**

| Возвращаемый тип | Описание |
| - | - |
| `bytes` | Итоговые сериализованные данные |

***

#### **abstractmethod** `write`

Записывает столбцы данных в блоки. Должен быть реализован в подклассах.

```python theme={null}
abstractmethod write(col_names: List[str], columns: List[List[Any]]) → None
```

**Параметры**

| Параметр | Тип | Описание |
| - | - | - |
| `col_names` | `List[str]` | Список имён столбцов, в которые записываются данные |
| `columns` | `List[List[Any]]` | Список данных по столбцам; каждый столбец представлен списком |

## Обработка исключений

### **class** `chdb.ChdbError`

Базовый класс: `Exception`

Базовый класс исключений для ошибок, связанных с chDB.

Это исключение возникает, когда выполнение запроса chDB завершается неудачно
или приводит к ошибке. Оно наследуется от стандартного класса Python Exception и
содержит сведения об ошибке из базового движка ClickHouse.

Сообщение исключения обычно содержит подробную информацию об ошибке
из ClickHouse, включая синтаксические ошибки, несоответствия типов, отсутствие
таблиц/столбцов и другие проблемы при выполнении запроса.

**Переменные**

| Переменная | Type | Описание |
| - | - | - |
| `args` | - | Tuple, содержащий сообщение об ошибке и любые дополнительные аргументы |

**Примеры**

```pycon theme={null}
>>> 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
```

```pycon theme={null}
>>> 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]
>
> Это исключение автоматически генерируется функцией chdb.query() и связанными
> функциями, когда движок ClickHouse сообщает об ошибке.
> Вам следует перехватывать это исключение при обработке запросов, которые
> могут завершиться с ошибкой, чтобы обеспечить надлежащую обработку ошибок в вашем приложении.

## Сведения о версии

### `chdb.chdb_version = ('3', '6', '0')`

Встроенная неизменяемая последовательность.

Если аргумент не указан, конструктор возвращает пустой кортеж.
Если указан `iterable`, кортеж инициализируется его элементами.

Если аргумент является кортежем, возвращается тот же объект.

***

### `chdb.engine_version = '25.5.2.1'`

```python theme={null}
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
```

Создаёт новый строковый объект из указанного объекта. Если заданы encoding или
errors, объект должен предоставлять буфер данных,
который будет декодирован с использованием указанной кодировки и обработчика ошибок.
В противном случае возвращает результат object.*\_str*\_() (если он определён)
или repr(object).

* encoding по умолчанию — ‘utf-8’.
* errors по умолчанию — ‘strict’.

***

### `chdb.__version__ = '3.6.0'`

```python theme={null}
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
```

Создаёт новый строковый объект из указанного объекта. Если заданы encoding или
errors, объект должен предоставлять буфер данных,
который будет декодирован с использованием указанной кодировки и обработчика ошибок.
В противном случае возвращается результат object.*\_str*\_() (если он определён)
или repr(object).

* encoding по умолчанию — ‘utf-8’.
* errors по умолчанию — ‘strict’.