Коннектор ClickHouse

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

Требования

Для подключения к серверу ClickHouse требуется:

• ClickHouse версии 25.3 или выше либо Altinity версии 22.8 или выше.

• Сетевой доступ от координатора и рабочих узлов Trino к серверу ClickHouse. Порт по умолчанию — 8123.

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

Коннектор может запрашивать сервер ClickHouse. Создайте файл свойств каталога, который указывает коннектор ClickHouse, задав connector.name равным clickhouse.

Например, создайте файл etc/catalog/example.properties. Замените свойства подключения значениями, подходящими для вашей среды:

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

connection-url определяет сведения о подключении и параметры, передаваемые драйверу ClickHouse JDBC. Поддерживаемые параметры URL доступны в конфигурации драйвера ClickHouse JDBC.

connection-user и connection-password обычно обязательны и определяют учетные данные пользователя для подключения, часто сервисного пользователя. Можно использовать секреты, чтобы не хранить фактические значения в файлах свойств каталога.

Безопасность подключения

Если в источнике данных настроен TLS с глобально доверенным сертификатом, можно включить TLS между кластером и источником данных, добавив параметр в строку подключения JDBC, заданную свойством конфигурации каталога connection-url.

Например, в версии 2.6.4 драйвера ClickHouse JDBC включите TLS, добавив параметр ssl=true к свойству конфигурации connection-url:

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

Дополнительные сведения о параметрах конфигурации TLS см. в документации драйвера ClickHouse JDBC.

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

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

• непосредственно в файле конфигурации коннектора;

• в отдельном файле свойств;

• в файле хранилища ключей;

• как дополнительные учетные данные, заданные при подключении к Trino.

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

В следующей таблице описаны свойства конфигурации для учетных данных подключения:

Имя свойства	Описание
credential-provider.type	Тип поставщика учетных данных. Должен быть одним из INLINE, FILE или KEYSTORE; по умолчанию — INLINE.
connection-user	Имя пользователя подключения.
connection-password	Пароль подключения.
user-credential-name	Имя свойства дополнительных учетных данных, значение которого используется как имя пользователя. См. extraCredentials в справочнике параметров.
password-credential-name	Имя свойства дополнительных учетных данных, значение которого используется как пароль.
connection-credential-file	Расположение файла свойств, в котором находятся учетные данные. Он должен содержать свойства connection-user и connection-password.
keystore-file-path	Расположение файла Java Keystore, из которого считываются учетные данные.
keystore-type	Формат файла хранилища ключей, например JKS или PEM.
keystore-password	Пароль для хранилища ключей.
keystore-user-credential-name	Имя сущности хранилища ключей, используемой как имя пользователя.
keystore-user-credential-password	Пароль для сущности хранилища ключей с именем пользователя.
keystore-password-credential-name	Имя сущности хранилища ключей, используемой как пароль.
keystore-password-credential-password	Пароль для сущности хранилища ключей с паролем.

Несколько серверов ClickHouse

Если у вас несколько серверов ClickHouse, необходимо настроить отдельный каталог для каждого сервера. Чтобы добавить еще один каталог:

• Добавьте еще один файл свойств в etc/catalog.

• Сохраните его с другим именем, заканчивающимся на .properties.

Например, если назвать файл свойств sales.properties, Trino использует настроенный коннектор для создания каталога с именем sales.

Общие свойства конфигурации

В следующей таблице описаны общие свойства конфигурации каталога для коннектора:

Имя свойства	Описание
case-insensitive-name-matching	Поддержка имен схем и таблиц без учета регистра. По умолчанию — false.
case-insensitive-name-matching.cache-ttl	Длительность, в течение которой кэшируются имена схем и таблиц при сопоставлении без учета регистра. По умолчанию — 1m.
case-insensitive-name-matching.config-file	Путь к конфигурационному файлу сопоставления имен в формате JSON, который позволяет Trino различать схемы и таблицы с похожими именами в разных регистрах. По умолчанию — null.
case-insensitive-name-matching.config-file.refresh-period	Частота, с которой Trino проверяет конфигурационный файл сопоставления имен на изменения. Значение длительности по умолчанию — 0s (обновление отключено).
metadata.cache-ttl	Длительность, в течение которой кэшируются метаданные, включая статистику таблиц и столбцов. По умолчанию — 0s (кэширование отключено).
metadata.cache-missing	Кэшировать факт недоступности метаданных, включая статистику таблиц и столбцов. По умолчанию — false.
metadata.schemas.cache-ttl	Длительность, в течение которой кэшируются метаданные схем. По умолчанию равно значению metadata.cache-ttl.
metadata.tables.cache-ttl	Длительность, в течение которой кэшируются метаданные таблиц. По умолчанию равно значению metadata.cache-ttl.
metadata.statistics.cache-ttl	Длительность, в течение которой кэшируется статистика таблиц. По умолчанию равно значению metadata.cache-ttl.
metadata.cache-maximum-size	Максимальное число объектов, хранящихся в кэше метаданных. По умолчанию — 10000.
write.batch-size	Максимальное число операторов в пакетном выполнении. Не меняйте это значение относительно значения по умолчанию. Нестандартные значения могут отрицательно повлиять на производительность. По умолчанию — 1000.
dynamic-filtering.enabled	Проталкивать динамические фильтры в JDBC-запросы. По умолчанию — true.
dynamic-filtering.wait-timeout	Максимальная длительность, в течение которой Trino ожидает сбора динамических фильтров со стороны построения соединения перед запуском JDBC-запроса. Большой тайм-аут потенциально может дать более подробные динамические фильтры, но также может увеличить задержку некоторых запросов. По умолчанию — 20s.

Добавление метаданных запроса

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

• $QUERY_ID: идентификатор запроса.

• $USER: имя пользователя, отправившего запрос в Trino.

• $SOURCE: идентификатор клиентского инструмента, использованного для отправки запроса, например trino-cli.

• $TRACE_TOKEN: токен трассировки, настроенный в клиентском инструменте.

Комментарий может предоставить больше контекста о запросе. Эта дополнительная информация доступна в журналах источника данных. Чтобы включить в комментарий переменные окружения из кластера Trino, используйте синтаксис ${ENV:VARIABLE-NAME}.

Следующий пример задает простой комментарий, идентифицирующий каждый запрос, отправленный Trino:

query.comment-format=Query sent by Trino.

С такой конфигурацией запрос вроде SELECT * FROM example_table; отправляется источнику данных с добавленным комментарием:

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, источнику данных отправляется следующая строка комментария:

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

Note

Некоторые настройки драйвера JDBC и конфигурации журналирования могут привести к удалению комментария.

Порог компактирования домена

Проталкивание большого списка предикатов в источник данных может ухудшить производительность. По умолчанию Trino компактирует большие предикаты в более простой предикат диапазона, чтобы сохранить баланс между производительностью и проталкиванием предикатов. При необходимости порог такого компактирования можно увеличить, чтобы повысить производительность, когда источник данных способен эффективно использовать большие предикаты. Увеличение этого порога может улучшить проталкивание больших динамических фильтров. Свойство конфигурации каталога domain-compaction-threshold или свойство сеанса каталога domain_compaction_threshold можно использовать для изменения значения по умолчанию 1000 для этого порога.

Сопоставление без учета регистра

Когда case-insensitive-name-matching установлено в true, Trino может запрашивать схемы и таблицы с именами не только в нижнем регистре, поддерживая сопоставление имени в нижнем регистре с фактическим именем в удаленной системе. Однако если две схемы и/или таблицы имеют имена, различающиеся только регистром, например “customers” и “Customers”, Trino не сможет запрашивать их из-за неоднозначности.

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

{
  "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"
    }]
}

Запросы к одной из таблиц или схем, заданных в атрибутах mapping, выполняются к соответствующей удаленной сущности. Например, запрос к таблицам в схеме case_insensitive_1 перенаправляется в схему CaseSensitiveName, а запрос к case_insensitive_2 — в схему cASEsENSITIVEnAME.

На уровне сопоставления таблиц запрос к case_insensitive_1.table_1 в приведенной выше конфигурации перенаправляется к CaseSensitiveName.tablex, а запрос к case_insensitive_1.table_2 — к CaseSensitiveName.TABLEX.

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

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

Запросы к ClickHouse

Коннектор ClickHouse предоставляет схему для каждой базы данных ClickHouse. Выполните SHOW SCHEMAS, чтобы увидеть доступные базы данных ClickHouse:

SHOW SCHEMAS FROM example;

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

SHOW TABLES FROM example.web;

Выполните DESCRIBE или SHOW COLUMNS, чтобы вывести столбцы таблицы clicks в базе данных web:

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

Выполните SELECT, чтобы получить доступ к таблице clicks в базе данных web:

SELECT * FROM example.web.clicks;

Note

Если для файла свойств каталога использовано другое имя, в приведенных выше примерах используйте это имя каталога вместо example.

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

Пример использования свойств таблицы:

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

Поддерживаются следующие свойства таблиц ClickHouse из документации MergeTree.

Имя свойства	Значение по умолчанию	Описание
engine	Log	Имя и параметры движка.
order_by	(нет)	Массив столбцов или выражений, объединяемых для создания ключа сортировки. Если order_by не указан, по умолчанию используется tuple().
partition_by	(нет)	Массив столбцов или выражений, используемых как вложенные ключи секционирования. Необязательно.
primary_key	(нет)	Массив столбцов или выражений, объединяемых для создания первичного ключа. Необязательно.
sample_by	(нет)	Выражение, используемое для семплирования. Необязательно.

В настоящее время коннектор поддерживает только движки таблиц Log и MergeTree в операторе создания таблицы. Движок ReplicatedMergeTree пока не поддерживается.

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

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

Сопоставление типов ClickHouse с типами Trino

Коннектор сопоставляет типы ClickHouse с соответствующими типами Trino согласно следующей таблице:

Сопоставление типов ClickHouse с типами Trino

Тип ClickHouse	Тип Trino	Примечания
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	VARBINARY	Включение свойства конфигурации clickhouse.map-string-as-varchar меняет сопоставление на VARCHAR
String	VARBINARY	Включение свойства конфигурации clickhouse.map-string-as-varchar меняет сопоставление на VARCHAR
Date	DATE
DateTime[(timezone)]	TIMESTAMP(0) [WITH TIME ZONE]
IPv4	IPADDRESS
IPv6	IPADDRESS
Enum8	VARCHAR
Enum16	VARCHAR
UUID	UUID

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

Сопоставление типов Trino с типами ClickHouse

Коннектор сопоставляет типы Trino с соответствующими типами ClickHouse согласно следующей таблице:

Сопоставление типов Trino с типами ClickHouse

Тип Trino	Тип 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
VARBINARY	String	Включение свойства конфигурации clickhouse.map-string-as-varchar меняет сопоставление на VARCHAR
DATE	Date
TIMESTAMP(0)	DateTime
UUID	UUID

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

Свойства конфигурации сопоставления типов

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

Имя свойства	Описание	Значение по умолчанию
unsupported-type-handling	Настраивает обработку неподдерживаемых типов данных столбцов: IGNORE — столбец недоступен. CONVERT_TO_VARCHAR — столбец преобразуется в неограниченный VARCHAR. Соответствующее свойство сеанса каталога — unsupported_type_handling.	IGNORE
jdbc-types-mapped-to-varchar	Позволяет принудительно сопоставлять списки типов данных, разделенные запятыми, с неограниченным VARCHAR.

Поддержка SQL

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

• INSERT, см. также Нетранзакционный INSERT

• TRUNCATE

• Управление схемами и таблицами, см. также:

  • ALTER SCHEMA limitation

• Процедуры

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

Нетранзакционный INSERT

Коннектор поддерживает добавление строк с помощью операторов INSERT. По умолчанию вставка данных выполняется путем записи данных во временную таблицу. Этот шаг можно пропустить, чтобы повысить производительность и писать напрямую в целевую таблицу. Установите свойство каталога insert.non-transactional-insert.enabled или соответствующее свойство сеанса каталога non_transactional_insert в true.

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

ALTER SCHEMA limitation

The connector supports renaming a schema with the ALTER SCHEMA RENAME statement. ALTER SCHEMA SET AUTHORIZATION is not supported.

Процедуры

system.flush_metadata_cache()

Очищает кэши метаданных JDBC. Например, следующий системный вызов очищает кэши метаданных для всех схем в каталоге example:

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

system.execute('query')

Процедура execute позволяет выполнить запрос напрямую в базовом источнике данных. Запрос должен использовать поддерживаемый синтаксис подключенного источника данных. Используйте процедуру для доступа к возможностям, которые недоступны в Trino, или для выполнения запросов, которые не возвращают набор результатов и поэтому не могут использоваться с транзитной табличной функцией query или raw_query. Типичные случаи применения — операторы, создающие или изменяющие объекты и требующие нативных возможностей, таких как ограничения, значения по умолчанию, автоматическое создание идентификаторов или индексы. Запросы также могут вызывать операторы, которые вставляют, обновляют или удаляют данные и не возвращают данных в результате.

Текст запроса не разбирается Trino, а только передается дальше, поэтому он подчиняется только правилам безопасности и контроля доступа базового источника данных.

В следующем примере текущая база данных устанавливается в example_schema каталога example. Затем в этой схеме вызывается процедура, чтобы удалить значение по умолчанию из your_column в таблице your_table с помощью стандартного SQL-синтаксиса в значении параметра query:

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. Это может быть полезно для доступа к нативным возможностям, недоступным в Trino, или для повышения производительности запросов в ситуациях, когда нативное выполнение запроса может быть быстрее.

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

В качестве простого примера запросите каталог example и выберите всю таблицу:

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

Note

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

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

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

Проталкивание

Коннектор поддерживает проталкивание для ряда операций:

• Проталкивание limit

Проталкивание агрегаций для следующих функций:

• avg()

• count()

• max()

• min()

• sum()

Note

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

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

Коннектор не поддерживает проталкивание предикатов неравенства, таких как !=, и предикатов диапазона, таких как > или BETWEEN, для столбцов с символьными строковыми типами, например CHAR или VARCHAR. Предикаты равенства, такие как IN или =, для столбцов с символьными строковыми типами проталкиваются. Это обеспечивает корректность результатов, поскольку удаленный источник данных может сортировать строки иначе, чем Trino.

В следующем примере предикат первого и второго запроса не проталкивается, поскольку name — столбец типа VARCHAR, а > и != являются соответственно предикатами диапазона и неравенства. Последний запрос проталкивается.

-- Не проталкивается
SELECT * FROM nation WHERE name > 'CANADA';
SELECT * FROM nation WHERE name != 'CANADA';
-- Проталкивается
SELECT * FROM nation WHERE name = 'CANADA';