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

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

`chdb.query`

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

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

Синтаксис

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

Параметры

Параметр	Тип	По умолчанию	Описание
`sql`	str	обязательный	Строка SQL-запроса для выполнения
`output_format`	str	`"CSV"`	Формат вывода для результатов. Поддерживаемые форматы: • `"CSV"` - Значения, разделенные запятыми • `"JSON"` - Формат JSON • `"Arrow"` - Формат Apache Arrow • `"Parquet"` - Формат Parquet • `"DataFrame"` - Pandas DataFrame • `"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

Примеры

>>> # 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)", path="mydb.chdb")

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

`chdb.sql`

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

Синтаксис

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

Параметры

Параметр	Тип	По умолчанию	Описание
`sql`	str	обязательный	Строка SQL-запроса для выполнения
`output_format`	str	`"CSV"`	Формат вывода для результатов. Поддерживаемые форматы: • `"CSV"` - Значения, разделенные запятыми • `"JSON"` - Формат JSON • `"Arrow"` - Формат Apache Arrow • `"Parquet"` - Формат Parquet • `"DataFrame"` - Pandas DataFrame • `"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

Примеры

>>> # 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)", path="mydb.chdb")

>>> # Query with 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`	pandas DataFrame, содержаший результаты запроса

Вызывает

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

Пример

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

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

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

`chdb.connect`

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

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

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

Параметры:

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

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

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

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

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

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

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

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

Для полного списка параметров см. clickhouse local --help --verbose

Возвращает

Тип возврата Описание

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

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

Вызывает

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

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

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

Примеры

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

Смотрите также

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

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

class `chdb.ChdbError`

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

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

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

class `chdb.session.Session`

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

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

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

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()  # Safe cleanup regardless of errors

Смотрите также

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

`close`

Закрыть сессию и очистить ресурсы.

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

Синтаксис

close()

примечание

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

Важно

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

Примеры

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

`query`

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

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

Синтаксис

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

Параметры

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

Возвращает

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

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

Вызывает

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

примечание

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

Внимание

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

Примеры

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

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

>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String)")
>>> 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	обязательный	Строка SQL-запроса для выполнения
`fmt`	str	`"CSV"`	Формат вывода для результатов. Доступные форматы: • `"CSV"` - Значения, разделенные запятыми • `"JSON"` - Формат JSON • `"TabSeparated"` - Значения, разделенные табуляцией • `"JSONCompact"` - Компактный формат JSON • `"Arrow"` - Формат Apache Arrow • `"Parquet"` - Формат Parquet

Возвращает

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

Вызывает

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

примечание

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

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

Примеры

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

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

Смотрите также

query() - Для выполнения запроса без потоковой передачи
chdb.state.sqlitelike.StreamingResult - Итератор потокового результата

`sql`

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

Синтаксис

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

Параметры

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

Возвращает

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

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

Вызывает:

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

примечание

Внимание

Примеры

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

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

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

Для полного списка параметров см. clickhouse local --help --verbose

Возвращает

Тип возврата Описание

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

Вызывает

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

Внимание

Примеры

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

Смотрите также

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

class `chdb.state.sqlitelike.Connection`

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

Синтаксис

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

`close`

Закрыть соединение и очистить ресурсы.

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

Синтаксис

close() → None

примечание

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

Внимание

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

Примеры

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

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

`cursor`

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

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

Синтаксис

cursor() → Cursor

Возвращает

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

примечание

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

Примеры

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

Смотрите также

Cursor - Реализация курсора базы данных

`query`

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

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

Синтаксис

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

Параметры:

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

Возвращает

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

Вызывает

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

Внимание

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

Примеры

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

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

Смотрите также

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

`send_query`

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

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

Синтаксис

send_query(query: str, format: str = 'CSV') → StreamingResult

Параметры

Параметр	Тип	По умолчанию	Описание
`query`	str	обязательный	Строка SQL-запроса для выполнения
`format`	str	`"CSV"`	Формат вывода для результатов. Поддерживаемые форматы: • `"CSV"` - Значения, разделенные запятыми • `"JSON"` - Формат JSON • `"Arrow"` - Формат Apache Arrow (включает метод record_batch()) • `"dataframe"` - Части DataFrame Pandas • `"arrowtable"` - Части таблицы PyArrow

Возвращает

Тип возвращаемого значения Описание

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

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

Вызывает

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

примечание

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

Примеры

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

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

>>> # Arrow format with RecordBatch streaming
>>> stream = conn.send_query("SELECT * FROM data", "Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Batch shape: {batch.num_rows} x {batch.num_columns}")

Смотрите также

query() - Для не потокового выполнения запросов
StreamingResult - Итератор потоковых результатов

class `chdb.state.sqlitelike.Cursor`

Основы: object

class chdb.state.sqlitelike.Cursor(connection)

`close`

Закройте курсор и очистите ресурсы.

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

Синтаксис

close() → None

примечание

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

Примеры

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

`column_names`

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

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

Синтаксис

column_names() → list

Возвращает

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

Примеры

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

Смотрите также

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

`column_types`

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

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

Синтаксис

column_types() → list

Возвращает

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

Примеры

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

Смотрите также

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

`commit`

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

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

примечание

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

Синтаксис

commit() → None

Примеры

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

`property description : list`

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

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

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

Возвращает

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

примечание

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

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users LIMIT 1")
>>> for desc in cursor.description:
...     print(f"Column: {desc[0]}, Type: {desc[1]}")
Column: id, Type: Int32
Column: name, Type: String

Смотрите также

column_names() - Получить только имена колонок
column_types() - Получить только типы колонок

`execute`

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

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

Синтаксис

execute(query: str) → None

Параметры:

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

Вызывает

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

примечание

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

примечание

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

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

Примеры

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

Смотрите также

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

`fetchall`

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

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

Синтаксис

fetchall() → tuple

Возвращает:

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

Внимание

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

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> all_users = cursor.fetchall()
>>> for user_id, user_name in all_users:
...     print(f"User {user_id}: {user_name}")

Смотрите также

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

`fetchmany`

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

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

Синтаксис

fetchmany(size: int = 1) → tuple

Параметры

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

Возвращает

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

примечание

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

Примеры

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

Смотрите также

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

`fetchone`

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

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

Синтаксис

fetchone() → tuple | None

Возвращает:

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

примечание

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

Примеры

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> row = cursor.fetchone()
>>> while row is not None:
...     user_id, user_name = row
...     print(f"User {user_id}: {user_name}")
...     row = cursor.fetchone()

Смотрите также

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

`chdb.state.sqlitelike`

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

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

Синтаксис

chdb.state.sqlitelike.to_arrowTable(res)

Параметры:

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

Возвращает

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

Вызывает

Исключение	Условие
`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`

Конвертировать результат запроса в Pandas DataFrame.

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

Синтаксис

chdb.state.sqlitelike.to_df(r)

Параметры:

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

Возвращает:

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

Вызывает

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

примечание

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

Смотрите также

to_arrowTable() - Для конвертации в формат таблицы PyArrow

Примеры

>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> df = to_df(result)
>>> print(df)
   num   text
0    1  hello
>>> print(df.dtypes)
num      int64
text    object
dtype: object

Интеграция DataFrame

class `chdb.dataframe.Table`

Основы:

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

Интерфейс API баз данных (DBAPI) 2.0

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

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

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

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

Интерфейс 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`	Входные данные, конвертированные в bytes

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

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

Основы: object

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

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

Соединение управляет движком chDB и предоставляет методы для выполнения запросов, управления транзакциями (нет операций для ClickHouse) и создания курсоров.

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

Параметры

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

Переменные

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

Примеры

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

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

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

примечание

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

`close`

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

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

Синтаксис

close()

Вызывает

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

`commit`

Зафиксировать текущую транзакцию.

Синтаксис

commit()

примечание

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

`cursor`

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

Синтаксис

cursor(cursor=None)

Параметры

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

Возвращает

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

Вызывает

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

Пример

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

`escape`

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

Синтаксис

escape(obj, mapping=None)

Параметры

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

Возвращает

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

Пример

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

`escape_string`

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

Синтаксис

escape_string(s)

Параметры

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

Возвращает

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

`property open`

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

Возвращает

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

`query`

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

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

Синтаксис

query(sql, fmt='CSV')

Параметры:

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

Возвращает

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

Вызывает

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

Пример

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

`property resp`

Получить последний ответ запроса.

Возвращает

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

примечание

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

`rollback`

Отменить текущую транзакцию.

Синтаксис

rollback()

примечание

Класс курсора

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

примечание

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

`callproc`

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

Синтаксис

callproc(procname, args=())

Параметры

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

Возвращает

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

примечание

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

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

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

`close`

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

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

Синтаксис

close()

`execute`

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

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

Синтаксис

execute(query, args=None)

Параметры

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

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

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

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

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

Примеры

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

Исключения

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

`executemany(query, args)`

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

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

Синтаксис

executemany(query, args)

Параметры

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

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

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

Примеры

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

примечание

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

`fetchall()`

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

Синтаксис

fetchall()

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

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

Исключения

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

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

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

Пример

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

`fetchmany`

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

Синтаксис

fetchmany(size=1)

Параметры

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

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

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

Исключения

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

Пример

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

`fetchone`

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

Синтаксис

fetchone()

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

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

Исключения

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

Пример

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

`max_stmt_length = 1024000`

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

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

`mogrify`

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

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

Синтаксис

mogrify(query, args=None)

Параметры

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

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

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

Пример

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

примечание

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

`nextset`

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

Синтаксис

nextset()

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

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

примечание

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

`setinputsizes`

Установить размеры входных параметров (реализация без действия).

Синтаксис

setinputsizes(*args)

Параметры

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

примечание

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

`setoutputsizes`

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

Синтаксис

setoutputsizes(*args)

Параметры

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

примечание

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

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

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

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

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

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

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

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

примечание

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

Смотрите также

Спецификация API базы данных Python версии 2.0
chdb.dbapi.connections - Управление соединениями с базой данных
chdb.dbapi.cursors - Операции с курсорами базы данных

Примеры

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

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

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

Базируется на: DatabaseError

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

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

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

Вызывает

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

Примеры

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

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

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

Базируется на: Error

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

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

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

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

примечание

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

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

Базируется на: StandardError

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

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

примечание

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

Смотрите также

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

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

Базируется на: DatabaseError

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

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

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

Вызывает

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

Примеры

>>> # Duplicate primary key
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
IntegrityError: Duplicate entry '1' for key 'PRIMARY'

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

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

Базируется на: Error

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

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

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

Вызывает

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

примечание

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

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

Базируется на: DatabaseError

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

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

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

Вызывает

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

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

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

примечание

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

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

Базируется на: DatabaseError

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

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

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

Вызывает

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

Примеры

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

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

примечание

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

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

Базируется на: DatabaseError

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

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

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

Вызывает

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

примечание

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

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

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

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

Базируется на: DatabaseError

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

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

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

Вызывает

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

Примеры

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

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

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

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

Базируется на: Exception

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

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

примечание

Этот класс исключений соответствует спецификации 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

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

кодировка по умолчанию 'utf-8'.
ошибки по умолчанию 'строгие'.

`chdb.dbapi.threadsafety = 1`

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

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

Если x не является числом или если указана основа, то x должен быть строкой, байтами или экземпляром bytearray, представляющим целочисленный литерал в заданной основе. Литерал может быть предшествован символами '+' или '-' и окружен пробелами. Основание по умолчанию — 10. Допустимые основания: 0 и 2-36. Основание 0 означает интерпретацию базы из строки как целочисленного литерала.

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

`chdb.dbapi.paramstyle = 'format'`

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

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