Перейти к основному содержимому
Перейти к основному содержимому

ODBC-драйвер

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

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

Исходный код драйвера доступен в ClickHouse-ODBC GitHub Repository.

Совет

Для лучшей совместимости настоятельно рекомендуется обновить сервер ClickHouse до версии 24.11 или более новой.

Примечание

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

Ваши отзывы чрезвычайно ценны и помогают определять приоритеты новых возможностей и улучшений. Если вы сталкиваетесь с ограничениями, отсутствующей функциональностью или неожиданным поведением, пожалуйста, поделитесь своими наблюдениями или запросами на новые возможности через трекер задач по адресу https://github.com/ClickHouse/clickhouse-odbc/issues

Установка на Windows​

Последнюю версию драйвера можно найти по адресу https://github.com/ClickHouse/clickhouse-odbc/releases/latest. Там вы можете скачать и запустить установщик MSI и выполнить простые шаги установки.

Тестирование​

Вы можете протестировать драйвер, запустив этот простой скрипт PowerShell. Скопируйте приведённый ниже текст, укажите URL, пользователя и пароль, затем вставьте текст в командную строку PowerShell — после выполнения $reader.GetValue(0) должна отобразиться версия сервера ClickHouse.

$url = "http://127.0.0.1:8123/"
$username = "default"
$password = ""
$conn = New-Object System.Data.Odbc.OdbcConnection("`
    Driver={ClickHouse ODBC Driver (Unicode)};`
    Url=$url;`
    Username=$username;`
    Password=$password")
$conn.Open()
$cmd = $conn.CreateCommand()
$cmd.CommandText = "select version()"
$reader = $cmd.ExecuteReader()
$reader.Read()
$reader.GetValue(0)
$reader.Close()
$conn.Close()

Параметры конфигурации​

Приведённые ниже параметры представляют собой наиболее часто используемые настройки для настройки соединения через драйвер ClickHouse ODBC. Они охватывают основные параметры аутентификации, поведения соединения и обработки данных. Полный список поддерживаемых параметров доступен на странице проекта в GitHub https://github.com/ClickHouse/clickhouse-odbc.

  • Url: Указывает полный HTTP(S)‑эндпоинт сервера ClickHouse. Включает протокол, хост, порт и необязательный путь.
  • Username: Имя пользователя, используемое для аутентификации на сервере ClickHouse.
  • Password: Пароль, связанный с указанным именем пользователя. Если не задан, драйвер подключается без аутентификации по паролю.
  • Database: База данных по умолчанию, используемая для соединения.
  • Timeout: Максимальное время (в секундах), в течение которого драйвер ожидает ответ сервера перед прерыванием запроса.
  • ClientName: Пользовательский идентификатор, отправляемый на сервер ClickHouse как часть клиентских метаданных. Полезен для трассировки или различения трафика от разных приложений. Этот параметр будет частью заголовка User-Agent в HTTP‑запросах, формируемых драйвером.
  • Compression: Включает или отключает HTTP‑сжатие для полезной нагрузки запросов и ответов. При включении позволяет уменьшить использование полосы пропускания и улучшить производительность для больших наборов результатов.
  • SqlCompatibilitySettings: Включает параметры запросов, которые заставляют ClickHouse вести себя более похоже на традиционную реляционную базу данных. Это полезно, когда запросы автоматически генерируются сторонними инструментами, например Power BI. Эти инструменты обычно не знают о некоторых особенностях ClickHouse и могут генерировать запросы, приводящие к ошибкам или неожиданным результатам. Дополнительные сведения см. в разделе Настройки ClickHouse, используемые параметром конфигурации SqlCompatibilitySettings.

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

  • Локально установленный сервер ClickHouse в экземпляре WSL
Driver={ClickHouse ODBC Driver (Unicode)};Url=http://localhost:8123/;Username=default
  • Инстанс ClickHouse Cloud.
Driver={ClickHouse ODBC Driver (Unicode)};Url=https://you-instance-url.gcp.clickhouse.cloud:8443/;Username=default;Password=your-password

Интеграция с Microsoft Power BI​

Вы можете использовать ODBC-драйвер для подключения Microsoft Power BI к серверу ClickHouse. Power BI предоставляет два варианта подключения: общий ODBC-коннектор и коннектор ClickHouse, оба входят в стандартную установку Power BI.

Оба коннектора используют ODBC во внутренней реализации, но отличаются возможностями:

  • ClickHouse Connector (рекомендуется)
    Использует ODBC «под капотом», но поддерживает режим DirectQuery. В этом режиме Power BI автоматически генерирует SQL-запросы и получает только те данные, которые необходимы для каждой визуализации или операции фильтрации.

  • ODBC Connector
    Поддерживает только режим Import. Power BI выполняет предоставленный пользователем запрос (или выбирает всю таблицу) и импортирует результирующий набор данных в Power BI. Последующие обновления повторно импортируют весь набор данных.

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

Для получения дополнительной информации об интеграции Microsoft Power BI с ClickHouse см. страницу документации ClickHouse по интеграции с Power BI.

Параметры совместимости с SQL​

ClickHouse использует собственный уникальный диалект SQL и в некоторых случаях ведёт себя иначе, чем другие базы данных, такие как MS SQL Server, MySQL или PostgreSQL. Часто эти различия являются преимуществом, поскольку они основаны на более удобном синтаксисе, который упрощает использование возможностей ClickHouse.

Однако драйвер ODBC часто используется в средах, где запросы генерируются сторонними инструментами, такими как Power BI, а не пишутся пользователями. Эти запросы обычно опираются на минимальное подмножество стандарта SQL. В таких случаях отклонения ClickHouse от стандарта SQL могут вести себя не так, как ожидается, и приводить к неожиданным результатам или ошибкам. Драйвер ODBC предоставляет дополнительный параметр конфигурации SqlCompatibilitySettings, который задаёт определённые параметры запроса, чтобы сделать поведение ClickHouse более близким к стандартному SQL.

Настройки ClickHouse, включаемые параметром конфигурации SqlCompatibilitySettings​

В этом разделе описывается, какие настройки изменяет драйвер ODBC и по какой причине.

cast_keep_nullable

По умолчанию ClickHouse не допускает преобразование типов Nullable в не-Nullable типы. Однако многие BI-инструменты не различают nullable и не-nullable типы при выполнении преобразований типов. В результате нередко можно увидеть запросы наподобие следующего, которые генерируются BI-инструментами:

SELECT sum(CAST(value, 'Int32'))
FROM values

По умолчанию, если столбец value имеет тип данных Nullable, этот запрос завершится с ошибкой со следующим сообщением:

DB::Exception: Cannot convert NULL value to non-Nullable type: while executing 'FUNCTION CAST(__table1.value :: 2,
'Int32'_String :: 1) -> CAST(__table1.value, 'Int32'_String) Int32 : 0'. (CANNOT_INSERT_NULL_IN_ORDINARY_COLUMN)

Включение cast_keep_nullable изменяет поведение CAST так, что он сохраняет признак Nullable у своих аргументов. Это делает поведение ClickHouse более похожим на другие базы данных и стандарт SQL для такого типа преобразования.

prefer_column_name_to_alias

ClickHouse позволяет ссылаться на выражения в том же списке SELECT по их псевдонимам. Например, этот запрос позволяет избежать повторения и его проще записать:

SELECT
    sum(value) AS S,
    count() AS C,
    S / C
FROM test

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

SELECT
    sum(value) AS value,
    avg(value)
FROM test

Какое значение value должна агрегировать функция avg(value)? По умолчанию ClickHouse предпочитает использовать псевдоним, фактически превращая это во вложенную агрегацию, что не соответствует ожиданиям большинства инструментов.

Само по себе это редко становится проблемой, но некоторые BI‑инструменты генерируют запросы с подзапросами, которые повторно используют псевдонимы столбцов. Например, Power BI часто генерирует запросы, похожие на следующий пример:

SELECT
    sum(C1) AS C1,
    count(C1) AS C2
FROM
(
    SELECT sum(value) AS C1
    FROM test
    GROUP BY group_index
) AS TBL

Ссылки на C1 могут вызвать следующую ошибку:

Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function sum(C1) AS C1 is found
inside another aggregate function in query. (ILLEGAL_AGGREGATION)

Другие базы данных обычно не разрешают алиасы на этом уровне и вместо этого рассматривают C1 как столбец из подзапроса. Чтобы сохранить аналогичное поведение в ClickHouse и позволить таким запросам выполняться без ошибок, драйвер ODBC включает параметр prefer_column_name_to_alias.

В большинстве случаев включение этих параметров не должно вызывать проблем. Однако пользователи с параметром readonly, установленным в 1, не могут менять какие-либо настройки, даже для запросов SELECT. Для таких пользователей включение SqlCompatibilitySettings приведёт к ошибке. В следующем разделе объясняется, как настроить этот параметр конфигурации для работы с пользователями только с правами чтения.

Настройка параметров совместимости SQL для пользователей с доступом только на чтение​

При подключении к ClickHouse через драйвер ODBC с параметром SqlCompatibilitySettings, установленным в значение 1, пользователь с настройкой readonly, установленной в 1, столкнётся с ошибкой, так как драйвер пытается изменить настройки запроса:

Code: 164. DB::Exception: Cannot modify 'cast_keep_nullable' setting in readonly mode. (READONLY)
Code: 164. DB::Exception: Cannot modify 'prefer_column_name_to_alias' setting in readonly mode. (READONLY)

Это происходит потому, что пользователям в режиме read-only не разрешено изменять настройки, даже для отдельных запросов SELECT. Существует несколько способов это исправить.

Вариант 1. Установить readonly в значение 2

Это самый простой вариант. Установка readonly в 2 позволяет изменять настройки, при этом оставляя пользователя в режиме только для чтения.

ALTER USER your_odbc_user MODIFY SETTING
    readonly = 2

В большинстве случаев установка readonly в значение 2 — самый простой и рекомендуемый способ решить эту проблему. Если это вам не подходит, используйте второй вариант.

Вариант 2. Изменение настроек пользователя в соответствии с настройками, задаваемыми драйвером ODBC.

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

ALTER USER your_odbc_user MODIFY SETTING
    cast_keep_nullable = 1,
    prefer_column_name_to_alias = 1

С этим изменением драйвер ODBC по‑прежнему может пытаться применить настройки, но, поскольку значения уже совпадают, фактических изменений не происходит и ошибка не возникает.

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