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.

Требования#

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.

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

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.

Примечание

Trino uses the new ClickHouse driver(com.clickhouse.jdbc.ClickHouseDriver) by default, but the new driver only supports ClickHouse server with version >= 20.7.

For compatibility with ClickHouse server versions < 20.7, you can temporarily continue to use the old ClickHouse driver(ru.yandex.clickhouse.ClickHouseDriver) by adding the following catalog property: clickhouse.legacy-driver=true.

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.

The following table describes configuration properties for connection credentials:

Property name

Description

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 в разделе Параметры подключения.

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-name-matching

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

false

case-insensitive-name-matching.cache-ttl

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

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 (refresh disabled)

metadata.cache-ttl

Время жизни закэшированных метаданных. Положительное значение включает кэширование.

0 (caching disabled)

metadata.cache-missing

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

false

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 некоторых запросов.

20s

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 catalog session property.

Процедуры#

  • 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

engine

Log

Name and parameters of the engine.

order_by

(none)

Array of columns or expressions to concatenate to create the sorting key. Required if engine is MergeTree.

partition_by

(none)

Array of columns or expressions to use as nested partition keys. Optional.

primary_key

(none)

Array of columns or expressions to concatenate to create the primary key. Optional.

sample_by

(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 to Trino type mapping#

ClickHouse type

Trino type

Notes

Int8

TINYINT

TINYINT, BOOL, BOOLEAN, and INT1 are aliases of Int8

Int16

SMALLINT

SMALLINT and INT2 are aliases of Int16

Int32

INTEGER

INT, INT4, and INTEGER are aliases of Int32

Int64

BIGINT

BIGINT is an alias of Int64

UInt8

SMALLINT

UInt16

INTEGER

UInt32

BIGINT

UInt64

DECIMAL(20,0)

Float32

REAL

FLOAT is an alias of Float32

Float64

DOUBLE

DOUBLE is an alias of Float64

Decimal

DECIMAL

FixedString

VARBINARY

Enabling clickhouse.map-string-as-varchar config property changes the mapping to VARCHAR

String

VARBINARY

Enabling clickhouse.map-string-as-varchar config property changes the mapping to VARCHAR

Date

DATE

DateTime[(timezone)]

TIMESTAMP(0) [WITH TIME ZONE]

IPv4

IPADDRESS

IPv6

IPADDRESS

Enum8

VARCHAR

Enum16

VARCHAR

UUID

UUID

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 to ClickHouse type mapping#

Trino type

ClickHouse type

Notes

BOOLEAN

UInt8

TINYINT

Int8

TINYINT, BOOL, BOOLEAN, and INT1 are aliases of Int8

SMALLINT

Int16

SMALLINT and INT2 are aliases of Int16

INTEGER

Int32

INT, INT4, and INTEGER are aliases of Int32

BIGINT

Int64

BIGINT is an alias of Int64

REAL

Float32

FLOAT is an alias of Float32

DOUBLE

Float64

DOUBLE is an alias of Float64

DECIMAL(p,s)

Decimal(p,s)

VARCHAR

String

CHAR

String

VARBINARY

String

Enabling clickhouse.map-string-as-varchar config property changes the mapping to VARCHAR

DATE

Date

TIMESTAMP(0)

DateTime

UUID

UUID

No other types are supported.

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

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

Название

Описание

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

unsupported-type-handling

Как обрабатывать колонки неподдерживаемых типов: * IGNORE, не обрабатывать колонку. * CONVERT_TO_VARCHAR, привести значение колонки к VARCHAR неограниченной длины. Соответствующий параметр сессии: unsupported_type_handling.

IGNORE

jdbc-types-mapped-to-varchar

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

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.

Pushdown#

The connector supports pushdown for a number of operations:

Aggregate pushdown for the following functions:

Примечание

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

Predicate pushdown support#

The connector does not support pushdown of any predicates on columns with textual types like CHAR or VARCHAR. This ensures correctness of results since the data source may compare strings case-insensitively.

In the following example, the predicate is not pushed down for either query since name is a column of type VARCHAR:

SELECT * FROM nation WHERE name > 'CANADA';
SELECT * FROM nation WHERE name = 'CANADA';