ClickHouse коннектор#

Коннектор позволяет отправлять запросы и создавать таблицы в СУБД ClickHouse. Коннектор может быть использован для объединения данных из ClickHouse с данными из других источников.

Требования#

  • ClickHouse версии 24.3 и выше или Altinity версии 22.3 и выше

  • Наличие сетевого доступа к ClickHouse со всех узлов CedrusData (coordinator и worker). По умолчанию, ClickHouse использует порт 8123

Конфигурация#

Для создания каталога ClickHouse установите параметр connector.name в значение clickhouse. Например, для конфигурации каталога с именем example создайте файл etc/catalog/example.properties со следующим содержимым. Замените параметры подключения в соответствии с конфигурацией вашего сервера ClickHouse.

connector.name=clickhouse
connection-url=jdbc:clickhouse://host1:8123/
connection-user=exampleuser
connection-password=examplepassword

Параметр connection-url определяет JDBC строку подключения к серверу ClickHouse. Вы можете ознакомиться с полным списком допустимых параметров в документации JDBC драйвера ClickHouse.

Параметры connection-user and connection-password определяют имя пользователя и пароль для подключения к экземпляру ClickHouse (как правило, это сервисный пользователь). Если вы не хотите хранить имя пользователя и пароль в открытом виде воспользуйтесь функционалом передачи секретов через переменные окружения.

Защищенное подключение#

Если ваш экземпляр ClickHouse сконфигурирован с использованием TLS сертификатов, вы можете включить поддержку TLS между кластером CedrusData и ClickHouse путем добавления необходимых параметров к строке подключения, указанной в connection-url. Например, для JDBC драйвера ClickHouse версии 2.6.4 вы можете включить поддержку TLS путем добавления параметра ssl=true:

connection-url=jdbc:clickhouse://host1:8443/?ssl=true

Для ознакомления со всеми доступными параметрами TLS ознакомьтесь с документацией JDBC-драйвра Clickhouse.

Аутентификация в источнике данных#

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

  • INLINE - в файле конфигурации каталога (в том числе, используя секреты, чтобы не хранить значения в открытом виде).

  • FILE - в отдельном properties файле.

  • KEYSTORE - в зашифрованном keystore файле.

  • Из extra credentials клиента CedrusData.

Конфигурация#

Название

Описание

credential-provider.type

Тип credential provider. Допустимые значения: INLINE (значение по умолчанию), FILE или KEYSTORE.

connection-user

Имя пользователя для подключения к источнику. Используется при credential-provider.type=INLINE.

connection-password

Пароль для подключения к источнику. Используется при credential-provider.type=INLINE.

connection-credential-file

Путь к properties файлу, содержащему параметры connection-user and connection-password. Используется при credential-provider.type=FILE.

keystore-file-path

Путь к keystore файлу, из которого следует прочитать имя пользователя и пароль. Используется при credential-provider.type=KEYSTORE.

keystore-type

Тип keystore файла. Например, JKS или PEM.

keystore-password

Пароль к keystore файлу.

keystore-user-credential-name

Имя keystore entity, содержащей имя пользователя для подключения к источнику.

keystore-user-credential-password

Пароль к keystore entity, содержащей имя пользователя для подключения к источнику

keystore-password-credential-name

Имя keystore entity, содержащей пароль для подключения к источнику.

keystore-password-credential-password

Пароль к keystore entity, содержащей пароль для подключения к источнику.

user-credential-name

Имя параметра extra credentials, значение которого следует использовать в качестве имени пользователя. См. extraCredentials в разделе Параметры подключения.

password-credential-name

Имя параметра extra credentials, значение которого следует использовать в качестве пароля. См. extraCredentials в разделе Параметры подключения.

Аутентификация в источнике данных от имени текущего пользователя#

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

Для использования данного типа аутентификации узел должен использовать PASSWORD аутентификацию с включенным параметром cedrusdata.http-server.authentication.password.populate-extra-credentials. Убедитесь, что файл config.properties содержит следующие параметры:

http-server.authentication.type=PASSWORD
cedrusdata.http-server.authentication.password.populate-extra-credentials=true

В файле конфигурации коннектора добавьте два параметра:

user-credential-name=cedrusdata.username
password-credential-name=cedrusdata.password

Теперь коннектор будет использовать имя и пароль текущего пользователя для аутентификации в источнике.

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

Несколько экземпляров ClickHouse#

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

Общие параметры конфигурации#

Название

Описание

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

case-insensitive-name-matching

Включить поддержку case insensitive идентификаторов.

false

case-insensitive-name-matching.cache-ttl

Время жизни закэшированных метаданных о case insensitive идентификаторах. Значение имеет тип duration.

1m

case-insensitive-name-matching.config-file

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

null

case-insensitive-name-matching.config-file.refresh-period

Частота проверки обновлений файла case-insensitive-name-matching.config-file.

0 (обновление отключено)

metadata.cache-ttl

Время жизни закэшированных метаданных (дескрипторы таблицы и колонок, статистики). Положительное значение включает кэширование. Значение имеет тип duration.

0 (кэширование отключено)

metadata.cache-missing

Кэшировать ли информацию о том, что для используемых таблиц и колонок отсутствуют статистики. Включение данного параметра может ускорить планирование некоторых запросов. Однако, если информация об отсутствии статистик для конкретного объекта СУБД закэширована, но статистики стали доступны позднее (например, была запущена команда ANALYZE), CedrusData не сможет использовать статистики, пока не истечет время жизни закэшированной записи в соответствии с metadata.cache-ttl.

false

metadata.schemas.cache-ttl

Время жизни закэшированных имен схем. Положительное значение включает кэширование. Допустимо только, если параметр metadata.cache-ttl имеет положительное значение. Значение имеет тип duration.

0 (кэширование отключено)

metadata.tables.cache-ttl

Время жизни закэшированных имен таблиц. Положительное значение включает кэширование. Допустимо только, если параметр metadata.cache-ttl имеет положительное значение. Значение имеет тип duration.

0 (кэширование отключено)

metadata.statistics.cache-ttl

Время жизни закэшированных статистик. Положительное значение включает кэширование. Допустимо только, если параметр metadata.cache-ttl имеет положительное значение. Значение имеет тип duration.

0 (кэширование отключено)

metadata.cache-maximum-size

Максимальное количество объектов, хранящихся в metadata cache.

10000

write.batch-size

Максимальное количество команд в batch операциях записи данных. Изменение данного параметра не рекомендовано, так как оно может негативно сказаться на производительности.

1000

dynamic-filtering.enabled

Использовать ли динамические фильтры при работе с JDBC источником.

true

dynamic-filtering.wait-timeout

Максимальное время ожидания готовности динамических фильтров с build стороны оператора join перед запуском JDBC запроса к источнику. Увеличение таймаута может позволить CedrusData выполнить запрос к источнику с более селективными фильтрами, но в то же время может увеличить latency некоторых запросов. Значение имеет тип duration.

20s

Добавление комментариев к SQL-запросам к источнику#

Опциональный параметр query.comment-format позволяет добавить комментарий, который будет добавлен к каждому SQL-запросу, отправляемому из CedrusData в источник. Значение параметра может содержать произвольные символы, а также набор специальных выражений, которые будут автоматически заменены CedrusData:

  • $QUERY_ID: Уникальный идентификатор запроса.

  • $USER: Имя пользователя CedrusData, который инициировал выполнение запроса.

  • $SOURCE: Идентификатор клиентского приложения. Например, trino-cli.

  • $TRACE_TOKEN: Trace token, заданный клиентским приложением.

Вы также можете добавить в комментарий значения переменных окружений CedrusData с помощью синтаксиса ${ENV:VARIABLE-NAME}.

Пример ниже добавляет комментарий «Query sent by Trino» к каждому запросу к SQL-источнику:

query.comment-format=Query sent by Trino

Пример SQL-запроса, отправленного к источнику:

SELECT * FROM example_table; /*Query sent by Trino.*/

Пример ниже добавляет специальные выражения в строку комментария:

query.comment-format=Query $QUERY_ID sent by user $USER from Trino.

Если пользователь Jane отправил запрос с идентификатором 20230622_180528_00000_bkizg, то источник получит SQL-запрос со следующим комментарием:

SELECT * FROM example_table; /*Query 20230622_180528_00000_bkizg sent by user Jane from Trino.*/

Примечание

Некоторые JDBC-драйвера могут автоматически удалять комментарии.

Domain compaction threshold#

CedrusData позволяет делегировать применение предикатов источнику данных (pushdown). Во многих случаях это существенно уменьшает количество записей, которые возвращает источник, и улучшает производительность. Однако, pushdown сложных предикатов (например, выражение IN со множеством значений) может негативно сказаться на производительности. При достижении порога сложности предиката, CedrusData автоматически преобразует предикат к более компактной форме. Например, предикат a IN (1, 2, ..., 100) может быть преобразован в a BETWEEN 1 AND 100. В большинстве случаев такое преобразование улучшает производительность запросов. Однако, в некоторых случаях может быть предпочтительнее передать сложный предикат в неизменном виде, так как источник данных может его обработать эффективнее, чем преобразованный предикат.

Вы можете увеличить значение порога сложности, чтобы CedrusData передавал предикат в источник без изменений. Используйте для этого параметр конфигурации каталога domain-compaction-threshold или свойство сессии domain_compaction_threshold.

Case insensitive идентификаторы#

Когда параметр конфигурации case-insensitive-name-matching установлен в true, CedrusData может обращаться к схемам и таблицам источника, имена которых не являются lowercase. Для этого CedrusData сопоставляет lowercase название схемы или таблицы с ее реальным названием в источнике данных. Например, если таблица в источнике данных имеет название Customers, CedrusData позволяет обратиться к ней по имени customers.

В случае, если источник имеет несколько объектов, имена которых отличаются только регистром (например, Customer и customer), CedrusData не может автоматически определить, к какому объекту обращаться.

В этом случае вы можете явно задать сопоставление имен с помощью файла в JSON формате, путь к которому следует указать в параметре конфигурации каталога case-insensitive-name-matching.config-file. Например:

{
  "schemas": [
    {
      "remoteSchema": "CaseSensitiveName",
      "mapping": "case_insensitive_1"
    },
    {
      "remoteSchema": "cASEsENSITIVEnAME",
      "mapping": "case_insensitive_2"
    }],
  "tables": [
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "tablex",
      "mapping": "table_1"
    },
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "TABLEX",
      "mapping": "table_2"
    }]
}

В данном случае, при обращении из CedrusData к схеме case_insensitive_1, запрос будет переадресован к схеме источника CaseSensitiveName, а при обращении из CedrusData к таблице case_insensitive_1.table_1 запрос будет переадресован к таблице источника CaseSensitiveName.tablex.

По умолчанию если вы изменяете содержимое данного файла, экземпляр CedrusData должен быть перезапущен, чтобы применить изменения. Если вы хотите изменять содержимое файла без перезапуска CedrusData, вы можете установить параметр конфигурации case-insensitive-name-matching.config-file.refresh-period, который определяет частоту повторного чтения данного файла.

case-insensitive-name-matching.config-file.refresh-period=30s

Работа с ClickHouse#

Коннектор ClickHouse отображает каждую базу данных (database) ClickHouse в виде логической схемы CedrusData. Запустите команды SHOW SCHEMAS, чтобы отобразить список баз данных ClickHouse:

SHOW SCHEMAS FROM example;

Если у вас есть база данных ClickHouse web, запустите команду SHOW TABLES, чтобы отобразить таблицы это базы данных:

SHOW TABLES FROM example.web;

Используйте команды DESCRIBE или SHOW COLUMNS, чтобы отобразить колонки отдельных таблиц:

DESCRIBE example.web.clicks;
SHOW COLUMNS FROM example.web.clicks;

Используйте команду SELECT, чтобы получить данные из таблиц ClickHouse:

SELECT * FROM example.web.clicks;

Распределенное чтение и запись#

Таблица ClickHouse с движком Distributed не хранит данные самостоятельно, а перенаправляет чтение и запись в underlying-таблицы шардов. Коннектор может работать через Distributed-таблицу либо обращаться непосредственно к underlying-таблицам.

Описанные ниже настройки применяются к именованным Distributed-таблицам. Для обычных таблиц коннектор использует стандартный JDBC-путь чтения и записи.

Режимы записи#

Режим записи выбирается параметром clickhouse.distributed-write или соответствующим свойством сессии distributed_write.

Режимы записи в Distributed-таблицы#

Режим

Путь записи

Выбор конечного шарда

Назначение

disabled

Стандартная JDBC-запись в Distributed-таблицу. Это режим по умолчанию.

ClickHouse

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

enabled

Коннектор выполняет параллельную запись в Distributed-таблицу через узлы разных шардов ClickHouse.

Конечный шард выбирает ClickHouse: таблица с движком Distributed вычисляет sharding expression и направляет каждую строку в соответствующий шард.

Используйте этот режим, когда маршрутизацию строк по шардам должен выполнять ClickHouse, в том числе для sharding expressions, не поддерживаемых режимом direct.

direct

Коннектор записывает непосредственно в underlying-таблицы шардов, минуя маршрутизацию Distributed-таблицы.

CedrusData вычисляет шард для поддерживаемых sharding expressions.

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

Поведение direct зависит от sharding expression целевой таблицы:

  • для поддерживаемого детерминированного выражения и доступной sharding-колонки коннектор вычисляет конечный шард для каждой строки;

  • для rand(), отсутствующего или пустого sharding key, а также поддерживаемого выражения, которое нельзя вычислить по колонкам INSERT, каждый writer распределяет целые страницы данных между шардами по round-robin;

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

Несколько CedrusData writer operators могут одновременно писать в один ClickHouse шард. Один writer также может открывать подключения к нескольким шардам. Количество writer operators и количество ClickHouse шардов не обязаны совпадать.

Настройка распределенного чтения и записи#

Параметры распределенного чтения и записи#

Параметр каталога

Свойство сессии каталога

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

Описание

clickhouse.distributed-write

distributed_write

disabled

Режим записи: disabled, enabled или direct.

clickhouse.distributed-write.preferred-write-partitioning-mode

preferred_write_partitioning_mode

bucket

Определяет способ распределения строк в Exchange при use_preferred_write_partitioning = true: по шардам (shard) или по бакетам, объединяющим шард и слот локальной партиции (bucket). Если local partitioning выключен или недоступен, bucket работает как shard.

clickhouse.distributed-write.local-partitioning.enabled

distributed_write_local_partitioning

false

Включает раздельное формирование JDBC-батчей по слотам, вычисленным из PARTITION BY underlying-таблицы.

clickhouse.distributed-write.local-partition-cardinality

distributed_write_local_partition_cardinality

32

Количество partition slots, используемых для группировки локальных партиций.

clickhouse.distributed-direct-read.enabled

distributed_direct_read

false

Включает прямое чтение underlying-таблиц шардов.

clickhouse.distributed.shard-port

—

8123

Задает HTTP-порт по умолчанию для подключения к шардам ClickHouse, обнаруженным через system.clusters.

clickhouse.distributed.cluster-shards-addresses

—

Данные из system.clusters

Задает адреса шардов ClickHouse вместо их автоматического обнаружения через system.clusters. Для каждого шарда укажите адрес одной реплики.

Например, следующая конфигурация включает режим enabled, группировку по локальным партициям и выбирает распределение Exchange по бакетам. Оно применяется, когда use_preferred_write_partitioning=true:

clickhouse.distributed-write=enabled
clickhouse.distributed-write.preferred-write-partitioning-mode=bucket
clickhouse.distributed-write.local-partitioning.enabled=true
clickhouse.distributed-write.local-partition-cardinality=32

Настройки каталога можно переопределить для отдельной сессии. Для каталога example:

SET SESSION example.distributed_write = 'direct';
SET SESSION example.preferred_write_partitioning_mode = 'bucket';
SET SESSION example.distributed_write_local_partitioning = true;
SET SESSION example.distributed_write_local_partition_cardinality = 32;
SET SESSION use_preferred_write_partitioning = true;

Предпочтительное распределение записи#

Системное свойство use_preferred_write_partitioning определяет, использует ли CedrusData предложенное коннектором распределение строк между writer operators. Свойство preferred_write_partitioning_mode влияет только на Exchange перед записью: оно не меняет distributed_write и не заменяет выбор конечного шарда внутри sink или ClickHouse.

Коннектор предлагает preferred write partitioning, только если выполняются все условия:

  • выбран режим direct или enabled;

  • use_preferred_write_partitioning имеет значение true;

  • запись выполняется в именованную Distributed-таблицу;

  • sharding expression поддерживается, sharding-колонка присутствует в INSERT, а ее тип позволяет вычислить шард.

Режимы preferred write partitioning#

Режим

Распределение строк в Exchange

Привязка к шардам ClickHouse

Утилизация ресурсов и память

shard

Строки группируются по вычисленному шарду ClickHouse. Для каждого шарда создается отдельный Exchange bucket.

В direct каждый writer обычно записывает данные в меньшее число шардов. Эта привязка существует только на уровне распределения строк: worker не закрепляется за конкретным шардом ClickHouse. В enabled узел, принимающий запись, выбирается независимо от Exchange bucket, а конечный шард определяет ClickHouse, поэтому привязки writer к шарду нет.

Может задействовать не более shardCount writers. При local partitioning слоты каждого шарда концентрируются на меньшем числе workers, из-за чего увеличиваются потребление памяти, количество удерживаемых JDBC-батчей и влияние неравномерного размера шардов.

bucket

При включенном и поддерживаемом local partitioning строки группируются по (shard, partitionSlot). Для каждой такой пары создается отдельный Exchange bucket. Без local partitioning режим работает как shard.

В direct один writer может получить бакеты нескольких шардов и записывать в несколько шардов ClickHouse. В enabled привязки writer к конечному шарду также нет.

Создает до shardCount * localPartitionCardinality бакетов и позволяет задействовать больше writers. Бакеты равномернее распределяются между workers, поэтому на каждом worker обычно удерживается меньше JDBC-батчей и снижается пиковое потребление памяти.

Каждый Exchange bucket назначается одному writer, но один writer может обслуживать несколько бакетов. Если бакетов меньше, чем доступных writers, часть writers не будет использоваться. Если бакетов больше, они распределяются между writers настолько равномерно, насколько позволяет план выполнения.

Для enabled режим bucket обычно предпочтительнее: конечный шард выбирает ClickHouse, поэтому Exchange по shard не создает привязки writer к узлу, принимающему запись, но концентрирует partition slots на меньшем числе workers. Для direct режим shard может быть полезен, когда концентрация записи по шардам важнее равномерного использования workers и памяти.

При use_preferred_write_partitioning=false значение preferred_write_partitioning_mode игнорируется. Если используется значение по умолчанию redistribute_writes=true, CedrusData распределяет строки между writers по round-robin. При включенном writer scaling используется масштабируемый вариант round-robin. Если redistribute_writes=false, отдельный writer Exchange может не добавляться.

Round-robin не меняет корректность маршрутизации, но может повысить потребление памяти: каждый direct writer потенциально встречает все (shard, partitionSlot), а каждый enabled writer — все partition slots. В результате на разных workers одновременно удерживается больше частично заполненных JDBC batches. При local partitioning это наиболее неблагоприятный вариант с точки зрения памяти.

Группировка по локальным партициям#

При distributed_write_local_partitioning=true для каждой строки вычисляется слот на основе PARTITION BY underlying-таблицы. Внутри каждого оператора записи JDBC-батчи для разных слотов формируются раздельно. Это уменьшает число партиций ClickHouse, затрагиваемых одним INSERT, и объем последующего фонового слияния данных.

Для вычисления слота поддерживаются:

  • целочисленная колонка или колонка DATE, непосредственно указанная в PARTITION BY;

  • toYYYYMM(column) и toYYYYMMDD(column) для DATE, TIMESTAMP(p) с точностью до 6 и TIMESTAMP(p) WITH TIME ZONE с точностью до 3;

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

Для каждой строки слот вычисляется по формуле:

partitionSlot = unsigned(partitionValue) % localPartitionCardinality

Параметр distributed_write_local_partition_cardinality задает количество слотов, а не физических партиций ClickHouse. Значения разных ключей партиционирования могут попасть в один слот. Увеличение значения параметра уменьшает вероятность таких совпадений, но увеличивает количество одновременно формируемых JDBC-батчей.

В режиме direct отдельные JDBC-батчи формируются для каждой пары (shard, partitionSlot), а в режиме enabled — для каждого partitionSlot. Частично заполненные батчи удерживаются в памяти. Поэтому слишком большое значение distributed_write_local_partition_cardinality, особенно в режиме shard или при use_preferred_write_partitioning=false, увеличивает потребление памяти и риск ее нехватки.

Поддерживаемые sharding expressions#

Имена функций в sharding expression чувствительны к регистру. CedrusData может вычислить шард для следующего набора выражений:

Sharding expression

Поддерживаемые типы колонки

Целочисленная колонка

TINYINT, SMALLINT, INTEGER, BIGINT

cityHash64(column), sipHash64(column), cityHash64(ifNull(column, N)), sipHash64(ifNull(column, N))

Целочисленные типы, VARCHAR, CHAR

toYYYYMM(column), toYYYYMMDD(column)

DATE

В выражениях с ifNull значение N должно быть целочисленным литералом.

Значение NULL без ifNull направляется в шард 0. Выражения с явным часовым поясом, хеши нескольких колонок, intHash64, арифметические выражения и другие нераспознанные формы не поддерживают вычисление шарда на стороне CedrusData.

Транзакционная и нетранзакционная запись#

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

  • disabled использует стандартный механизм временных таблиц JDBC-коннектора;

  • direct создает в кластере пустую staging-таблицу со схемой и определением движка целевой underlying-таблицы, записывает в нее данные, а затем переносит активные партиции в целевую таблицу;

  • enabled создает staging-таблицу для underlying-таблицы и связанную с ней staging-таблицу с движком Distributed. Перед переносом партиций коннектор выполняет flush staging-таблицы с движком Distributed.

При non_transactional_insert=true staging-таблицы и финализация не используются. Режим direct пишет сразу в реальные underlying-таблицы, а enabled и disabled — в исходную Distributed-таблицу. Ошибка может оставить в целевых таблицах только часть записываемых данных. Общая настройка нетранзакционного INSERT описана в разделе Неатомарный INSERT.

Для кластера с репликами underlying-таблица должна использовать движок семейства Replicated*. Коннектор отклоняет распределенную запись через staging-таблицы, если реплицируемый кластер ссылается на нереплицируемую underlying-таблицу.

Восстановление незавершенной записи#

Финализация распределенной записи состоит из нескольких операций. Если после переименования staging-таблицы перенос партиций завершился только на части шардов, коннектор сохраняет таблицу с суффиксом _moving_partitions. После устранения причины ошибки продолжите финализацию процедурой:

CALL example.system.resume_insert_commit(
    '<schema_name>',
    '<distributed_table_name>',
    '<moving_staging_table_name>');

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

Поведение CTAS#

Операция CREATE TABLE AS SELECT не использует распределенную маршрутизацию записи. Коннектор создает локальную таблицу поддерживаемого движка и записывает в нее через стандартный механизм JDBC. Параметры distributed_write, distributed_write_local_partitioning и use_preferred_write_partitioning не влияют на маршрутизацию CTAS. Параллелизм CTAS обеспечивают операторы записи CedrusData.

Прямое чтение#

При distributed_direct_read=true коннектор создает по одному split для основного адреса каждого шарда и читает underlying-таблицу непосредственно с этого адреса. Обычные и синтетические таблицы продолжают использовать стандартный механизм JDBC.

Для поддерживаемого детерминированного sharding expression коннектор также сообщает CedrusData распределение таблицы по шардам. Это позволяет планировщику учитывать его при построении плана. Для rand(), отсутствующего sharding key и неподдерживаемых выражений split по шардам создаются, но распределение таблицы планировщику не сообщается.

Требования и ограничения#

По умолчанию коннектор получает топологию кластера из таблицы ClickHouse system.clusters и использует основной адрес каждого шарда. Все CedrusData workers должны иметь сетевой доступ к этим адресам и портам.

При необходимости адреса шардов можно указать вручную:

clickhouse.distributed.cluster-shards-addresses=cluster1=host1:8123,cluster1=host2:8123

Для каждого шарда укажите адрес одной доступной реплики. При автоматическом обнаружении через system.clusters используется порт из clickhouse.distributed.shard-port.

Свойства таблицы#

CedrusData позволяет создавать таблицы в ClickHouse с помощью команды CREATE TABLE. Вы можете задать свойства таблицы ClickHouse с помощью ключевого слова WITH. Например:

CREATE TABLE default.trino_ck (
  id int NOT NULL,
  birthday DATE NOT NULL,
  name VARCHAR,
  age BIGINT,
  logdate DATE NOT NULL
)
WITH (
  engine = 'MergeTree',
  order_by = ARRAY['id', 'birthday'],
  partition_by = ARRAY['toYYYYMM(logdate)'],
  primary_key = ARRAY['id'],
  sample_by = 'id'
);

Поддерживаемые свойства:

Название

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

Описание

engine

Log

Тип движка таблицы. Поддерживаемые значения: Log, MergeTree. Движок ReplicatedMergeTree в настоящее время не поддерживается.

order_by

(отсутствует)

Только для MergeTree. Массив колонок или выражений для построения ключа сортировки (ORDER BY). Если значение не задано, будет использовано значение tuple().

partition_by

(отсутствует)

Только для MergeTree. Массив колонок или выражений для построения ключе партиционирования (PARTITION BY). Необязательный параметр.

primary_key

(отсутствует)

Только для MergeTree. Массив колонок или выражений для построения первичного ключа (PRIMARY KEY). Необязательный параметр.

sample_by

(отсутствует)

Только для MergeTree. Выражения для сэмплирования. Необязательный параметр.

Сопоставление типов#

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

Приведение типов ClickHouse к типам CedrusData#

Коннектор ClickHouse приводит типы ClickHouse к типам CedrusData согласно таблице ниже.

Приведение типов ClickHouse к типам CedrusData#

Тип ClickHouse

Тип CedrusData

Комментарий

Bool

BOOLEAN

Int8

TINYINT

TINYINT и INT1 — синонимы Int8

Int16

SMALLINT

SMALLINT и INT2 — синонимы Int16

Int32

INTEGER

INT, INT4 и INTEGER — синонимы Int32

Int64

BIGINT

BIGINT — синоним Int64

UInt8

SMALLINT

UInt16

INTEGER

UInt32

BIGINT

UInt64

DECIMAL(20,0)

Float32

REAL

FLOAT — синоним Float32

Float64

DOUBLE

DOUBLE — синоним Float64

Decimal

DECIMAL

FixedString

VARCHAR

Установка параметра каталога clickhouse.map-string-as-varchar в false меняет тип CedrusData на VARBINARY

String

VARCHAR

Установка параметра каталога clickhouse.map-string-as-varchar в false меняет тип CedrusData на VARBINARY

Date

DATE

DateTime[(timezone)]

TIMESTAMP(0) [WITH TIME ZONE]

IPv4

IPADDRESS

IPv6

IPADDRESS

Enum8

VARCHAR

Enum16

VARCHAR

UUID

UUID

Другие типы данных не поддерживаются.

Приведение типов CedrusData к типам ClickHouse#

Коннектор ClickHouse приводит типы CedrusData к типам ClickHouse согласно таблице ниже.

Приведение типов CedrusData к типам ClickHouse#

Тип CedrusData

Тип ClickHouse

Комментарий

BOOLEAN

Bool

TINYINT

Int8

TINYINT и INT1 — синонимы Int8

SMALLINT

Int16

SMALLINT и INT2 — синонимы Int16

INTEGER

Int32

INT, INT4 и INTEGER — синонимы Int32

BIGINT

Int64

BIGINT — синоним Int64

REAL

Float32

FLOAT — синоним Float32

DOUBLE

Float64

DOUBLE — синоним Float64

DECIMAL(p,s)

Decimal(p,s)

VARCHAR

String

CHAR

String

VARCHAR

String

Установка параметра каталога clickhouse.map-string-as-varchar в false меняет тип CedrusData на VARBINARY

DATE

Date

TIMESTAMP(0)

DateTime

UUID

UUID

Другие типы данных не поддерживаются.

Конфигурация сопоставления типов#

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

Название

Описание

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

unsupported-type-handling

Как обрабатывать колонки неподдерживаемых типов: IGNORE - не обрабатывать колонку; CONVERT_TO_VARCHAR - привести значение колонки к VARCHAR неограниченной длины. Параметр сессии: unsupported_type_handling.

IGNORE

jdbc-types-mapped-to-varchar

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

Поддержка SQL#

Коннектор поддерживает команды чтения и изменения данных и метаданных экземпляра ClickHouse. В дополнение к общим командам и командам чтения коннектор поддерживает следующие операции:

Неатомарный INSERT#

Коннектор поддерживает добавление записей в источник с помощью команды INSERT statements. По умолчанию CedrusData осуществляет запись данных, используя временную таблицу, что обеспечивает транзакционные гарантии: в источник будут записаны либо все данные, либо не будет записано ничего (в случае возникновения ошибки).

Вы можете осуществлять запись данных в таблицу источника напрямую, минуя временную таблицу. Для этого установите параметр конфигурации каталога insert.non-transactional-insert.enabled или свойство сессии non_transactional_insert в значение true. Изменение данного параметра может увеличить производительность записи, но может привести данные в источнике в неопределенное состояние при возникновении ошибки в момент записи. Например, если при вставке 10 записей в таблицу источника в середине процесса произошла ошибка, откат вставки уже сохраненных записей может оказаться невозможным, и после выполнения команды источник будет содержать только часть записей.

Ограничения ALTER SCHEMA#

Коннектор поддерживает переименование схемы с помощью команды ALTER SCHEMA RENAME. Команда ALTER SCHEMA SET AUTHORIZATION не поддерживается.

Процедуры#

system.flush_metadata_cache()#

Очистить кэш JDBC метаданных. Команда ниже очищает кэш метаданных всех схем в каталоге example.

USE example.example_schema;
CALL system.flush_metadata_cache();

system.execute('query')#

Процедура execute позволяет запустить SQL запрос к источнику в неизменном виде. Данная процедура полезна, когда вам требуется воспользоваться специфичным синтаксисом источника, который недоступен в CedrusData. В отличие от табличных функций query и raw_query данная процедура позволяет запускать SQL-запросы, который не возвращают записи (например, DML и DDL команды).

Запрос из процедуры будет исполнен в источнике как есть, без дополнительных проверок доступа к конкретным объектам источника на стороне CedrusData.

Пример использования процедуры для вызова команды ALTER TABLE на источнике:

USE example.example_schema;
CALL system.execute(query => 'ALTER TABLE your_table ALTER COLUMN your_column DROP DEFAULT');

Табличные функции#

Коннектор предоставляет ряд табличных функций для обработки данных ClickHouse.

query(varchar) -> table#

Табличная функция query позволяет запустить конкретный запрос к ClickHouse с использованием нативного синтаксиса ClickHouse. Запрос будет выполнен в ClickHouse как есть без каких-либо изменений. Данный функционал может быть полезен, если вам требуется задействовать специфичный функционал ClickHouse (например, нестандартный синтаксис или хинты или для ускорения запроса) или получить полный контроль над тем, какой запрос будет выполнен в ClickHouse.

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

Нативный запрос, переданный в источник, должен возвращать набор записей (result set). CedrusData не осуществляет проверку доступа текущего пользователя к объектам источника, задействованным в нативном запросе. Используйте нативные запросы только для чтения данных.

Пример использования табличной функции query для сканирования таблицы tpch.nation:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        *
      FROM
        tpch.nation'
    )
  );

Примечание

Полиморфные табличные функции не сохраняют оригинальный порядок записей в результате запроса. Есть переданный запрос содержит запрос выражение ORDER BY, функция может вернуть записи в ином порядке. Для восстановления требуемого порядка используйте ORDER BY в запросе CedrusData.

Производительность#

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

Пул соединений (connection pool)#

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

CedrusData создает по одному пулу соединений на каждого пользователя, который подключается к источнику:

  • Если вы аутентифицируетесь в источнике от имени общего системного пользователя, будет создан один пул.

  • Если вы используете Аутентификация в коннекторах от имени текущего пользователя, то будет создано по одному пулу на каждого активного пользователя CedrusData, но не более cedrusdata.jdbc.connection-pool.max-users. Создание большого количества соединений может негативно сказать на источнике. Мы рекомендуем вам провести нагрузочное тестирование, чтобы убедиться, что преимущества пула соединений перевешивают риски, при использовании совместно с аутентификацией в источнике от имени текущего пользователя.

Каждый пул может содержать до cedrusdata.jdbc.connection-pool.max-user-connections соединений.

Название

Описание

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

cedrusdata.jdbc.connection-pool.enabled

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

false

cedrusdata.jdbc.connection-pool.max-users

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

100

cedrusdata.jdbc.connection-pool.max-user-connections

Максимальное количество подключений к источнику в рамках одного пула.

Равно количеству процессорных ядер

cedrusdata.jdbc.connection-pool.user-ttl

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

5m (пять минут)

cedrusdata.jdbc.connection-pool.connection-ttl

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

5m (пять минут)

Статистики таблиц#

ClickHouse коннектор может использовать статистики таблиц (row count) для cost-based оптимизации запросов.

Сбор статистик осуществляет экземпляр ClickHouse, после чего передает их CedrusData. Используйте команду ANALYZE для сбора статистик таблиц.

ANALYZE table_schema.table_name;

Pushdown#

Коннектор поддерживает pushdown различных выражений, включая предикаты и проекции, агрегации, JOIN, LIMIT.

В общем случае pushdown возможен для типов данных BOOLEAN, TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, DOUBLE, CHAR, VARCHAR, TIMESTAMP и TIMESTAMP WITH TIME ZONE. Для некоторых операций pushdown разрешен только для определенных типов данных.

Используйте следующие параметры конфигурации для включения и выключения pushdown некоторых типов данных.

Управление pushdown типов данных#

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

Свойство сессии

Описание

cedrusdata.clickhouse.pushdown.boolean-type

cedrusdata_pushdown_boolean_type

Включает pushdown для типа BOOLEAN. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.decimal-type

cedrusdata_pushdown_decimal_type

Включает pushdown для типа DECIMAL. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.real-type

cedrusdata_pushdown_real_type

Включает pushdown для типа REAL. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.double-type

cedrusdata_pushdown_double_type

Включает pushdown для типа DOUBLE. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.date-type

cedrusdata_pushdown_date_type

Включает pushdown для типа DATE. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.timestamp-type

cedrusdata_pushdown_timestamp_type

Включает pushdown для типа TIMESTAMP. Значение по умолчанию: true.

Pushdown выражений#

Коннектор поддерживает pushdown следующих выражений в качестве предикатов (выражения WHERE, HAVING) и проекций (функции в выражении SELECT):

  • Константы

  • Колонки таблицы

  • Логические операторы AND, OR, NOT

  • Оператор IS NULL

  • Оператор LIKE

  • Операторы сравнения =, !=, >, >=, <, <= для типов TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, DOUBLE, CHAR, VARCHAR, TIMESTAMP

  • Оператор IN для типов BOOLEAN, TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, DOUBLE, CHAR, VARCHAR, TIMESTAMP

  • Арифметические операторы +, -, /, % для типов TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, DOUBLE

  • Функция CAST

  • Функция NULL IF

  • Строковые функции CONCAT, LENGTH, LOWER, LPAD, LTRIM, POSITION, REPLACE, REVERSE, RPAD, RTRIM, STRPOS, SUBSTRING, TRANSLATE, TRIM, UPPER

  • Математические функции ABS, CBRT, CEILING, DEGREES, EXP, FLOOR, LOG, LOG2, LOG10, POW, RADIANS, RAND, ROUND, SIGN, SQRT, TRUNCATE

  • Функции YEAR, QUARTER, MONTH, WEEK, DAY, DAY_OF_WEEK, DAY_OF_YEAR, HOUR, MINUTE, SECOND

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

Управление pushdown выражений#

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

Свойство сессии

Описание

cedrusdata.clickhouse.pushdown.cast-function

cedrusdata_pushdown_cast_function

Включает pushdown функции CAST. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.concat-function

cedrusdata_pushdown_concat_function

Включает pushdown функции CONCAT. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.length-function

cedrusdata_pushdown_length_function

Включает pushdown функции LENGTH. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.lower-function

cedrusdata_pushdown_lower_function

Включает pushdown функции LOWER. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.replace-function

cedrusdata_pushdown_replace_function

Включает pushdown функции REPLACE. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.reverse-function

cedrusdata_pushdown_reverse_function

Включает pushdown функции REVERSE. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.substring-function

cedrusdata_pushdown_substring_function

Включает pushdown функции SUBSTRING. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.translate-function

cedrusdata_pushdown_translate_function

Включает pushdown функции TRANSLATE. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.upper-function

cedrusdata_pushdown_upper_function

Включает pushdown функции UPPER. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.pad-function

cedrusdata_pushdown_pad_function

Включает pushdown функций LPAD и RPAD. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.strpos-function

cedrusdata_pushdown_strpos_function

Включает pushdown функций STRPOS и POSITION. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.trim-function

cedrusdata_pushdown_trim_function

Включает pushdown функций TRIM, LTRIM и RTRIM. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.trim-function.default-characters

cedrusdata_pushdown_trim_function_default_characters

Какие символы подлежат удалению, когда функция TRIM вызвана без явного указания удаляемого символа. Значение по умолчанию: (удалять пробел).

cedrusdata.clickhouse.pushdown.abs-function

cedrusdata_pushdown_abs_function

Включает pushdown функции ABS. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.cbrt-function

cedrusdata_pushdown_cbrt_function

Включает pushdown функции CBRT. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.ceiling-function

cedrusdata_pushdown_ceiling_function

Включает pushdown функции CEILING. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.degrees-function

cedrusdata_pushdown_degrees_function

Включает pushdown функции DEGREES. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.exp-function

cedrusdata_pushdown_exp_function

Включает pushdown функции EXP. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.floor-function

cedrusdata_pushdown_floor_function

Включает pushdown функции FLOOR. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.log-function

cedrusdata_pushdown_log_function

Включает pushdown функций LN, LOG2 и LOG10. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.pow-function

cedrusdata_pushdown_pow_function

Включает pushdown функции POW. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.radians-function

cedrusdata_pushdown_radians_function

Включает pushdown функции RADIANS. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.rand-function

cedrusdata_pushdown_rand_function

Включает pushdown функции RAND. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.round-function

cedrusdata_pushdown_round_function

Включает pushdown функции ROUND. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.sign-function

cedrusdata_pushdown_sign_function

Включает pushdown функции SIGN. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.sqrt-function

cedrusdata_pushdown_sqrt_function

Включает pushdown функции SQRT. Значение по умолчанию: true.

cedrusdata.clickhouse.pushdown.truncate-function

cedrusdata_pushdown_truncate_function

Включает pushdown функции TRUNCATE. Значение по умолчанию: true.

Pushdown агрегаций#

Коннектор поддерживает pushdown агрегатных функций:

Pushdown других операций#

Коннектор поддерживает pushdown следующих операций: