Возвращает
Возвращает результат запроса в указанном формате:
Вызывает
Примеры
Выполняет SQL-запрос с помощью движка chDB. Это основная функция для выполнения SQL-команд с помощью встроенного движка ClickHouse. Поддерживает различные форматы вывода и может работать с временными или файловыми базами данных. Синтаксис
Возвращает
Возвращает результат запроса в указанном формате:
Вызывает
Примеры
Преобразует результат запроса в таблицу PyArrow. Преобразует результат запроса chDB в таблицу PyArrow для эффективной обработки данных в столбцовом формате. Возвращает пустую таблицу, если результат отсутствует. Синтаксис
Возвращаемое значение
Исключения
Пример
Преобразует результат запроса в pandas DataFrame. Преобразует результат запроса chDB в pandas DataFrame: сначала в таблицу PyArrow, а затем в pandas с использованием многопоточности для повышения производительности. Синтаксис
Возвращаемое значение
Исключения
Пример
Базовые форматы
С параметрами запроса
Обработка параметров запроса
Параметры запроса передаются в движок ClickHouse как аргументы запуска.
Специальная обработка параметров:
Полный список параметров см. в
clickhouse local --help --verbose
Возвращает
Вызывает
В одном процессе может работать один встроенный движок, привязанный к одному пути базы данных. Несколько подключений к одному и тому же пути могут сосуществовать и выполнять запросы одновременно. Если при наличии открытого подключения открыть другой путь, возникнет
RuntimeError; сначала закройте открытые подключения.Connection— класс подключения к базе данныхCursor— курсор базы данных для операций DB-API 2.0
Exception
Базовый класс исключений для ошибок, связанных с chDB.
Это исключение возникает, когда выполнение запроса chDB завершается с ошибкой
или в процессе возникает ошибка. Оно наследуется от стандартного класса Python Exception и
предоставляет информацию об ошибке от базового движка ClickHouse.
Базовый класс:
object
Сеанс сохраняет состояние запроса.
Если path имеет значение None, сеанс использует общую для всего процесса временную базу данных (:memory:), поэтому все сеансы без path видят таблицы друг друга; её временный каталог удаляется только при закрытии последнего такого сеанса или подключения.
Вы также можете передать path, чтобы создать базу данных по этому пути, где будут храниться ваши данные.
Вы также можете использовать строку подключения, чтобы передать path и другие параметры.
Обработка аргументов строки подключенияСтроки подключения, содержащие параметры запроса, например “file:test.db?param1=value1¶m2=value2”, передают
“param1=value1” движку ClickHouse в качестве аргументов запуска.Подробнее см.
clickhouse local –help –verboseОбработка некоторых специальных аргументов:- “mode=ro” будет преобразован в “–readonly=1” для ClickHouse (режим только для чтения)
Важно
- Несколько сеансов могут сосуществовать, если используют один и тот же путь к базе данных.
- Чтобы использовать другой путь к базе данных, сначала закройте открытые сеансы.
Очистка ресурсов сеанса с обработкой исключений. Этот метод пытается закрыть сеанс, подавляя все исключения, которые могут возникнуть в процессе очистки. Он особенно полезен в сценариях обработки ошибок или когда нужно гарантировать выполнение очистки независимо от состояния сеанса. Синтаксис
Этот метод никогда не сгенерирует исключение, поэтому его можно безопасно вызывать в
блоках finally или в деструкторах.
close()- Для явного закрытия сеанса с пробросом ошибок
Закрывает сеанс и освобождает ресурсы. Этот метод закрывает базовое соединение и сбрасывает глобальное состояние сеанса. После вызова этого метода сеанс становится недействительным, и его нельзя использовать для дальнейших запросов. Синтаксис
Этот метод автоматически вызывается, когда сеанс используется в качестве менеджера контекста
или когда объект сеанса уничтожается.
Выполняет SQL-запрос и возвращает результаты. Этот метод выполняет SQL-запрос к базе данных текущего сеанса и возвращает результаты в указанном формате. Метод поддерживает различные форматы вывода и сохраняет состояние сеанса между запросами. Синтаксис
Возвращает
Возвращает результаты запроса в указанном формате.
Точный возвращаемый тип зависит от параметра
fmt:
- Строковые форматы (CSV, JSON и т. д.) возвращают str
- Двоичный формат (Arrow, Parquet) возвращает bytes
Формат «Debug» не поддерживается и будет автоматически преобразован
в «CSV» с предупреждением.
Для отладки используйте параметры строки подключения.
send_query()— Для потокового выполнения запросовsql— Псевдоним этого метода
Выполняет SQL-запрос и возвращает итератор для потокового получения результатов. Этот метод выполняет SQL-запрос к базе данных сеанса и возвращает объект потокового результата, который позволяет перебирать результаты, не загружая всё в память сразу. Это особенно полезно для больших результирующих наборов. Синтаксис
Возвращает
Вызывает исключения
Формат «Debug» не поддерживается и будет автоматически преобразован
в «CSV» с предупреждением. Для отладки используйте параметры строки подключения.
query()— для выполнения запросов без использования стримингаchdb.state.sqlitelike.StreamingResult— итератор результатов стриминга
Выполняет SQL-запрос и возвращает результаты. Этот метод выполняет SQL-запрос к базе данных текущего сеанса и возвращает результаты в указанном формате. Метод поддерживает различные выходные форматы и сохраняет состояние сеанса между запросами. Синтаксис
Возвращает
Возвращает результаты запроса в указанном формате.
Точный тип возвращаемого значения зависит от параметра формата:
- Строковые форматы (CSV, JSON и т. д.) возвращают str
- Двоичные форматы (Arrow, Parquet) возвращают bytes
Формат “Debug” не поддерживается и будет автоматически преобразован
в “CSV” с предупреждением. Для отладки используйте параметры строки подключения
вместо него.
send_query()— Для потокового выполнения запросовsql— Псевдоним этого метода
Базовые форматы
Поддерживаемые форматы строки подключения:
С параметрами запроса
Обработка параметров запроса
Параметры запроса передаются движку ClickHouse как аргументы запуска.
Специальная обработка параметров:
Полный список параметров см. в
clickhouse local --help --verbose
Возвращает
Выбрасывает исключения
В рамках одного процесса запускается один встроенный движок, привязанный к одному пути к базе данных. Несколько подключений к одному пути могут существовать одновременно и выполнять запросы параллельно. Открытие другого пути, пока открыто хотя бы одно подключение, вызывает
RuntimeError; сначала закройте открытые подключения.Connection— класс подключения к базе данныхCursor— курсор базы данных для операций DB-API 2.0
object
Синтаксис
Закрывает подключение и освобождает ресурсы. Этот метод закрывает подключение к базе данных и освобождает все связанные с ним ресурсы, включая активные курсоры. После вызова этого метода подключение становится недействительным и не может использоваться для дальнейших операций. Синтаксис
Этот метод идемпотентен — его можно безопасно вызывать несколько раз.
Создаёт объект Cursor для выполнения запросов. Этот метод создаёт курсор базы данных, предоставляющий стандартный интерфейс DB-API 2.0 для выполнения запросов и получения результатов. Курсор позволяет более гибко управлять выполнением запросов и извлечением результатов. Синтаксис
При создании нового курсора любой существующий курсор,
связанный с этим подключением, будет заменён. Для одного подключения поддерживается только один курсор.
Cursor— Реализация курсора для работы с базой данных
Выполняет SQL-запрос и возвращает результат целиком. Этот метод синхронно выполняет SQL-запрос и возвращает полный результирующий набор. Он поддерживает различные форматы вывода и автоматически выполняет постобработку в зависимости от формата. Синтаксис
Возвращает
Вызывает исключения
Примеры
send_query()— Для выполнения запросов в потоковом режиме
Выполняет SQL-запрос и возвращает итератор потокового результата. Этот метод выполняет SQL-запрос и возвращает объект StreamingResult, который позволяет перебирать результаты, не загружая всё сразу в память. Это идеально подходит для обработки больших результирующих наборов. Синтаксис
Возвращает
Вызывает
Только формат «Arrow» поддерживает метод
record_batch() у возвращаемого StreamingResult.query()— для выполнения запросов без стримингаStreamingResult— итератор для потоковых результатов
Базовый класс:
object
Итератор потоковых результатов для обработки больших результатов запросов.
Этот класс предоставляет интерфейс итератора для потоковой обработки результатов запросов без
загрузки всего результирующего набора в память. Он поддерживает различные выходные форматы
и предоставляет методы для ручного получения результатов и потоковой передачи батчей PyArrow RecordBatch.
Возвращает следующий фрагмент результатов стриминга. Этот метод возвращает следующий доступный фрагмент данных из результата потокового запроса. Формат возвращаемых данных зависит от формата, указанного при запуске потокового запроса. Синтаксис
Примеры
Отменяет потоковый запрос и освобождает ресурсы. Этот метод отменяет любой выполняемый потоковый запрос и освобождает связанные с ним ресурсы. Его следует вызывать, если вы хотите прекратить обработку результатов до завершения потока. Синтаксис
Закрывает потоковый результат и освобождает ресурсы. Псевдоним для
cancel(). Закрывает итератор потокового результата
и освобождает все связанные с ним ресурсы.
Синтаксис
Создает PyArrow RecordBatchReader для эффективной пакетной обработки. Этот метод создает PyArrow RecordBatchReader, который позволяет эффективно перебирать результаты запроса в формате Arrow. Это наиболее эффективный способ обрабатывать большие результирующие наборы при использовании PyArrow. Синтаксис
Возвращаемое значение
Этот метод доступен только в том случае, если потоковый запрос был
инициирован с
format="Arrow". При использовании с другими форматами будет вызвана ошибка.StreamingResult поддерживает протокол итерации Python, поэтому его можно использовать напрямую в циклах for:
StreamingResult поддерживает протокол контекстного менеджера для автоматического освобождения ресурсов:
Базовый класс:
object
Закрывает курсор и освобождает ресурсы. Этот метод закрывает курсор и освобождает все связанные с ним ресурсы. После вызова этого метода курсор становится недействительным и не может использоваться для выполнения дальнейших операций. Синтаксис
Этот метод идемпотентен — его можно безопасно вызывать несколько раз.
При закрытии соединения курсор также закрывается автоматически.
Возвращает список имён столбцов из последнего выполненного запроса. Этот метод возвращает имена столбцов из последнего выполненного запроса SELECT. Имена возвращаются в том же порядке, в котором они указаны в результирующем наборе. Синтаксис
Примеры
column_types()— Получить информацию о типах столбцовdescription— описание столбца в DB-API 2.0
Возвращает список типов столбцов из последнего выполненного запроса. Этот метод возвращает имена типов столбцов ClickHouse из самого недавно выполненного SELECT-запроса. Типы возвращаются в том же порядке, в котором они представлены в результирующем наборе. Синтаксис
Примеры
column_names()— получить информацию об именах столбцовdescription— описание столбцов в DB-API 2.0
Зафиксировать любую незавершённую транзакцию. Этот метод фиксирует любую незавершённую транзакцию базы данных. В ClickHouse большинство операций фиксируются автоматически, но этот метод предусмотрен для совместимости с DB-API 2.0.
В ClickHouse операции обычно фиксируются автоматически, поэтому явная фиксация
обычно не требуется. Этот метод предусмотрен для совместимости
со стандартным сценарием работы DB-API 2.0.
Возвращает описание столбцов в соответствии со спецификацией DB-API 2.0. Это свойство возвращает список 7-элементных кортежей, описывающих каждый столбец в результирующем наборе последнего выполненного запроса SELECT. Каждый кортеж содержит: (name, type_code, display_size, internal_size, precision, scale, null_ok) В настоящее время заполняются только поля name и type_code, а для остальных установлено значение None. Возвращает
Это соответствует спецификации DB-API 2.0 для cursor.description.
Только первые два элемента (name и type_code) содержат значимые
данные в данной реализации.
column_names()— Получить только имена столбцовcolumn_types()— Получить только типы столбцов
Выполняет SQL-запрос и подготавливает результаты для получения. Этот метод выполняет SQL-запрос и подготавливает результаты для дальнейшего получения с помощью методов fetch. Он обрабатывает разбор данных результата и автоматическое преобразование типов данных ClickHouse. Синтаксис
Исключения
Этот метод соответствует спецификации DB-API 2.0 для
cursor.execute().
После выполнения используйте fetchone(), fetchmany() или fetchall(),
чтобы получить результаты.Метод автоматически преобразует типы данных ClickHouse в соответствующие
типы Python:
- Int/UInt types → int
- Float types → float
- String/FixedString → str
- DateTime → datetime.datetime
- Date → datetime.date
- Bool → bool
fetchone()— Получить одну строкуfetchmany()— Получить несколько строкfetchall()— Получить все оставшиеся строки
Получает все оставшиеся строки из результата запроса. Этот метод возвращает все оставшиеся строки из текущего набора результатов запроса, начиная с текущей позиции курсора. Он возвращает кортеж кортежей строк с соответствующим преобразованием в типы Python. Синтаксис
Примеры
fetchone()- Выборка одной строкиfetchmany()- Выборка нескольких строк батчами
Извлекает несколько строк из результата запроса. Этот метод извлекает до ‘size’ строк из текущего набора результатов запроса. Он возвращает кортеж кортежей строк, где каждая строка содержит значения столбцов с соответствующим преобразованием в типы Python. Синтаксис
Возвращает
Этот метод соответствует спецификации DB-API 2.0. Он вернет меньше
чем ‘size’ строк, если результирующий набор исчерпан.
fetchone()— Получить одну строкуfetchall()— Получить все оставшиеся строки
Извлекает следующую строку из результата запроса. Этот метод извлекает следующую доступную строку из текущего результирующего набора запроса. Он возвращает кортеж со значениями столбцов с соответствующим преобразованием к типам Python. Синтаксис
Этот метод соответствует спецификации DB-API 2.0. Значения столбцов
автоматически преобразуются в соответствующие типы Python в зависимости от
типов столбцов ClickHouse.
fetchmany()- Получить несколько строкfetchall()- Получить все оставшиеся строки
Преобразует результат запроса в таблицу PyArrow. Эта функция преобразует результаты запроса chdb в таблицу PyArrow, что обеспечивает эффективный доступ к столбцовым данным и совместимость с другими библиотеками для обработки данных. Синтаксис
Возвращает
Вызывает
Для работы этой функции должны быть установлены и pyarrow, и pandas.
Установите их командой:
pip install pyarrow pandasПреобразует результат запроса в DataFrame Pandas. Эта функция преобразует результаты запросов chdb в DataFrame Pandas: сначала в таблицу PyArrow, а затем в DataFrame. Это обеспечивает удобные возможности для анализа данных через API Pandas. Синтаксис
Возвращает:
Вызывает
Эта функция использует многопоточность при преобразовании из Arrow в Pandas,
чтобы повысить производительность на больших объёмах данных.
to_arrowTable()- Для преобразования в формат таблицы PyArrow
- Подключения: Управление подключениями к базе данных с помощью строк подключения
- Курсоры: Выполнение запросов и получение результатов
- Система типов: Константы типов и конвертеры, совместимые с DB-API 2.0
- Обработка ошибок: Стандартная иерархия исключений базы данных
- Потокобезопасность: Уровень потокобезопасности 1 (потоки могут совместно использовать модули, но не подключения)
Интерфейс Database API (DBAPI) 2.0 включает следующие основные функции: Инициализирует новое соединение с базой данных. Синтаксис
Вызывает
Возвращает сведения о версии клиента. Возвращает версию клиента chDB в виде строки для совместимости с MySQLdb. Синтаксис
Возвращает x в виде двоичного типа. Эта функция преобразует входное значение в тип bytes для использования в двоичных полях базы данных в соответствии со спецификацией DB-API 2.0. Синтаксис
Возвращает
Базовый класс:
object
Подключение к базе данных chDB, совместимое с DB-API 2.0.
Этот класс предоставляет стандартный интерфейс DB-API для подключения к базам данных chDB и работы с ними. Поддерживаются как временные, так и файловые базы данных.
Подключение управляет базовым движком chDB и предоставляет методы для
выполнения запросов, управления транзакциями (для ClickHouse это операция-заглушка) и создания курсоров.
Переменные
Примеры
ClickHouse не поддерживает традиционные транзакции, поэтому операции commit() и rollback()
ничего не делают, но предусмотрены для соответствия DB-API.
Закрывает соединение с базой данных. Закрывает базовое соединение chDB и помечает его как закрытое. Последующие операции с этим соединением будут вызывать ошибку. Синтаксис
Фиксирует текущую транзакцию. Синтаксис
Для chDB/ClickHouse это операция-заглушка, так как они не поддерживают
традиционные транзакции. Предусмотрено для соблюдения требований DB-API 2.0.
Создает новый курсор для выполнения запросов. Синтаксис
Возвращает
Вызывает
Пример
Экранирование значения для безопасного включения в SQL-запросы. Синтаксис
Возвращаемое значение
Пример
Экранирует строковое значение для SQL-запросов. Синтаксис
Возвращает
Проверяет, открыто ли соединение. Возвращает
Выполняет SQL-запрос напрямую и возвращает необработанные результаты. Этот метод обходит интерфейс курсора и выполняет запросы напрямую. Для стандартного использования DB-API рекомендуется использовать метод
cursor().
Синтаксис
Возвращает
Вызывает исключения
Пример
Возвращает ответ на последний запрос. Возвращает
Это свойство обновляется при каждом прямом вызове query().
Оно не отражает запросы, выполненные через курсоры.
Откатывает текущую транзакцию. Синтаксис
Для chDB/ClickHouse это не имеет эффекта, так как они не поддерживают традиционные
транзакции. Предусмотрено для соответствия DB-API 2.0.
Наследует:
object
Курсор DB-API 2.0 для выполнения запросов и получения результатов.
Курсор предоставляет методы для выполнения SQL-команд, управления результатами запросов
и навигации по результирующим наборам. Он поддерживает привязку параметров, пакетные операции
и соответствует спецификации DB-API 2.0.
Не создавайте экземпляры Cursor напрямую. Вместо этого используйте Connection.cursor().
Примеры
См. объекты Cursor в DB-API 2.0
для получения подробной информации о спецификации.
Выполняет хранимую процедуру (временная реализация-заглушка). Синтаксис
Возвращает
chDB/ClickHouse не поддерживает хранимые процедуры в традиционном понимании.
Этот метод предоставлен для соответствия DB-API 2.0, но фактически
не выполняет никаких действий. Для всех SQL-операций используйте execute().
Закрывает курсор и освобождает связанные с ним ресурсы. После закрытия курсор становится непригодным для дальнейшего использования, и любая операция с ним сгенерирует исключение. При закрытии курсора считываются все оставшиеся данные и освобождается базовый курсор. Синтаксис
Выполняет SQL-запрос с необязательной привязкой параметров. Этот метод выполняет один SQL-оператор с необязательной подстановкой параметров. Поддерживает несколько стилей плейсхолдеров параметров для большей гибкости. Синтаксис
Возвращаемое значение
Стили параметров
Примеры
Выполняет запрос несколько раз с разными наборами параметров. Этот метод позволяет эффективно выполнять один и тот же SQL-запрос несколько раз с разными значениями параметров. Он особенно полезен при массовой вставке данных. Синтаксис
Возвращает
Примеры
Этот метод повышает производительность операций INSERT и UPDATE сразу для нескольких строк
за счёт оптимизации процесса выполнения запроса.
Получает все оставшиеся строки из результата запроса. Синтаксис
Вызывает
Пример
Возвращает несколько строк из результата запроса. Синтаксис
Возвращает
Вызывает
Пример
Возвращает следующую строку из результата запроса. Синтаксис
Исключения
Пример
Максимальный размер оператора, создаваемого
executemany().
Значение по умолчанию — 1024000.
Возвращает точную строку запроса, которая будет отправлена в базу данных. Этот метод показывает итоговый SQL-запрос после подстановки параметров, что полезно для отладки и логирования. Синтаксис
Возвращает
Пример
Этот метод реализован в соответствии с расширением DB-API 2.0, используемым в Psycopg.
Переход к следующему результирующему набору (не поддерживается). Синтаксис
chDB/ClickHouse не поддерживает несколько результирующих наборов для одного запроса.
Этот метод предусмотрен для соответствия DB-API 2.0, но всегда возвращает None.
Устанавливает размеры входных данных для параметров (реализация-заглушка). Синтаксис
Этот метод ничего не делает, но требуется спецификацией DB-API 2.0.
chDB автоматически обрабатывает размеры параметров на внутреннем уровне.
Установить размеры выходных столбцов (реализация-заглушка). Синтаксис
Этот метод ничего не делает, но обязателен по спецификации DB-API 2.0.
chDB автоматически обрабатывает размер выходных данных на своей стороне.
Классы исключений для операций с базой данных chdb. Этот модуль предоставляет полную иерархию классов исключений для обработки ошибок, связанных с базой данных, в chdb в соответствии со спецификацией Python Database API v2.0. Иерархия исключений устроена следующим образом:
Эти классы исключений соответствуют спецификации Python DB API 2.0
и обеспечивают единообразную обработку ошибок в различных операциях с базой данных.
- Python Database API Specification v2.0
chdb.dbapi.connections- Управление подключениями к базе данныхchdb.dbapi.cursors- Операции с курсорами базы данных
Наследуется от:
DatabaseError
Исключение, возникающее при ошибках, связанных с обрабатываемыми данными.
Это исключение возникает, когда операции с базой данных завершаются с ошибкой из-за проблем с
обрабатываемыми данными, таких как:
- Деление на ноль
- Числовые значения вне допустимого диапазона
- Недопустимые значения даты/времени
- Ошибки усечения строк
- Ошибки преобразования типов
- Недопустимый формат данных для данного типа столбца
Примеры
Базовый класс:
Error
Исключение, вызываемое при ошибках, связанных с базой данных.
Это базовый класс для всех ошибок, связанных с базой данных. Он охватывает
все ошибки, возникающие при операциях с базой данных и относящиеся к
самой базе данных, а не к интерфейсу.
К распространённым ситуациям относятся:
- Ошибки выполнения SQL
- Проблемы с подключением к базе данных
- Проблемы, связанные с транзакциями
- Нарушения ограничений, специфичных для базы данных
Это родительский класс для более конкретных типов ошибок базы данных,
таких как
DataError, OperationalError и т. д.Базовый класс:
StandardError
Исключение, которое является базовым классом для всех остальных исключений ошибок (кроме Warning).
Это базовый класс для всех исключений ошибок в chdb, кроме предупреждений.
Он служит родительским классом для всех ошибок базы данных, которые препятствуют
успешному завершению операций.
Эта иерархия исключений соответствует спецификации Python DB API 2.0.
Warning- Для нефатальных предупреждений, которые не мешают завершению операции
DatabaseError
Исключение, которое возникает при нарушении реляционной целостности базы данных.
Это исключение возникает, когда операции с базой данных нарушают ограничения целостности,
в том числе:
- Нарушения ограничений внешнего ключа
- Нарушения первичного ключа или ограничения уникальности (дублирующиеся ключи)
- Нарушения ограничения CHECK
- Нарушения ограничения NOT NULL
- Нарушения ссылочной целостности
Примеры
Базовый класс:
Error
Исключение, возникающее при ошибках, связанных с интерфейсом базы данных, а не с самой базой данных.
Это исключение возникает при проблемах в реализации
интерфейса базы данных, например:
- Недопустимые параметры соединения
- Неправильное использование API (вызов методов у закрытых соединений)
- Ошибки протокола на уровне интерфейса
- Сбои при импорте или инициализации модуля
Эти ошибки обычно вызваны ошибками в коде или проблемами конфигурации
и могут быть устранены исправлением клиентского кода или конфигурации.
Базовый класс:
DatabaseError
Исключение, возникающее, когда база данных сталкивается с внутренней ошибкой.
Это исключение возникает, когда система базы данных сталкивается с внутренними
ошибками, не вызванными приложением, например:
- Недопустимое состояние курсора (курсор больше не является действительным)
- Несогласованность состояния транзакции (транзакция не синхронизирована)
- Проблемы, связанные с повреждением базы данных
- Повреждение внутренних структур данных
- Ошибки базы данных на уровне системы
Эти ошибки, как правило, находятся вне контроля приложения
и могут потребовать перезапуска базы данных или операций восстановления.
Базовый класс:
DatabaseError
Исключение, возникающее, когда метод или API базы данных не поддерживается.
Это исключение возникает, когда приложение пытается использовать возможности базы данных
или методы API, которые не поддерживаются текущей конфигурацией
или версией базы данных, например:
- Вызов
rollback()для соединений без поддержки транзакций - Использование расширенных возможностей SQL, не поддерживаемых версией базы данных
- Вызов методов, не реализованных текущим драйвером
- Попытка использовать отключённые возможности базы данных
Примеры
Чтобы избежать
этих ошибок, ознакомьтесь с документацией по базе данных и возможностями драйвера. По возможности предусмотрите корректный переход на резервные варианты.
Базовый класс:
DatabaseError
Исключение, возникающее при ошибках, связанных с работой базы данных.
Это исключение возникает при ошибках, происходящих во время работы базы данных
и не обязательно зависящих от программиста, включая:
- Неожиданное отключение от базы данных
- Сервер базы данных не найден или недоступен
- Сбои при обработке транзакций
- Ошибки выделения памяти во время обработки
- Нехватка места на диске или исчерпание ресурсов
- Внутренние ошибки сервера базы данных
- Сбои аутентификации или авторизации
Эти ошибки обычно носят временный характер и могут быть устранены повторной попыткой
выполнить операцию или устранением проблем на уровне системы.
Базовый класс:
DatabaseError
Исключение, возникающее при ошибках программирования в операциях с базой данных.
Это исключение возникает, когда в работе приложения с базой данных
допущены ошибки программирования, в том числе:
- Таблица или столбец не найдены
- Таблица или индекс уже существуют при создании
- Синтаксические ошибки SQL в операторах
- Указано неверное количество параметров в подготовленных операторах
- Недопустимые SQL-операции (например, DROP для несуществующих объектов)
- Некорректное использование методов API базы данных
Примеры
Базовый класс:
Exception
Исключение, связанное с работой chdb.
Это базовый класс для всех исключений, связанных с chdb. Он наследуется от
встроенного класса Python Exception и служит корневым классом в иерархии
исключений для операций с базой данных.
Этот класс исключений соответствует спецификации Python DB API 2.0
для обработки исключений баз данных.
Базовый класс:
StandardError
Исключение, возникающее при важных предупреждениях, таких как усечение данных при вставке и т. д.
Это исключение возникает, когда операция с базой данных завершается, но
сопровождается важными предупреждениями, на которые приложение должно обратить внимание.
Распространённые сценарии:
- Усечение данных при вставке
- Потеря точности при числовых преобразованиях
- Предупреждения при преобразовании кодировки
Соответствует спецификации Python DB API 2.0 для исключений-предупреждений.
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 — это отдельное значение типа. Примеры
Расширенный frozenset для сравнения типов в DB-API 2.0. Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0. Он обеспечивает гибкую проверку типов, при которой отдельные элементы можно сравнивать с набором как с помощью операторов равенства, так и неравенства. Используется для таких констант типов, как STRING, BINARY, NUMBER и т. д., чтобы можно было выполнять сравнения вида “field_type == STRING”, где field_type — это отдельное значение типа. Примеры
Расширенный frozenset для сравнения типов в соответствии с DB-API 2.0. Этот класс расширяет frozenset, добавляя поддержку семантики сравнения типов из DB-API 2.0. Он обеспечивает гибкую проверку типов, при которой отдельные элементы можно сравнивать с набором с помощью операторов равенства и неравенства. Используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать сравнения вида “field_type == STRING”, где field_type — это отдельное значение типа. Примеры
Расширенный frozenset для сравнения типов в DB-API 2.0. Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0. Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать с множеством с помощью как операторов равенства, так и неравенства. Он используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать сравнения вида “field_type == STRING”, где field_type — это отдельное значение типа. Примеры
Расширенный frozenset для сравнения типов в DB-API 2.0. Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0. Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать с множеством как с помощью операторов равенства, так и неравенства. Используется для таких констант типов, как STRING, BINARY, NUMBER и т. д., чтобы можно было выполнять сравнения вида “field_type == STRING”, где field_type — это отдельное значение типа. Примеры
Расширенный frozenset для сравнения типов в DB-API 2.0. Этот класс расширяет frozenset, чтобы поддерживать семантику сравнения типов в DB-API 2.0. Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать с набором с помощью операторов равенства и неравенства. Это используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать сравнения вида “field_type == STRING”, где field_type — это значение отдельного типа. Примеры
Расширенный
frozenset для сравнения типов в DB-API 2.0.
Этот класс расширяет frozenset, добавляя поддержку семантики сравнения типов DB-API 2.0.
Он позволяет гибко проверять типы, когда отдельные элементы можно сравнивать
с Set с помощью операторов равенства и неравенства.
Используется для констант типов, таких как STRING, BINARY, NUMBER и т. д., чтобы поддерживать
сравнения вида “field_type == STRING”, где field_type — это отдельное значение типа.
Примеры
- Управление соединениями: Всегда закрывайте соединения и курсоры по завершении работы
- Контекстные менеджеры: Используйте операторы
withдля автоматического освобождения ресурсов - Обработка батчами: Используйте
fetchmany()для больших результирующих наборов - Обработка ошибок: Оборачивайте операции с базой данных в блоки try-except
- Привязка параметров: По возможности используйте параметризованные запросы
- Управление памятью: Избегайте
fetchall()для очень больших наборов данных
- Интерфейс DB-API 2.0 в chDB совместим с большинством Python-инструментов для работы с базами данных
- Интерфейс обеспечивает потокобезопасность уровня 1 (потоки могут совместно использовать модули, но не соединения)
- Строки подключения поддерживают те же параметры, что и сеансы chDB
- Поддерживаются все стандартные исключения DB-API 2.0
NULL отображается как \N, а к строковым значениям и датам применяется CSV-экранирование.
Зарегистрируйте функцию Python в качестве SQL-функции chDB.
Синтаксис
Каждый параметр типа (элементы
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— сопоставляется согласно разделу Автоматическое сопоставление типов
drop_function.
Пример
Удаляет ранее зарегистрированную UDF Python. Если функция не зарегистрирована, ничего не происходит, поэтому её можно безопасно вызывать без проверки. Синтаксис
Декоратор для регистрации функции Python в качестве SQL-функции chDB. Функцию по-прежнему можно вызывать как обычную функцию Python; одновременно она доступна в SQL-запросах под именем
__name__.
Синтаксис
create_function, за исключением name и func, которые определяются декорированной функцией.
Примеры
Импортируйте типы из
chdb.sqltypes:
Типы можно задавать несколькими способами:
Настройте обработку значений NULL с помощью параметра
on_null.
Управляйте обработкой исключений с помощью параметра
on_error.
Пользовательские функции (UDF) полностью поддерживают типы
Date, Date32, DateTime и DateTime64 с поддержкой часовых поясов.
- Входные значения ClickHouse
DateTime/DateTime64преобразуются в объекты Pythondatetimeс информацией о часовом поясе - При возврате в ClickHouse выходные объекты Python
datetimeсохраняют информацию о часовом поясе - Тип
DATETIME64изchdb.sqltypesпо умолчанию имеет scale 6 (микросекунды), что эквивалентноDateTime64(6)
Декоратор для Python UDF (пользовательская функция) в chDB. Синтаксис
Примечания
- Функция должна быть без сохранения состояния. Поддерживаются только UDF, а не UDAF.
- Возвращаемый тип по умолчанию — String. Он должен быть одним из типов данных ClickHouse.
- Функция должна принимать аргументы типа String. Все аргументы являются строками.
- Функция будет вызываться для каждой строки входных данных.
- Функция должна быть чистой функцией Python. Импортируйте все модули, используемые в самой функции.
- Используется тот же интерпретатор Python, что и для запуска скрипта.
Генерирует файлы конфигурации UDF и исполняемого скрипта. Эта функция создает необходимые файлы для пользовательской функции (UDF) в chDB:
- Исполняемый Python-скрипт для обработки входных данных
- XML-файл конфигурации, который регистрирует UDF в ClickHouse
Эта функция обычно вызывается декоратором @chdb_udf, и её не следует
вызывать напрямую.
Служебные функции и вспомогательные средства для chDB. Этот модуль содержит различные утилиты для работы с chDB, включая вывод типов, средства преобразования данных и инструменты отладки.
Преобразует список словарей в столбцовый формат. Эта функция принимает список словарей и преобразует его в словарь, где каждый ключ соответствует столбцу, а каждое значение — это список значений столбца. Отсутствующие значения в словарях обозначаются как None. Синтаксис
Возвращает
Пример
Преобразует вложенный словарь в плоский. Эта функция принимает вложенный словарь и преобразует его в плоский, объединяя вложенные ключи с помощью разделителя. Списки словарей сериализуются в JSON-строки. Синтаксис
Возвращает
Пример
Определяет наиболее подходящий тип данных для списка значений. Эта функция анализирует список значений и определяет наиболее подходящий тип данных, который может представлять все значения в списке. Она учитывает целочисленные, беззнаковые целочисленные, десятичные типы и типы с плавающей точкой и по умолчанию использует «string», если значения не могут быть представлены ни одним числовым типом или если все значения — None. Синтаксис
Возвращаемое значение
- Если все значения в списке — None, функция возвращает “string”.
- Если хотя бы одно значение в списке является строкой, функция сразу возвращает “string”.
- Функция предполагает, что числовые значения могут быть представлены как целые числа, десятичные числа или числа с плавающей точкой в зависимости от их диапазона и точности.
Определяет типы данных для каждого столбца в столбцовой структуре данных. Эта функция анализирует значения в каждом столбце и определяет наиболее подходящий тип данных для каждого столбца на основе выборки данных. Синтаксис
Возвращает
Базовый класс:
ABC
Считывает указанное количество строк из заданных столбцов и возвращает список объектов, где каждый объект содержит последовательность значений одного столбца.
Возвращаемое значение
Базовый класс:
ABC
Формирует и возвращает итоговые данные из блоков. Метод должен быть реализован в подклассах.
Записывает столбцы данных в блоки. Должен быть реализован в подклассах.
Базовый класс:
Exception
Базовый класс исключений для ошибок, связанных с chDB.
Это исключение возникает, когда выполнение запроса chDB завершается неудачно
или приводит к ошибке. Оно наследуется от стандартного класса Python Exception и
содержит сведения об ошибке из базового движка ClickHouse.
Сообщение исключения обычно содержит подробную информацию об ошибке
из ClickHouse, включая синтаксические ошибки, несоответствия типов, отсутствие
таблиц/столбцов и другие проблемы при выполнении запроса.
Переменные
Примеры
Это исключение автоматически генерируется функцией chdb.query() и связанными
функциями, когда движок ClickHouse сообщает об ошибке.
Вам следует перехватывать это исключение при обработке запросов, которые
могут завершиться с ошибкой, чтобы обеспечить надлежащую обработку ошибок в вашем приложении.
iterable, кортеж инициализируется его элементами.
Если аргумент является кортежем, возвращается тот же объект.
- encoding по умолчанию — ‘utf-8’.
- errors по умолчанию — ‘strict’.
- encoding по умолчанию — ‘utf-8’.
- errors по умолчанию — ‘strict’.