ClickHouse коннектор#
Примечание
Ниже приведена оригинальная документация Trino. Скоро мы ее переведем на русский язык и дополним полезными примерами.
The ClickHouse connector allows querying tables in an external ClickHouse server. This can be used to query data in the databases on that server, or combine it with other data from different catalogs accessing ClickHouse or any other supported data source.
Requirements#
To connect to a ClickHouse server, you need:
ClickHouse (version 21.8 or higher) or Altinity (version 20.8 or higher).
Network access from the Trino coordinator and workers to the ClickHouse server. Port 8123 is the default port.
Configuration#
The connector can query a ClickHouse server. Create a catalog properties file
that specifies the ClickHouse connector by setting the connector.name
to
clickhouse
.
For example, create the file etc/catalog/example.properties
. Replace the
connection properties as appropriate for your setup:
connector.name=clickhouse
connection-url=jdbc:clickhouse://host1:8123/
connection-user=exampleuser
connection-password=examplepassword
The connection-url
defines the connection information and parameters to pass
to the ClickHouse JDBC driver. The supported parameters for the URL are
available in the ClickHouse JDBC driver configuration.
The connection-user
and connection-password
are typically required and
determine the user credentials for the connection, often a service user. You can
use secrets to avoid actual values in the catalog
properties files.
Connection security#
If you have TLS configured with a globally-trusted certificate installed on your
data source, you can enable TLS between your cluster and the data
source by appending a parameter to the JDBC connection string set in the
connection-url
catalog configuration property.
For example, with version 2.6.4 of the ClickHouse JDBC driver, enable TLS by
appending the ssl=true
parameter to the connection-url
configuration
property:
connection-url=jdbc:clickhouse://host1:8443/?ssl=true
For more information on TLS configuration options, see the Clickhouse JDBC driver documentation
Аутентификация в источнике данных#
Вы можете предоставить имя пользователя и пароль для подключения к источнику данных несколькими способами:
INLINE
- в файле конфигурации каталога (в том числе, используя секреты, чтобы не хранить значения в открытом виде).FILE
- в отдельном properties файле.KEYSTORE
- в зашифрованном keystore файле.Из extra credentials клиента CedrusData.
Название |
Описание |
---|---|
|
Тип credential provider. Допустимые значения: |
|
Имя пользователя для подключения к источнику. Используется при |
|
Пароль для подключения к источнику. Используется при |
|
Путь к properties файлу, содержащему параметры |
|
Путь к keystore файлу, из которого следует прочитать имя пользователя и пароль. Используется при |
|
Тип keystore файла. Например, |
|
Пароль к keystore файлу. |
|
Имя keystore entity, содержащей имя пользователя для подключения к источнику. |
|
Пароль к keystore entity, содержащей имя пользователя для подключения к источнику |
|
Имя keystore entity, содержащей пароль для подключения к источнику. |
|
Пароль к keystore entity, содержащей пароль для подключения к источнику. |
|
Имя параметра extra credentials, значение которого следует использовать в качестве имени пользователя. См. |
|
Имя параметра extra credentials, значение которого следует использовать в качестве пароля. См. |
Аутентификация в источнике данных от имени текущего пользователя#
В дополнение к описанным выше способам аутентификации, 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 другие параметры аутентификации коннектора будут проигнорированы.
Multiple ClickHouse servers#
If you have multiple ClickHouse servers you need to configure one catalog for each server. To add another catalog:
Add another properties file to
etc/catalog
Save it with a different name that ends in
.properties
For example, if you name the property file sales.properties
, Trino uses the
configured connector to create a catalog named sales
.
Общие параметры конфигурации#
Название |
Описание |
Значение по умолчанию |
---|---|---|
|
Включить поддержку case insensitive идентификаторов. |
|
|
Время жизни закэшированных метаданных о case insensitive идентификаторах. Значение имеет тип duration. |
|
|
Путь к файлу конфигурации в формате JSON, который позволяет разрешать конфликты имен между case insensitive схемами и таблицами. |
|
|
Частота проверки обновлений файла |
|
|
Время жизни закэшированных метаданных (дескрипторы таблицы и колонок, статистики). Положительное значение включает кэширование. Значение имеет тип duration. |
|
|
Кэшировать ли информацию о том, что для используемых таблиц и колонок отсутствуют статистики. Включение данного
параметра может ускорить планирование некоторых запросов. Однако, если информация об отсутствии статистик для
конкретного объекта СУБД закэширована, но статистики стали доступны позднее (например, была запущена
команда |
|
|
Время жизни закэшированных имен схем. Положительное значение включает кэширование. Допустимо только, если
параметр |
|
|
Время жизни закэшированных имен таблиц. Положительное значение включает кэширование. Допустимо только, если
параметр |
|
|
Время жизни закэшированных статистик. Положительное значение включает кэширование. Допустимо только, если
параметр |
|
|
Максимальное количество объектов, хранящихся в metadata cache. |
|
|
Максимальное количество команд в batch операциях записи данных. Изменение данного параметра не рекомендовано, так как оно может негативно сказаться на производительности. |
|
|
Использовать ли динамические фильтры при работе с JDBC источником. |
|
|
Максимальное время ожидания готовности динамических фильтров с build стороны оператора join перед запуском JDBC запроса к источнику. Увеличение таймаута может позволить CedrusData выполнить запрос к источнику с более селективными фильтрами, но в то же время может увеличить latency некоторых запросов. Значение имеет тип duration. |
|
Добавление комментариев к 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
.
Процедуры#
system.flush_metadata_cache()
Очистить кэш JDBC метаданных. Команда ниже очищает кэш метаданных всех схем в каталоге
example
.USE example.example_schema; CALL system.flush_metadata_cache();
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-mapping.refresh-period
, который определяет частоту повторного чтения данного
файла.
case-insensitive-name-mapping.refresh-period=30s
Неатомарный INSERT#
Коннектор поддерживает добавление записей в источник с помощью команды INSERT statements. По умолчанию CedrusData осуществляет запись данных, используя временную таблицу, что обеспечивает транзакционные гарантии: в источник будут записаны либо все данные, либо не будет записано ничего (в случае возникновения ошибки).
Вы можете осуществлять запись данных в таблицу источника напрямую, минуя временную таблицу.
Для этого установите параметр конфигурации каталога insert.non-transactional-insert.enabled
или свойство сессии non_transactional_insert
в значение true
.
Изменение данного параметра может увеличить производительность записи, но может привести
данные в источнике в неопределенное состояние при возникновении ошибки в момент записи.
Например, если при вставке 10 записей в таблицу источника в середине процесса произошла ошибка,
откат вставки уже сохраненных записей может оказаться невозможным, и после выполнения команды
источник будет содержать только часть записей.
Querying ClickHouse#
The ClickHouse connector provides a schema for every ClickHouse database.
Run SHOW SCHEMAS
to see the available ClickHouse databases:
SHOW SCHEMAS FROM example;
If you have a ClickHouse database named web
, run SHOW TABLES
to view the
tables in this database:
SHOW TABLES FROM example.web;
Run DESCRIBE
or SHOW COLUMNS
to list the columns in the clicks
table
in the web
databases:
DESCRIBE example.web.clicks;
SHOW COLUMNS FROM example.web.clicks;
Run SELECT
to access the clicks
table in the web
database:
SELECT * FROM example.web.clicks;
Примечание
If you used a different name for your catalog properties file, use
that catalog name instead of example
in the above examples.
Table properties#
Table property usage 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'
);
The following are supported ClickHouse table properties from https://clickhouse.tech/docs/en/engines/table-engines/mergetree-family/mergetree/
Property name |
Default value |
Description |
---|---|---|
|
|
Name and parameters of the engine. |
|
(none) |
Array of columns or expressions to concatenate to create the sorting key. Required if |
|
(none) |
Array of columns or expressions to use as nested partition keys. Optional. |
|
(none) |
Array of columns or expressions to concatenate to create the primary key. Optional. |
|
(none) |
An expression to use for sampling. Optional. |
Currently the connector only supports Log
and MergeTree
table engines
in create table statement. ReplicatedMergeTree
engine is not yet supported.
Type mapping#
Because Trino and ClickHouse each support types that the other does not, this connector modifies some types when reading or writing data. Data types may not map the same way in both directions between Trino and the data source. Refer to the following sections for type mapping in each direction.
ClickHouse type to Trino type mapping#
The connector maps ClickHouse types to the corresponding Trino types according to the following table:
ClickHouse type |
Trino type |
Notes |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Enabling |
|
|
Enabling |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
No other types are supported.
Trino type to ClickHouse type mapping#
The connector maps Trino types to the corresponding ClickHouse types according to the following table:
Trino type |
ClickHouse type |
Notes |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Enabling |
|
|
|
|
|
|
|
|
No other types are supported.
Конфигурация сопоставления типов#
Следующие параметры конфигурации могут быть использованы для изменения логики приведения типов.
Название |
Описание |
Значение по умолчанию |
---|---|---|
|
Как обрабатывать колонки неподдерживаемых типов: |
|
|
Список типов данных источника, которые должны быть принудительно приведены к |
SQL support#
The connector provides read and write access to data and metadata in a ClickHouse catalog. In addition to the globally available and read operation statements, the connector supports the following features:
ALTER SCHEMA#
Коннектор поддерживает переименование схемы с помощью команды ALTER SCHEMA RENAME
.
Команда ALTER SCHEMA SET AUTHORIZATION
не поддерживается.
Performance#
The connector includes a number of performance improvements, detailed in the following sections.
Пул соединений (connection pool)#
Коннектор поддерживает работу через пул соединений с помощью библиотеки HikariCP. В ряде случаев использование пула соединений может ускорить запросы к источнику данных.
CedrusData создает по одному пулу соединений на каждого пользователя, который подключается к источнику:
Если вы аутентифицируетесь в источнике от имени общего системного пользователя, будет создан один пул.
Если вы используете Аутентификация в коннекторах от имени текущего пользователя, то будет создано по одному пулу на каждого активного пользователя CedrusData, но не более
cedrusdata.jdbc.connection-pool.max-users
. Создание большого количества соединений может негативно сказать на источнике. Мы рекомендуем вам провести нагрузочное тестирование, чтобы убедиться, что преимущества пула соединений перевешивают риски, при использовании совместно с аутентификацией в источнике от имени текущего пользователя.
Каждый пул может содержать до cedrusdata.jdbc.connection-pool.max-user-connections
соединений.
Название |
Описание |
Значение по умолчанию |
---|---|---|
|
Использовать ли пул соединений при подключении к источнику. |
|
|
Максимальное количество пулов соединений, которое может быть создано. Если необходимо создать новый пул для пользователя, но общее количество пулов достигло предела, будет закрыт один из давно неиспользуемых пулов. Значение данного параметра не имеет значения, если вы аутентифицируетесь в источнике от имени общего системного пользователя, так как в этом случае всегда будет использован ровно только пул. |
|
|
Максимальное количество подключений к источнику в рамках одного пула. |
Равно количеству процессорных ядер |
|
Как долго удерживать пул пользователя открытым в случае отсутствия активности последнего. |
|
|
Как долго удерживать соединение открытым в случае отсутствия активности. |
|
Pushdown#
Коннектор поддерживает pushdown следующих операций:
Коннектор поддерживает pushdown агрегатных функций:
Примечание
Коннектор осуществляет pushdown для улучшения производительности запросов. Коннектор не будет делать pushdown конкретной операции, если это может привести к некорректным результатам. Таким образом коннектор предпочитает корректность производительности. В некоторых случаях коннекторы могут предоставлять дополнительные параметры конфигурации, которые разрешают pushdown небезопасных операций, но только при явном указании соответствующего параметра пользователем.
Поддержка predicate pushdown#
Коннектор поддерживает pushdown выражений =
, !=
, >
, >=
, <
, <=
в качестве предикатов (выражения WHERE
, HAVING
).
Одним из аргументов выражения должна быть колонка таблицы типа BOOLEAN
, TINYINT
, SMALLINT
, INTEGER
, BIGINT
, DOUBLE
, CHAR
, VARCHAR
, TIMESTAMP
или TIMESTAMP WITH TIME ZONE
.
Вторым аргументом должна быть константа.
Используйте следующие параметры конфигурации и свойства сессии для тонкой настройки pushdown выражений.
Параметр конфигурации |
Свойство сессии |
Описание |
---|---|---|
|
|
Включает pushdown предикатов |