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

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

`chdb.query`

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

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

Синтаксис

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"` — Pandas DataFrame • `"ArrowTable"` — PyArrow Table • `"Debug"` — включает подробное журналирование
`path`	str	`""`	Путь к файлу базы данных. По умолчанию используется база данных в оперативной памяти. Может быть путём к файлу или `":memory:"` для базы данных в памяти
`udf_path`	str	`""`	Путь к каталогу с пользовательскими функциями (User-Defined Functions)

Возвращает

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

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

Исключения

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

Примеры

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

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

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

>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")

`chdb.sql`

Выполнение SQL‑запроса с использованием движка chDB.

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

Синтаксис

chdb.sql(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"` — Pandas DataFrame • `"ArrowTable"` — PyArrow Table • `"Debug"` — включает подробное журналирование
`path`	str	`""`	Путь к файлу базы данных. По умолчанию используется база данных в оперативной памяти. Может быть путём к файлу или `":memory:"` для базы данных в памяти
`udf_path`	str	`""`	Путь к каталогу с пользовательскими функциями (User-Defined Functions)

Возвращает

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

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

Исключения

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

Примеры

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

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

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

>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")

`chdb.to_arrowTable`

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

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

Синтаксис

chdb.to_arrowTable(res)

Параметры

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

Возвращает

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

Исключения

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

Пример

>>> 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 Table, а затем — в pandas с использованием многопоточности для повышения производительности.

Синтаксис

chdb.to_df(r)

Параметры

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

Возвращает

Тип возврата	Описание
`pd.DataFrame`	объект pandas DataFrame, содержащий результаты запроса

Исключения

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

Пример

>>> 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 (ClickHouse). В одном процессе допускается только одно открытое подключение. Многократные вызовы с одной и той же строкой подключения будут возвращать один и тот же объект подключения.

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()
• Протокол контекстного менеджера для автоматической очистки

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

Исключения

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

Примечание

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

Примеры

>>> # In-memory 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.ChdbError`

Bases: Exception

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

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

class `chdb.session.Session`

Bases: object

Session хранит состояние запроса. Если path равно None, будет создана временная директория и использована как путь к базе данных, а временная директория будет удалена при закрытии сессии. Вы также можете передать путь для создания базы данных по этому пути, где будут храниться ваши данные.

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

class chdb.session.Session(path=None)

Примеры

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

Обработка аргументов в строке подключения

Строки подключения, содержащие query-параметры, такие как “file:test.db?param1=value1&param2=value2” «param1=value1» будут переданы в движок ClickHouse как аргументы запуска.

Для получения дополнительной информации см. clickhouse local –help –verbose.

Особый порядок обработки некоторых аргументов:

«mode=ro» будет соответствовать «–readonly=1» для ClickHouse (режим только для чтения)

Важно

Одновременно может быть только одна сессия. Если вы хотите создать новую сессию, необходимо закрыть существующую.
Создание новой сессии приведёт к закрытию существующей.

`cleanup`

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

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

Синтаксис

cleanup()

Примечание

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

Примеры

>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Safe cleanup regardless of errors

См. также

close() — для явного закрытия сессии с пробросом ошибок

`close`

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

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

Синтаксис

close()

Примечание

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

Важно

Любая попытка использовать сессию после вызова close() приведёт к ошибке.

Примеры

>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close()  # Explicitly close the session

`query`

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

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

Синтаксис

query(sql, fmt='CSV', udf_path='')

Параметры

Parameter	Type	Default	Description
`sql`	str	required	Строка SQL‑запроса, который нужно выполнить
`fmt`	str	`"CSV"`	Формат вывода результатов. Доступные форматы: • `"CSV"` — значения, разделённые запятыми • `"JSON"` — формат JSON • `"TabSeparated"` — значения, разделённые табуляцией • `"Pretty"` — формат таблицы с удобочитаемым выводом • `"JSONCompact"` — компактный формат JSON • `"Arrow"` — формат Apache Arrow • `"Parquet"` — формат Parquet
`udf_path`	str	`""`	Путь к пользовательским функциям (UDF). Если не указан, используется путь к UDF, заданный при инициализации сессии

Возвращает

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

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

Исключения

Exception	Condition
`RuntimeError`	Если сессия закрыта или недействительна
`ValueError`	Если SQL‑запрос содержит синтаксические ошибки

Примечание

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

Warning

Этот метод выполняет запрос синхронно и загружает все результаты в память. Для больших объёмов данных рассмотрите использование send_query() для потоковой передачи результатов.

Примеры

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

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

>>> # 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() - Для потокового выполнения запросов
sql - Псевдоним этого метода

`send_query`

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

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

Синтаксис

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` или быть преобразован в другие структуры данных

Исключения

Exception	Condition
`RuntimeError`	Если сессия закрыта или недействительна
`ValueError`	Если SQL‑запрос содержит синтаксические ошибки

Примечание

Возвращаемый объект StreamingResult должен быть своевременно обработан или корректно сохранён, так как он поддерживает соединение с базой данных.

Примеры

>>> session = Session("test.db")
>>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id")
>>>
>>> # Insert large dataset
>>> for i in range(1000):
...     session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')")
>>>
>>> # Stream results to avoid memory issues
>>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id")
>>> for chunk in streaming_result:
...     print(f"Processing chunk: {len(chunk)} bytes")
...     # Process chunk without loading entire result set

>>> # 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.state.sqlitelike.StreamingResult - Потоковый итератор результатов

`sql`

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

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

Синтаксис

sql(sql, fmt='CSV', udf_path='')

Параметры

Параметр	Тип	Значение по умолчанию	Описание
`sql`	str	обязателен	Строка SQL‑запроса для выполнения
`fmt`	str	`"CSV"`	Формат вывода результатов. Доступные форматы: • `"CSV"` — значения, разделённые запятыми • `"JSON"` — формат JSON • `"TabSeparated"` — значения, разделённые табуляцией • `"Pretty"` — формат таблицы с удобочитаемым выводом • `"JSONCompact"` — компактный формат JSON • `"Arrow"` — формат Apache Arrow • `"Parquet"` — формат Parquet
`udf_path`	str	`""`	Путь к пользовательским функциям (UDF). Если не указан, используется путь к UDF из инициализации сессии

Возвращает

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

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

Исключения:

Исключение	Условие
`RuntimeError`	Если сессия закрыта или недействительна
`ValueError`	Если SQL‑запрос составлен некорректно

Примечание

Формат "Debug" не поддерживается и будет автоматически преобразован в "CSV" с предупреждением. Для отладки вместо этого используйте параметры строки подключения.

Warning

Этот метод выполняет запрос синхронно и загружает все результаты в память. Для больших наборов данных рассмотрите использование send_query() для потоковой загрузки результатов.

Примеры

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

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

>>> # 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() — для потокового выполнения запросов
sql — синоним этого метода

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

`chdb.state.connect`

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

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

Синтаксис

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()
• протокол контекстного менеджера для автоматической очистки

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

Исключения

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

Предупреждение

Поддерживается только одно подключение на процесс. Создание нового подключения закроет существующее подключение.

Примеры

>>> # In-memory 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

Синтаксис

class chdb.state.sqlitelike.Connection(connection_string: str)

`close`

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

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

Синтаксис

close() → None

Примечание

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

Предупреждение

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

Примеры

>>> conn = connect("test.db")
>>> # Use connection for queries
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Close when done
>>> conn.close()

>>> # Using with context manager (automatic cleanup)
>>> with connect("test.db") as conn:
...     conn.query("SELECT 1")
...     # Connection automatically closed

`cursor`

Создаёт объект Cursor для выполнения запросов.

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

Синтаксис

cursor() → Cursor

Возвращает

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

Примечание

Создание нового курсора приведёт к замене любого существующего курсора, связанного с этим соединением. Поддерживается только один курсор на соединение.

Примеры

>>> 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 — реализация курсора базы данных

`query`

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

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

Синтаксис

query(query: str, format: str = 'CSV') → Any

Параметры:

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

Возвращает

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

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

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

Предупреждение

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

Примеры

>>> conn = connect(":memory:")
>>>
>>> # Basic CSV query
>>> result = conn.query("SELECT 1 as num, 'hello' as text")
>>> print(result)
num,text
1,hello

>>> # DataFrame format
>>> df = conn.query("SELECT number FROM numbers(5)", "dataframe")
>>> print(df)
   number
0       0
1       1
2       2
3       3
4       4

См. также

send_query() - Для потокового выполнения запросов

`send_query`

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

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

Синтаксис

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)

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

Исключения

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

Примечание

Только формат "Arrow" поддерживает метод record_batch() для возвращаемого StreamingResult.

Примеры

>>> conn = connect(":memory:")
>>>
>>> # Basic streaming
>>> stream = conn.send_query("SELECT number FROM numbers(1000)")
>>> for chunk in stream:
...     print(f"Processing chunk: {len(chunk)} bytes")

>>> # Using context manager for cleanup
>>> with conn.send_query("SELECT * FROM large_table") as stream:
...     chunk = stream.fetch()
...     while chunk:
...         process_data(chunk)
...         chunk = stream.fetch()

>>> # Arrow format with RecordBatch streaming
>>> 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() — Для выполнения запросов без потоковой передачи
StreamingResult — Итератор потокового результата

class `chdb.state.sqlitelike.StreamingResult`

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

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

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

class chdb.state.sqlitelike.StreamingResult

`fetch`

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

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

Синтаксис

fetch() → Any

Возвращает

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

Примеры

>>> stream = conn.send_query("SELECT * FROM large_table")
>>> chunk = stream.fetch()
>>> while chunk is not None:
...     process_data(chunk)
...     chunk = stream.fetch()

`cancel`

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

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

Синтаксис

cancel() → None

Примеры

>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Only process first 10 chunks
...         stream.cancel()
...         break
...     process_data(chunk)

`close`

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

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

Синтаксис

close() → None

`record_batch`

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

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

Синтаксис

record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader

Параметры

Параметр	Тип	Значение по умолчанию	Описание
`rows_per_batch`	int	`1000000`	Количество строк в пакете

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

Тип возвращаемого значения	Описание
`pa.RecordBatchReader`	PyArrow RecordBatchReader для итерации по пакетам

Примечание

Этот метод доступен только в том случае, если потоковый запрос был запущен с format="Arrow". Использование его с другими форматами приведёт к ошибке.

Примеры

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

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

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

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

>>> with conn.send_query("SELECT * FROM data") as stream:
...     for chunk in stream:
...         process(chunk)
>>> # Stream automatically closed

class `chdb.state.sqlitelike.Cursor`

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

class chdb.state.sqlitelike.Cursor(connection)

`close`

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

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

Синтаксис

close() → None

Примечание

Этот метод идемпотентен — его можно безопасно вызывать многократно. Курсор также автоматически закрывается при закрытии соединения.

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Cleanup cursor resources

`column_names`

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

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

Синтаксис

column_names() → list

Возвращает

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

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name, email FROM users LIMIT 1")
>>> print(cursor.column_names())
['id', 'name', 'email']

См. также

column_types() - Получить информацию о типах столбцов
description - Описание столбцов по стандарту DB-API 2.0

`column_types`

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

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

Синтаксис

column_types() → list

Возвращает

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

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT toInt32(1), toString('hello')")
>>> print(cursor.column_types())
['Int32', 'String']

См. также

column_names() — Получение информации об именах столбцов
description — Описание столбцов по стандарту DB-API 2.0

`commit`

Фиксирует все незавершённые транзакции.

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

Примечание

ClickHouse, как правило, автоматически фиксирует операции, поэтому явный commit обычно не требуется. Этот метод предусмотрен для совместимости со стандартным рабочим процессом DB-API 2.0.

Синтаксис

commit() → None

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
>>> cursor.commit()

`property 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 не был выполнен

Примечание

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

Примеры

>>> 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() — Получить только имена столбцов
column_types() — Получить только типы столбцов

`execute`

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

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

Синтаксис

execute(query: str) → None

Параметры:

Параметр	Тип	Описание
`query`	str	SQL‑запрос для выполнения

Исключения

Исключение	Условие
`Exception`	Если выполнение запроса или разбор результата завершается ошибкой

Примечание

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

Примечание

Метод автоматически преобразует типы данных ClickHouse в соответствующие типы Python:

типы Int/UInt → int
типы Float → float
String/FixedString → str
DateTime → datetime.datetime
Date → datetime.date
Bool → bool

Примеры

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

См. также

fetchone() - Извлекает одну строку
fetchmany() - Извлекает несколько строк
fetchall() - Извлекает все оставшиеся строки

`fetchall`

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

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

Синтаксис

fetchall() → tuple

Возвращает:

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

Предупреждение

Этот метод загружает все оставшиеся строки в память за один раз. Для больших наборов результатов используйте fetchmany() для поэтапной обработки результатов.

Примеры

>>> 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() - Извлечение одной строки
fetchmany() - Извлечение нескольких строк пакетами

`fetchmany`

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

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

Синтаксис

fetchmany(size: int = 1) → tuple

Параметры

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

Возвращает

Тип возвращаемого значения	Описание
`tuple`	Кортеж, содержащий до 'size' кортежей строк. Может содержать меньше строк, если результирующий набор исчерпан

Примечание

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

Примеры

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

См. также

fetchone() - Получает одну строку
fetchall() - Получает все оставшиеся строки

`fetchone`

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

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

Синтаксис

fetchone() → tuple | None

Возвращает:

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

Примечание

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

Примеры

>>> 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() - Извлечь несколько строк
fetchall() - Извлечь все оставшиеся строки

`chdb.state.sqlitelike`

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

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

Синтаксис

chdb.state.sqlitelike.to_arrowTable(res)

Параметры:

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

Возвращает

Return Type	Description
`pyarrow.Table`	Таблица PyArrow, содержащая результаты запроса

Исключения

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

Примечание

Для работы этой функции необходима установка и pyarrow, и pandas. Установите их с помощью: pip install pyarrow pandas

Warning

При отсутствии результатов возвращается пустая таблица PyArrow без схемы.

Примеры

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

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

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

Синтаксис

chdb.state.sqlitelike.to_df(r)

Параметры:

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

Возвращает:

Тип возвращаемого значения	Описание
`pandas.DataFrame`	Объект DataFrame, содержащий результаты запроса с корректными именами столбцов и типами данных

Исключения

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

Примечание

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

См. также

to_arrowTable() — для преобразования в формат таблицы PyArrow

Примеры

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

Родительские классы:

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 включает:

Connections: управление подключениями к базе данных с помощью строк подключения
Cursors: выполнение запросов и получение результатов
Type System: константы типов и конвертеры, совместимые с DB-API 2.0
Error Handling: стандартная иерархия исключений базы данных
Thread Safety: уровень потокобезопасности 1 (потоки могут совместно использовать модули, но не подключения)

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

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

`chdb.dbapi.connect`

Создать новое подключение к базе данных.

Синтаксис

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

Параметры

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

Исключения

Исключение	Условие
`err.Error`	Если соединение не может быть установлено

`chdb.dbapi.get_client_info()`

Получить информацию о версии клиента.

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

Синтаксис

chdb.dbapi.get_client_info()

Возвращает

Тип возвращаемого значения	Описание
`str`	Строка версии в формате 'major.minor.patch'

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

`chdb.dbapi.Binary(x)`

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

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

Синтаксис

chdb.dbapi.Binary(x)

Параметры

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

Возвращает

Тип возвращаемого значения	Описание
`bytes`	Входные данные, преобразованные в байты

Класс Connection

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

Bases: object

Соединение с базой данных chDB, совместимое с DB-API 2.0.

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

Соединение управляет базовым движком chDB и предоставляет методы для выполнения запросов, управления транзакциями (операции с транзакциями не выполняются — no-op для ClickHouse) и создания курсоров.

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

Параметры

Parameter	Type	Default	Description
`path`	str	`None`	Путь к файлу базы данных. Если указано None, используется база данных в памяти. Может быть путем к файлу, например 'database.db', или None для ':memory:'

Переменные

Variable	Type	Description
`encoding`	str	Кодировка символов для запросов, по умолчанию 'utf8'
`open`	bool	True, если соединение открыто, False, если закрыто

Примеры

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

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

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

Примечание

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

`close`

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

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

Синтаксис

close()

Исключения

Исключение	Условие
`err.Error`	Если соединение уже закрыто

`commit`

Подтверждает текущую транзакцию.

Синтаксис

commit()

Примечание

Это операция-заглушка для chDB/ClickHouse, так как эти системы не поддерживают традиционные транзакции. Предоставляется для совместимости с DB-API 2.0.

`cursor`

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

Синтаксис

cursor(cursor=None)

Параметры

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

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

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

Исключения

Исключение	Условие
`err.Error`	Если соединение закрыто

Пример

>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1")
>>> result = cur.fetchone()

`escape`

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

Синтаксис

escape(obj, mapping=None)

Параметры

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

Возвращает

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

Пример

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

`escape_string`

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

Синтаксис

escape_string(s)

Параметры

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

Возвращает

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

`property open`

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

Возвращает

Тип возвращаемого значения	Описание
`bool`	True, если соединение открыто, False, если закрыто

`query`

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

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

Синтаксис

query(sql, fmt='CSV')

Параметры:

Параметр	Тип	Значение по умолчанию	Описание
`sql`	str или bytes	обязательно	SQL-запрос для выполнения
`fmt`	str	`"CSV"`	Формат вывода. Поддерживаемые форматы включают «CSV», «JSON», «Arrow», «Parquet» и др.

Возвращает

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

Исключения

Исключение	Условие
`err.InterfaceError`	Если соединение закрыто или выполнение запроса завершилось ошибкой

Пример

>>> conn = Connection()
>>> result = conn.query("SELECT 1, 'hello'", "CSV")
>>> print(result)
"1,hello\n"

`property resp`

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

Returns

Return Type	Description
-	Необработанный ответ от последнего вызова query()

Примечание

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

`rollback`

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

Синтаксис

rollback()

Примечание

Эта операция не выполняет никаких действий (no-op) для 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().

class chdb.dbapi.cursors.Cursor(connection)

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

Примеры

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

Примечание

См. DB-API 2.0 Cursor Objects для полного описания спецификации.

`callproc`

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

Синтаксис

callproc(procname, args=())

Параметры

Параметр	Тип	Описание
`procname`	str	Имя хранимой процедуры, которую нужно выполнить
`args`	sequence	Параметры, передаваемые в процедуру

Возвращает

Тип возвращаемого значения	Описание
`sequence`	Исходный параметр args (без изменений)

Примечание

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

Совместимость

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

`close`

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

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

Синтаксис

close()

`execute`

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

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

Синтаксис

execute(query, args=None)

Параметры

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

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

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

Форматы параметров

Стиль	Пример
Стиль с вопросительным знаком	`"SELECT * FROM users WHERE id = ?"`
Именованный стиль	`"SELECT * FROM users WHERE name = %(name)s"`
Стиль форматирования	`"SELECT * FROM users WHERE age = %s"` (устаревший)

Примеры

>>> # Question mark parameters
>>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
>>>
>>> # Named parameters
>>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
>>>
>>> # No parameters
>>> cur.execute("SELECT COUNT(*) FROM users")

Исключения

Исключение	Условие
`ProgrammingError`	Если курсор закрыт или запрос некорректен
`InterfaceError`	Если во время выполнения произошла ошибка базы данных

`executemany(query, args)`

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

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

Синтаксис

executemany(query, args)

Параметры

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

Возвращает

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

Примеры

>>> # Bulk insert with question mark parameters
>>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
>>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
>>>
>>> # Bulk insert with named parameters
>>> users_data = [
...     {'id': 1, 'name': 'Alice'},
...     {'id': 2, 'name': 'Bob'}
... ]
>>> cur.executemany(
...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
...     users_data
... )

Примечание

Этот метод повышает производительность операций INSERT и UPDATE с несколькими строками за счёт оптимизации процесса выполнения запроса.

`fetchall()`

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

Синтаксис

fetchall()

Возвращает

Тип возвращаемого значения	Описание
`list`	Список кортежей, представляющих все оставшиеся строки

Исключения

Исключение	Условие
`ProgrammingError`	Если сначала не был вызван `execute()`

Предупреждение

Этот метод может потреблять большой объём памяти для больших наборов результатов. Рассмотрите использование fetchmany() для больших наборов данных.

Пример

>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_rows))  # Number of total rows

`fetchmany`

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

Синтаксис

fetchmany(size=1)

Параметры

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

Возвращает

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

Исключения

Исключение	Условие
`ProgrammingError`	Если `execute()` не был вызван ранее

Пример

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

`fetchone`

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

Синтаксис

fetchone()

Возвращает

Тип возвращаемого значения	Описание
`tuple or None`	Следующая строка в виде кортежа или `None`, если больше строк нет

Исключения

Исключение	Условие
`ProgrammingError`	Если `execute()` не был вызван сначала

Пример

>>> 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().

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

`mogrify`

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

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

Синтаксис

mogrify(query, args=None)

Параметры

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

Возвращает

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

Пример

>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"

Примечание

Этот метод соответствует расширению DB-API 2.0, используемому в Psycopg.

`nextset`

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

Синтаксис

nextset()

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

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

Примечание

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

`setinputsizes`

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

Синтаксис

setinputsizes(*args)

Параметры

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

Примечание

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

`setoutputsizes`

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

Синтаксис

setoutputsizes(*args)

Параметры

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

Примечание

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

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

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

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

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

StandardError
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError

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

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

Примечание

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

См. также

Python Database API Specification v2.0
chdb.dbapi.connections — управление подключениями к базе данных
chdb.dbapi.cursors — операции с курсорами базы данных

Примеры

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

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

исключение `chdb.dbapi.err.DataError`

Базовый класс: DatabaseError

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

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

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

Вызывает

Исключение	Условие
`DataError`	При ошибке проверки или обработки данных

Примеры

>>> # Division by zero in SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero

>>> # Invalid date format
>>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
DataError: Invalid date format

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

Базовый класс: Error

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

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

Типичные сценарии включают:

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

Примечание

Выступает родительским классом для более специализированных типов ошибок базы данных, таких как DataError, OperationalError и др.

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

Базовый класс: StandardError

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

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

Примечание

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

См. также

Warning — для нефатальных предупреждений, которые не препятствуют завершению операций

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

Базовый класс: DatabaseError

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

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

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

Генерируемые исключения

Исключение	Условие
`IntegrityError`	При нарушении ограничений целостности базы данных

Примеры

>>> # Duplicate primary key
>>> 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'

>>> # Foreign key violation
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails

exception `chdb.dbapi.err.InterfaceError`

Bases: Error

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

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

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

Исключения

Исключение	Условие
`InterfaceError`	Когда интерфейс базы данных сталкивается с ошибками, не связанными с операциями с БД

Примечание

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

exception `chdb.dbapi.err.InternalError`

Bases: DatabaseError

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

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

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

Исключения

Исключение	Условие
`InternalError`	Когда база данных сталкивается с внутренними несоответствиями

Warning

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

Примечание

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

exception `chdb.dbapi.err.NotSupportedError`

Bases: DatabaseError

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

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

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

Исключения

Исключение	Условие
`NotSupportedError`	Когда осуществляется доступ к неподдерживаемым функциям базы данных

Примеры

>>> # Transaction rollback on non-transactional connection
>>> connection.rollback()
NotSupportedError: Transactions are not supported

>>> # Using unsupported SQL syntax
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version

Примечание

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

exception `chdb.dbapi.err.OperationalError`

Bases: DatabaseError

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

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

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

Raises

Exception	Condition
`OperationalError`	Когда операции с базой данных завершаются сбоем по операционным причинам

Примечание

Эти ошибки, как правило, временные и могут быть устранены повторным выполнением операции или решением проблем на системном уровне.

Warning

Некоторые операционные ошибки могут указывать на серьёзные проблемы в системе, требующие вмешательства администратора.

exception `chdb.dbapi.err.ProgrammingError`

Bases: DatabaseError

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

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

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

Raises

Исключение	Условие
`ProgrammingError`	Когда SQL‑выражения или использование API содержат ошибки

Examples

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

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

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

exception `chdb.dbapi.err.StandardError`

Bases: Exception

Исключение, связанное с операциями с chdb.

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

Примечание

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

exception `chdb.dbapi.err.Warning`

Bases: StandardError

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

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

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

Примечание

Это соответствует спецификации Python DB API 2.0 для исключений-предупреждений.

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

`chdb.dbapi.apilevel = '2.0'`

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`

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

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

Если x не является числом или указан base, то x должен быть строкой, объектом bytes или bytearray, представляющим целочисленный литерал в заданной системе счисления. Литерал может начинаться с «+» или «-» и быть окружён пробельными символами. Система счисления по умолчанию — 10. Допустимые значения системы счисления: 0 и 2–36. Значение 0 означает, что основание системы счисления определяется по строке, как для целочисленного литерала.

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

`chdb.dbapi.paramstyle = 'format'`

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 — это одиночное значение типа.

Примеры

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

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

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

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

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

Примеры

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

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

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

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

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

Примеры

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

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

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

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

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

Примеры

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

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

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

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

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

Примеры

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

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

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

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

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

Примеры

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

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

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

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

Примеры

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

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

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

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

Он используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы выполнять сравнения вида «field_type == STRING», где field_type — это одиночное значение типа.

Примеры

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

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

Простой пример запроса:

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()

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

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()

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

import chdb.dbapi as dbapi

# In-memory 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()

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

Управление соединениями: Всегда закрывайте соединения и курсоры после завершения работы
Менеджеры контекста: Используйте операторы with для автоматической очистки ресурсов
Пакетная обработка: Используйте fetchmany() для больших наборов результатов
Обработка ошибок: Оборачивайте операции с базой данных в блоки try-except
Привязка параметров: По возможности используйте параметризованные запросы
Управление памятью: Избегайте использования fetchall() для очень больших наборов данных

Примечание

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

Предупреждение

Всегда закрывайте курсоры и соединения во избежание утечек ресурсов
Большие наборы результатов следует обрабатывать пакетами
Синтаксис привязки параметров соответствует стилю форматирования: %s

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

Модуль пользовательских функций для chDB.

Этот модуль предоставляет возможности для создания и управления пользовательскими функциями (UDF) в chDB. Он позволяет расширять функциональность chDB за счёт написания пользовательских функций на Python, которые можно вызывать из SQL-запросов.

`chdb.udf.chdb_udf`

Декоратор для пользовательских функций chDB на Python (UDF, User Defined Function).

Синтаксис

chdb.udf.chdb_udf(return_type='String')

Параметры

Параметр	Тип	Значение по умолчанию	Описание
`return_type`	str	`"String"`	Тип возвращаемого значения функции; должен быть одним из типов данных ClickHouse

Примечания

Функция должна быть stateless (без сохранения состояния). Поддерживаются только UDF, UDAF не поддерживаются.
Тип возвращаемого значения по умолчанию — String. Тип возвращаемого значения должен быть одним из типов данных ClickHouse.
Функция должна принимать аргументы типа String. Все аргументы — строки.
Функция будет вызываться для каждой строки входных данных.
Функция должна быть чистой функцией Python. Импортируйте все модули, используемые внутри функции.
Используется тот же интерпретатор Python, что и для запуска скрипта.

Пример

@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 и исполняемый скрипт.

Эта функция создаёт необходимые файлы для пользовательской функции (User Defined Function, UDF) в chDB:

Исполняемый Python-скрипт, который обрабатывает входные данные
XML-файл конфигурации, который регистрирует UDF в ClickHouse

Синтаксис

chdb.udf.generate_udf(func_name, args, return_type, udf_body)

Параметры

Parameter	Type	Description
`func_name`	str	Имя функции UDF
`args`	list	Список имён аргументов функции
`return_type`	str	Тип возвращаемого значения функции в ClickHouse
`udf_body`	str	Тело исходного кода функции UDF на Python

Примечание

Эта функция обычно вызывается декоратором @chdb_udf и не должна вызываться пользователями напрямую.

Вспомогательные утилиты

Вспомогательные функции и средства для chDB.

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

`chdb.utils.convert_to_columnar`

Преобразует список словарей в колоночный формат.

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

Синтаксис

chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]

Параметры

Параметр	Тип	Описание
`items`	`List[Dict[str, Any]]`	Список словарей для преобразования

Возвращает

Возвращаемый тип	Описание
`Dict[str, List[Any]]`	Словарь, в котором ключи — имена столбцов, а значения — списки значений этих столбцов

Пример

>>> 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-строки.

Синтаксис

chdb.utils.flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') → Dict[str, Any]

Параметры

Параметр	Тип	Значение по умолчанию	Описание
`d`	`Dict[str, Any]`	обязателен	Словарь, который нужно преобразовать в плоский вид
`parent_key`	str	`""`	Базовый ключ, добавляемый в начало каждого ключа
`sep`	str	`"_"`	Разделитель, используемый между объединёнными ключами

Возвращает

Тип возвращаемого значения	Описание
`Dict[str, Any]`	Плоский словарь

Пример

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

Синтаксис

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".

Примечание

Если все значения в списке равны None, функция возвращает "string".
Если хотя бы одно значение в списке является строкой, функция сразу возвращает "string".
Функция предполагает, что числовые значения могут быть представлены как целые числа, десятичные дроби или числа с плавающей запятой в зависимости от их диапазона и точности.

`chdb.utils.infer_data_types`

Определяет типы данных для каждого столбца в колоночной структуре данных.

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

Синтаксис

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

class chdb.rwabc.PyReader(data: Any)

abstractmethod `read`

Считывает указанное количество строк из заданных столбцов и возвращает список объектов, каждый из которых представляет собой последовательность значений для одного столбца.

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

Параметры

Параметр	Тип	Описание
`col_names`	`List[str]`	Список имён столбцов для чтения
`count`	int	Максимальное количество строк для чтения

Возвращает

Тип возврата	Описание
`List[Any]`	Список последовательностей, по одной для каждого столбца

класс `chdb.rwabc.PyWriter`

Базовый класс: ABC

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

abstractmethod finalize

Собрать и вернуть окончательные данные из блоков. Должен быть реализован в подклассах.

abstractmethod finalize() → bytes

Возвращает

Тип возвращаемого значения	Описание
`bytes`	Конечные сериализованные данные

abstractmethod `write`

Сохраняет столбцы данных в блоки. Должен быть реализован в подклассах.

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, включая синтаксические ошибки, несоответствия типов, отсутствующие таблицы/столбцы и другие проблемы выполнения запроса.

Переменные

Переменная	Тип	Описание
`args`	-	Кортеж, содержащий сообщение об ошибке и любые дополнительные аргументы

Примеры

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

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

Примечание

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

Информация о версии

`chdb.chdb_version = ('3', '6', '0')`

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

Если аргумент не указан, конструктор возвращает пустой кортеж. Если передан итерируемый объект iterable, кортеж инициализируется его элементами.

Если аргумент является кортежем, возвращается тот же самый объект.

`chdb.engine_version = '25.5.2.1'`

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'`

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

encoding по умолчанию — utf-8.
errors по умолчанию — strict.

Основные функции запросов​

chdb.query​

chdb.sql​

chdb.to_arrowTable​

chdb.to_df​

Управление подключениями и сессиями​

chdb.connect​

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

class chdb.ChdbError​

class chdb.session.Session​

cleanup​

close​

query​

send_query​

sql​

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

chdb.state.connect​

class chdb.state.sqlitelike.Connection​

close​

cursor​

query​

send_query​

class chdb.state.sqlitelike.StreamingResult​

fetch​

cancel​

close​

record_batch​

Протокол итератора​

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

class chdb.state.sqlitelike.Cursor​

close​

column_names​

column_types​

commit​

property description : list​

execute​

fetchall​

fetchmany​

fetchone​

chdb.state.sqlitelike​

chdb.state.sqlitelike.to_df​

Интеграция с DataFrame​

class chdb.dataframe.Table​

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

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

chdb.dbapi.connect​

chdb.dbapi.get_client_info()​

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

chdb.dbapi.Binary(x)​

Класс Connection​

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

close​

commit​

cursor​

escape​

escape_string​

property open​

query​

property resp​

rollback​

Класс Cursor​

class chdb.dbapi.cursors.Cursor​

callproc​

close​

execute​

executemany(query, args)​

fetchall()​

fetchmany​

fetchone​

max_stmt_length = 1024000​

mogrify​

nextset​

setinputsizes​

setoutputsizes​

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

исключение chdb.dbapi.err.DataError​

исключение chdb.dbapi.err.DatabaseError​

исключение chdb.dbapi.err.Error​

исключение chdb.dbapi.err.IntegrityError​

exception chdb.dbapi.err.InterfaceError​

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

`chdb.query`

`chdb.sql`

`chdb.to_arrowTable`

`chdb.to_df`

Управление подключениями и сессиями

`chdb.connect`

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

class `chdb.ChdbError`

class `chdb.session.Session`

`cleanup`

`close`

`query`

`send_query`

`sql`

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

`chdb.state.connect`

class `chdb.state.sqlitelike.Connection`

`close`

`cursor`

`query`

`send_query`

class `chdb.state.sqlitelike.StreamingResult`

`fetch`

`cancel`

`close`

`record_batch`

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

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

class `chdb.state.sqlitelike.Cursor`

`close`

`column_names`

`column_types`

`commit`

`property description : list`

`execute`

`fetchall`

`fetchmany`

`fetchone`

`chdb.state.sqlitelike`

`chdb.state.sqlitelike.to_df`

Интеграция с DataFrame

class `chdb.dataframe.Table`

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

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

`chdb.dbapi.connect`

`chdb.dbapi.get_client_info()`

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

`chdb.dbapi.Binary(x)`

Класс Connection

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

`close`

`commit`

`cursor`

`escape`

`escape_string`

`property open`

`query`

`property resp`

`rollback`

Класс Cursor

class `chdb.dbapi.cursors.Cursor`

`callproc`

`close`

`execute`

`executemany(query, args)`

`fetchall()`

`fetchmany`

`fetchone`

`max_stmt_length = 1024000`

`mogrify`

`nextset`

`setinputsizes`

`setoutputsizes`

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

исключение `chdb.dbapi.err.DataError`

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

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

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

exception `chdb.dbapi.err.InterfaceError`