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

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

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

Синтаксис

chdb.query(sql, output_format='CSV', path='', udf_path='')

Параметры

Возвращает

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

Вызывает

Примеры

>>> # 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")

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

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

Синтаксис

chdb.sql(sql, output_format='CSV', path='', udf_path='')

Параметры

Возвращает

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

Вызывает

Примеры

>>> # 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")

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

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

Синтаксис

chdb.to_arrowTable(res)

Параметры

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

Исключения

Пример

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

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

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

Синтаксис

chdb.to_df(r)

Параметры

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

Исключения

Пример

>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> df = chdb.to_df(result)
>>> print(df)
   id    msg
0   1  hello

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

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

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

chdb.connect(connection_string: str = ':memory:') → Connection

Параметры:

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

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

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

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

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

Возвращает

Вызывает

Примеры

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

См. также

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

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

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

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

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

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

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

class chdb.session.Session(path=None)

Примеры

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

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

Синтаксис

cleanup()

Примеры

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

См. также

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

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

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

Синтаксис

close()

Примеры

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

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

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

Синтаксис

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

Параметры

Возвращает

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

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

Исключения

Примеры

>>> 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 — Псевдоним этого метода

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

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

Синтаксис

send_query(sql, fmt='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, fmt='CSV', udf_path='')

Параметры

Возвращает

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

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

Вызывает:

Примеры

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

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

Синтаксис

chdb.state.connect(connection_string: str = ':memory:') → Connection

Параметры

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

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

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

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

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

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

Возвращает

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

Примеры

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

См. также

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

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

Синтаксис

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

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

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

Синтаксис

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 для выполнения запросов.

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

Синтаксис

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

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

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

Синтаксис

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

Параметры:

Возвращает

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

Примеры

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

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

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

Синтаксис

send_query(query: str, format: str = 'CSV') → 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 — итератор для потоковых результатов

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

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

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

class chdb.state.sqlitelike.StreamingResult

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

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

Синтаксис

fetch() → Any

Возвращает

Примеры

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

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

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

Синтаксис

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)

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

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

Синтаксис

close() → None

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

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

Синтаксис

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

Параметры

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

Примеры

>>> 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)
>>> # Поток автоматически закрыт

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

class chdb.state.sqlitelike.Cursor(connection)

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

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

Синтаксис

close() → None

Примеры

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

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

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

Синтаксис

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

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

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

Синтаксис

column_types() → list

Возвращает

Примеры

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

См. также

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

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

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

Синтаксис

commit() → None

Примеры

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

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

Это свойство возвращает список 7-элементных кортежей, описывающих каждый столбец в результирующем наборе последнего выполненного запроса SELECT. Каждый кортеж содержит: (name, type_code, display_size, internal_size, precision, scale, null_ok)

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

Возвращает

Примеры

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

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

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

Синтаксис

execute(query: str) → None

Параметры:

Исключения

Примеры

>>> 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() — Получить все оставшиеся строки

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

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

Синтаксис

fetchall() → tuple

Возвращает:

Примеры

>>> 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() - Выборка нескольких строк батчами

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

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

Синтаксис

fetchmany(size: int = 1) → tuple

Параметры

Возвращает

Примеры

>>> 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() — Получить все оставшиеся строки

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

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

Синтаксис

fetchone() → tuple | None

Возвращает:

Примеры

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

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

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

Синтаксис

chdb.state.sqlitelike.to_arrowTable(res)

Параметры:

Возвращает

Вызывает

Примеры

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

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

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

Синтаксис

chdb.state.sqlitelike.to_df(r)

Параметры:

Возвращает:

Вызывает

См. также

• 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

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

class chdb.dataframe.Table(*args: Any, **kwargs: Any)

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(*args, **kwargs)

Параметры

Вызывает

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

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

Синтаксис

chdb.dbapi.get_client_info()

Возвращает

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

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

Синтаксис

chdb.dbapi.Binary(x)

Параметры

Возвращает

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

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

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

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

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

Параметры

Переменные

Примеры

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

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

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

Синтаксис

close()

Исключения

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

Синтаксис

commit()

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

Синтаксис

cursor(cursor=None)

Параметры

Возвращает

Вызывает

Пример

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

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

Синтаксис

escape(obj, mapping=None)

Параметры

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

Пример

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

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

Синтаксис

escape_string(s)

Параметры

Возвращает

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

Возвращает

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

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

Синтаксис

query(sql, fmt='CSV')

Параметры:

Возвращает

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

Пример

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

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

Возвращает

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

Синтаксис

rollback()

Наследует: object

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

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

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

class chdb.dbapi.cursors.Cursor(connection)

Примеры

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

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

Синтаксис

callproc(procname, args=())

Параметры

Возвращает

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

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

Синтаксис

close()

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

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

Синтаксис

execute(query, args=None)

Параметры

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

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

Примеры

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

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

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

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

Синтаксис

executemany(query, args)

Параметры

Возвращает

Примеры

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

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

Синтаксис

fetchall()

Возвращает

Вызывает

Пример

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

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

Синтаксис

fetchmany(size=1)

Параметры

Возвращает

Вызывает

Пример

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

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

Синтаксис

fetchone()

Возвращает

Исключения

Пример

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

Максимальный размер оператора, создаваемого executemany().

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

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

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

Синтаксис

mogrify(query, args=None)

Параметры

Возвращает

Пример

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

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

Синтаксис

nextset()

Возвращает

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

Синтаксис

setinputsizes(*args)

Параметры

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

Синтаксис

setoutputsizes(*args)

Параметры

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

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

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

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

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

См. также

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

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

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

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

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

Вызывает

Примеры

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

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

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

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

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

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

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

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

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

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

См. также

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

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

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

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

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

Вызывает

Примеры

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

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

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

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

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

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

Возникает

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

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

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

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

Вызывает

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

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

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

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

Вызывает

Примеры

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

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

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

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

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

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

Вызывает

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Расширенный 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

Расширенный 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

Расширенный 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

Расширенный 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

Расширенный 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

Расширенный 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

Расширенный 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

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

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

Используется для констант типов, таких как 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

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

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

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

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

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

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

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

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

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

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

Синтаксис

chdb.create_function(name, func, arg_types=None, return_type=None, *, on_null=None, on_error=None)

Параметры

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

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

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

Пример

from chdb import create_function, drop_function, query
from chdb.sqltypes import INT64, STRING

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

drop_function("strlen")

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

Синтаксис

chdb.drop_function(name)

Параметры

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

Синтаксис

from chdb import func

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

Параметры

Такие же, как у create_function, за исключением name и func, которые определяются декорированной функцией.

Примеры

from chdb import func, query
from chdb.sqltypes import INT64, STRING

# Explicit types
@func([INT64, INT64], INT64)
def add(a, b):
    return a + b

# Types inferred from annotations
@func()
def multiply(a: int, b: int) -> int:
    return a * b

# Explicit return_type, arg_types inferred from annotations
@func(return_type=STRING)
def greet(name: str):
    return f"Hello, {name}!"

print(query("SELECT add(12, 22)"))       # 34
print(query("SELECT multiply(3, 7)"))    # 21
print(query("SELECT greet('world')"))    # Hello, world!

Импортируйте типы из chdb.sqltypes:

from chdb.sqltypes import (
    BOOL,
    INT8, INT16, INT32, INT64, INT128, INT256,
    UINT8, UINT16, UINT32, UINT64, UINT128, UINT256,
    FLOAT32, FLOAT64,
    STRING,
    DATE, DATE32, DATETIME, DATETIME64,
)

Если типы определяются на основе аннотаций Python, используется следующее сопоставление:

Типы можно задавать несколькими способами:

from chdb import create_function, func
from chdb.sqltypes import INT64

# 1. ChdbType constants
create_function("f1", lambda x: x, arg_types=[INT64], return_type=INT64)

# 2. ClickHouse type strings
create_function("f2", lambda x: x, arg_types=["Int64"], return_type="Int64")

# 3. Parameterized type strings
create_function("f3", lambda x: x, arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")

# 4. Python types — passed directly or used as annotations
create_function("f4", lambda x: x, arg_types=[int], return_type=int)

@func()
def f5(x: int) -> int:
    return x

Настройте обработку значений NULL с помощью параметра on_null.

from chdb import func, query, NullHandling

# Default: NULL in → NULL out, function not called
@func(return_type="Int64")
def add_one(x: int) -> int:
    return x + 1

print(query("SELECT add_one(NULL)"))  # NULL

# Pass NULL as None
@func(return_type="Int64", on_null="pass")
def null_safe(x):
    return 0 if x is None else x + 1

print(query("SELECT null_safe(NULL)"))  # 0

Управляйте обработкой исключений с помощью параметра on_error.

from chdb import func, query

# Default: exception propagates
@func(arg_types=["Int64", "Int64"], return_type="Int64")
def divide(a, b):
    return a // b

# print(query("SELECT divide(1, 0)"))  # Error: division by zero

# Ignore: exception → NULL
@func(arg_types=["Int64", "Int64"], return_type="Int64", on_error="ignore")
def safe_divide(a, b):
    return a // b

print(query("SELECT safe_divide(1, 0)"))   # NULL
print(query("SELECT safe_divide(10, 2)"))  # 5

Пользовательские функции (UDF) полностью поддерживают типы Date, Date32, DateTime и DateTime64 с поддержкой часовых поясов.

from chdb import func, query
from datetime import datetime, timedelta, date

@func(arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")
def add_one_hour(dt):
    return dt + timedelta(hours=1)

@func()
def get_year(d: date) -> int:
    return d.year

print(query("SELECT add_one_hour(toDateTime('2024-01-01 12:00:00', 'UTC'))"))  # 2024-01-01 13:00:00
print(query("SELECT get_year(toDate('2024-06-15'))"))  # 2024

• Входные значения ClickHouse DateTime/DateTime64 преобразуются в объекты Python datetime с информацией о часовом поясе
• При возврате в ClickHouse выходные объекты Python datetime сохраняют информацию о часовом поясе
• Тип DATETIME64 из chdb.sqltypes по умолчанию имеет scale 6 (микросекунды), что эквивалентно DateTime64(6)

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

Синтаксис

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

Параметры

Примечания

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
    # ... use json module

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

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

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

Синтаксис

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

Параметры

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

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

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

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

Синтаксис

chdb.utils.convert_to_columnar(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']
}

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

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

Синтаксис

chdb.utils.flatten_dict(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}]'
}

Определяет наиболее подходящий тип данных для списка значений.

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

Синтаксис

chdb.utils.infer_data_type(values: List[Any]) → str

Параметры

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

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

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

Синтаксис

chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple]

Параметры

Возвращает

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

class chdb.rwabc.PyReader(data: Any)

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

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

Параметры

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

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

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

Формирует и возвращает итоговые данные из блоков. Метод должен быть реализован в подклассах.

abstractmethod finalize() → bytes

Возвращает

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

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

Параметры

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

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

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

Сообщение исключения обычно содержит подробную информацию об ошибке из ClickHouse, включая синтаксические ошибки, несоответствия типов, отсутствие таблиц/столбцов и другие проблемы при выполнении запроса.

Переменные

Примеры

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

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

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

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

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

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

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

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