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

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

​

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

​

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

Возвращает

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

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

Вызывает

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

Примеры

>>> # Базовый CSV-запрос
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Запрос с выводом в формате DataFrame
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Запрос с файловой базой данных
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

>>> # Запрос с 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='')

Параметры

Параметр	Тип	По умолчанию	Описание
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	""	Путь к каталогу пользовательских функций

Возвращает

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

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

Вызывает

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

Примеры

>>> # Базовый CSV-запрос
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Запрос с выводом в формате DataFrame
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Запрос с файловой базой данных
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

>>> # Запрос с UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")

---

​

chdb.to_arrowTable

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

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

Синтаксис

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

Синтаксис

chdb.to_df(r)

Параметры

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

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

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

Исключения

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

Вызывает

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

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

Примеры

>>> # База данных в памяти
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # База данных на основе файла
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # С параметрами
>>> conn = connect("data.db?mode=ro")  # Режим только для чтения
>>> conn = connect(":memory:?verbose&log-level=debug")  # Отладочное логирование
>>>
>>> # Использование менеджера контекста для автоматической очистки ресурсов
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Соединение закрывается автоматически

См. также

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

​

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

​

class chdb.ChdbError

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

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

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

---

​

class chdb.session.Session

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

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

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

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"	Абсолютный путь с параметрами запроса

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

Строки подключения, содержащие параметры запроса, например “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()  # Безопасная очистка независимо от ошибок

См. также

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

---

​

close

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

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

Синтаксис

close()

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

Важно

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

Примеры

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

---

​

query

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

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

Синтаксис

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, заданный при инициализации сеанса

Возвращает

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

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

Исключения

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

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

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

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

Примеры

>>> session = Session("test.db")
>>>
>>> # Базовый запрос с форматом CSV по умолчанию
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Запрос в формате JSON
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

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

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

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

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

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

Примеры

>>> 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")
...     # Обработка фрагмента без загрузки всего результирующего набора

>>> # 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='')

Параметры

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, заданный при инициализации сеанса

Возвращает

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

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

Вызывает:

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

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

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

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

Примеры

>>> session = Session("test.db")
>>>
>>> # Базовый запрос с форматом CSV по умолчанию
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Запрос в формате JSON
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

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

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

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

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

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

Примеры

>>> # База данных в памяти
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # База данных на основе файла
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # С параметрами
>>> conn = connect("data.db?mode=ro")  # Режим только для чтения
>>> conn = connect(":memory:?verbose&log-level=debug")  # Отладочное логирование
>>>
>>> # Использование контекстного менеджера для автоматической очистки ресурсов
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Соединение закрывается автоматически

См. также

• 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")
>>> # Использовать подключение для запросов
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Закрыть после завершения
>>> conn.close()

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

---

​

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	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	Если не установлены пакеты, необходимые для формата

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

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

Примеры

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

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

---

​

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)

Вызывает

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

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

Примеры

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

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

>>> # Формат 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() — для выполнения запросов без стриминга
• 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:  # Обрабатываем только первые 10 фрагментов
...         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)
>>> # Поток автоматически закрыт

---

​

класс 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()  # Освобождаем ресурсы курсора

---

​

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 операции обычно фиксируются автоматически, поэтому явная фиксация обычно не требуется. Этот метод предусмотрен для совместимости со стандартным сценарием работы DB-API 2.0.

Синтаксис

commit() → None

Примеры

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

Это соответствует спецификации 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-запрос и подготавливает результаты для дальнейшего получения с помощью методов fetch. Он обрабатывает разбор данных результата и автоматическое преобразование типов данных ClickHouse.

Синтаксис

execute(query: str) → None

Параметры:

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

Исключения

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

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

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

• Int/UInt types → int
• Float types → float
• String/FixedString → str
• DateTime → datetime.datetime
• Date → datetime.date
• Bool → bool

Примеры

>>> 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() — Получить одну строку
• 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	Tuple, содержащий до ‘size’ кортежей строк. Может содержать меньше строк, если результирующий набор исчерпан

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

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Обработка результатов батчами
>>> while True:
...     batch = cursor.fetchmany(100)  # Получить 100 строк за раз
...     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

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

При пустом результате возвращается пустая таблица 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

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

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

Синтаксис

chdb.state.sqlitelike.to_df(r)

Параметры:

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

Возвращает:

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

Вызывает

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

• Подключения: Управление подключениями к базе данных с помощью строк подключения
• Курсоры: Выполнение запросов и получение результатов
• Система типов: Константы типов и конвертеры, совместимые с DB-API 2.0
• Обработка ошибок: Стандартная иерархия исключений базы данных
• Потокобезопасность: Уровень потокобезопасности 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	Входные данные, преобразованные в байты

---

​

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

​

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

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

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

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

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

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

Параметры

Параметр	Тип	По умолчанию	Описание
path	str	None	Путь к файлу базы данных. Если указано None, используется база данных в памяти. Может быть путём к файлу, например ‘database.db’, или None для ‘:memory:’

Переменные

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

Примеры

>>> # База данных в памяти
>>> conn = Connection()
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchall()
>>> conn.close()

>>> # База данных на основе файла
>>> 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()

>>> # Использование в качестве менеджера контекста
>>> with Connection() as cur:
...     cur.execute("SELECT version()")
...     version = cur.fetchone()

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

---

​

close

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

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

Синтаксис

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

---

​

свойство open

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

Возвращает

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

---

​

query

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

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

Синтаксис

query(sql, fmt='CSV')

Параметры:

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

Возвращает

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

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

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

Пример

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

---

​

свойство resp

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

Возвращает

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

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

---

​

rollback

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

Синтаксис

rollback()

Для 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	-	ID последней вставленной строки (если применимо)
max_stmt_length	int	Максимальный размер оператора для 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()

См. объекты Cursor в DB-API 2.0 для получения подробной информации о спецификации.

---

​

callproc

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

Синтаксис

callproc(procname, args=())

Параметры

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

Возвращает

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

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

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

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

---

​

close

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

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

Синтаксис

close()

---

​

execute

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

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

Синтаксис

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" (устаревший)

Примеры

>>> # Параметры с вопросительными знаками
>>> 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	Если курсор закрыт или запрос составлен неверно
InterfaceError	Если во время выполнения возникает ошибка базы данных

---

​

executemany(query, args)

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

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

Синтаксис

executemany(query, args)

Параметры

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

Возвращает

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

Примеры

>>> # Пакетная вставка с параметрами-заполнителями ?
>>> 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
... )

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

---

​

fetchall()

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

Синтаксис

fetchall()

Возвращает

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

Вызывает

Exception	Условие
ProgrammingError	Если execute() не был вызван заранее

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

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

Пример

>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_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'

---

​

exception chdb.dbapi.err.DataError

Наследуется от: DatabaseError

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

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

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

Вызывает

Исключение	Условие
DataError	Когда проверка или обработка данных завершается ошибкой

Примеры

>>> # Деление на ноль в SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero

>>> # Неправильный формат даты
>>> 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	Когда нарушаются ограничения целостности базы данных

Примеры

>>> # Дубликат первичного ключа
>>> 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'

>>> # Нарушение внешнего ключа
>>> 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

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

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

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

Возникает

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

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

---

​

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

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

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

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

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

Вызывает

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

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

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

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

---

​

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

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

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

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

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

Вызывает

Exception	Condition
NotSupportedError	При обращении к неподдерживаемым возможностям базы данных

Примеры

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

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

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

---

​

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

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

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

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

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

Вызывает

Исключение	Условие
OperationalError	Когда операции с базой данных завершаются сбоем из-за проблем при выполнении

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

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

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

---

​

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

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

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

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

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

Вызывает

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

Примеры

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

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

>>> # Неверное число параметров
>>> 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 и служит корневым классом в иерархии исключений для операций с базой данных.

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

---

​

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

Базовый класс: 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, представляющим целочисленный литерал в заданной системе счисления. Литерал может предваряться символом ‘+’ или ‘-’ и содержать пробельные символы по краям. По умолчанию base равен 10. Допустимые значения base: 0 и 2–36. Base 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  # Возвращает 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 — это отдельное значение типа.

Примеры

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

Примеры

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

Примеры

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

Примеры

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

Примеры

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

Примеры

>>> 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. Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать с набором с помощью операторов равенства и неравенства.

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

Примеры

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

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

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

import chdb.dbapi as dbapi

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

# Создайте соединение и курсор
conn = dbapi.connect()
cur = conn.cursor()

# Выполните запрос
cur.execute('SELECT version()')
print("description:", cur.description)
print("data:", cur.fetchone())

# Освободите ресурсы
cur.close()
conn.close()

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

import chdb.dbapi as dbapi

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

# Создание таблицы
cur.execute("""
    CREATE TABLE employees (
        id UInt32,
        name String,
        department String,
        salary Decimal(10,2)
    ) ENGINE = Memory
""")

# Вставка данных
cur.execute("""
    INSERT INTO employees VALUES
    (1, 'Alice', 'Engineering', 75000.00),
    (2, 'Bob', 'Marketing', 65000.00),
    (3, 'Charlie', 'Engineering', 80000.00)
""")

# Запрос данных
cur.execute("SELECT * FROM employees WHERE department = 'Engineering'")

# Получение результатов
print("Column names:", [desc[0] for desc in cur.description])
for row in cur.fetchall():
    print(row)

conn.close()

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

import chdb.dbapi as dbapi

# База данных в памяти (по умолчанию)
conn1 = dbapi.connect()

# Файл базы данных на диске
conn2 = dbapi.connect("./my_database.chdb")

# Соединение с параметрами
conn3 = dbapi.connect("./my_database.chdb?log-level=debug&verbose")

# Соединение только для чтения
conn4 = dbapi.connect("./my_database.chdb?mode=ro")

# Автоматическое закрытие соединения
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() для очень больших наборов данных

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

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

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

​

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

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

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

​

chdb.udf.chdb_udf

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

Синтаксис

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, что и для запуска скрипта.

Пример

@chdb_udf()
def sum_udf(lhs, rhs):
    return int(lhs) + int(rhs)

@chdb_udf()
def func_use_json(arg):
    import json
    # ... использовать модуль json

---

​

chdb.udf.generate_udf

Генерирует файлы конфигурации UDF и исполняемого скрипта.

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

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

Синтаксис

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

Эта функция обычно вызывается декоратором @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]	required	Словарь, который нужно преобразовать в плоскую структуру
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]

Параметры

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

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

Return Type	Description
List[Any]	Список последовательностей, по одной для каждого столбца

​

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

Переменные

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

Примеры

>>> 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 или errors, объект должен предоставлять буфер данных, который будет декодирован с использованием указанной кодировки и обработчика ошибок. В противном случае возвращается результат object._str_() (если он определён) или repr(object).

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