Настройка ADB ClickHouse Connector

Дарья Барышева

Для отправки данных из ADB в ClickHouse через ADB ClickHouse Connector необходимо предварительно создать следующие объекты на стороне кластера ADB:

  1. Server (сервер) — инкапсулирует информацию о соединении с внешним источником данных.

  2. User mapping (сопоставление пользователя) — обеспечивает аутентификацию пользователя во внешнем источнике данных.

  3. Foreign table (сторонняя таблица) — таблица ADB, определяющая структуру внешних данных. Сторонняя таблица не хранит данные в ADB, но к ней можно обращаться с помощью запросов как к обычной таблице.

Примеры использования перечисленных объектов для отправки данных из ADB в ADQM приведены в статье Примеры использования ADB ClickHouse Connector.

ВАЖНО

  • Для каждого кластера ClickHouse, в который планируется отправлять запросы из ADB, достаточно создать один сервер и одно сопоставление пользователя. Сторонних таблиц может быть несколько, если отправка запросов запланирована в различные таблицы ClickHouse.

  • Все опции, приведенные в таблицах ниже (Опции сервера, Опции сопоставления пользователя, Опции сторонней таблицы), при объявлении объектов заполняются в строковом виде (в одинарных кавычках '). Столбец Тип в таблицах показывает, какой тип данных будет использоваться при валидации вводимых значений.

Сервер

Для создания сервера предназначена команда CREATE SERVER, базовый синтаксис которой приведен ниже:

CREATE SERVER <server_name> [ TYPE '<server_type>' ] [ VERSION '<server_version>' ]
    FOREIGN DATA WRAPPER <fdw_name>
    [ OPTIONS ( [ <option> '<value>' [, ... ]] ) ]

где:

  • <server_name> — имя сервера в ADB. Должно быть уникальным в рамках текущей базы данных ADB.

  • <server_type> — необязательный параметр, определяющий тип сервера.

  • <server_version> — необязательный параметр, определяющий версию сервера.

  • <fdw_name> — имя обертки сторонних данных (foreign data wrapper). Необходимо указать tkh_fdw — foreign data wrapper, который создается автоматически после установки коннектора (см. шаг 8 в статье Установка ADB ClickHouse Connector).

  • <option> — параметры сервера, определяющие детали подключения к внешнему источнику данных. Список возможных опций для ADB ClickHouse Connector приведен в таблице Опции сервера ниже. Обратите внимание, что эти опции могут быть определены как на уровне сервера, так и на уровне сторонней таблицы. При этом опции, отмеченные как обязательные, должны быть указаны на одном из уровней.

  • <value> — значения соответствующих параметров <option>.

ПРИМЕЧАНИЕ

  • Чтобы создать сервер, пользователю необходима привилегия USAGE для обертки сторонних данных tkh_fdw. Пользователь, создавший сервер, становится его владельцем.

  • Полную версию синтаксиса команды CREATE SERVER можно посмотреть в документации Greengage DB.

  • Для редактирования параметров сервера предназначена команда ALTER SERVER, для удаления — DROP SERVER.
Опции сервера
Имя Тип Описание Default Обязательность

database

TEXT

Имя базы данных в ClickHouse, в которой расположена целевая таблица.

Должно соответствовать регулярному выражению ^[a-zA-Z_][0-9a-zA-Z_]*$

 — 

Да

hosts

TEXT

Список хостов в ClickHouse, на которых расположена целевая таблица. Поскольку кластер ClickHouse не имеет единой точки входа (мастер-ноды) и запросы могут отправляться к любому из хостов в кластере, для снижения нагрузки отправка батчей данных со стороны коннектора на хосты осуществляется согласно выбранной стратегии random или round-robin (см. параметр distribution_type далее).

Правила валидации параметра hosts см. ниже

 — 

Да

lines_batch_size

INT

Максимальное количество строк в одном батче, отправляемом коннектором в ClickHouse. Используется только для операций INSERT.

Значение 0 отключает разбиение на батчи по числу строк. Если bytes_batch_size_mb тоже равен 0, данные не разбиваются на батчи, и каждый сегмент отправляет весь поток одним INSERT.

Игнорируется, если bytes_batch_size_mb больше 0

100000

Нет

bytes_batch_size_mb

INT

Максимальный размер одного батча (в МБ), отправляемого коннектором в ClickHouse. Используется только для операций INSERT.

Значение 0 отключает разбиение на батчи по размеру. Если lines_batch_size тоже равен 0, данные не разбиваются на батчи, и каждый сегмент отправляет весь поток одним INSERT.

Имеет приоритет над lines_batch_size

0

Нет

send_compressed

BOOL

Флаг, указывающий на необходимость компрессии данных на стороне коннектора перед отправкой в ClickHouse.

Возможные значения:

  • true — использовать сжатие данных.

  • false — не использовать сжатие данных.

false

Нет

send_delay

INT

Задержка между запросами со стороны коннектора к ClickHouse (в миллисекундах).

Для ввода допускаются целые положительные числа

300

Нет

insert_distributed_sync

BOOL

Включает или отключает режим синхронного добавления данных в распределенные (distributed) таблицы.

Возможные значения:

  • true — данные вставляются синхронно, а запрос INSERT считается выполненным успешно, когда все данные записаны на все шарды (по крайней мере на одну реплику для каждого шарда, если параметр ClickHouse internal_replication = true).

  • false — данные вставляются асинхронно.

true

Нет

distribution_type

TEXT

Определяет стратегию распределения нагрузки между хостами ClickHouse (см. hosts выше) при выполнении операций вставки данных со стороны коннектора.

Возможные значения:

  • random — случайный выбор хоста из списка.

  • round-robin — выбор хостов из списка с использованием алгоритма round-robin. В плане равномерности распределения нагрузки этот вариант предпочтительнее.

random

Нет

use_staging

BOOL

Флаг, указывающий на необходимость создания коннектором staging-таблиц на стороне ClickHouse перед выполнением вставки данных в целевую таблицу. Используется для эмуляции транзакций, которые отсутствуют в ClickHouse. В случае сбоя транзакция ADB, содержащая команду INSERT, откатывается, и целевая таблица остается без изменений. Однако, если транзакция откатывается после того, как партиция уже присоединена в ClickHouse, коннектор не сможет удалить добавленные строки. Атомарность гарантируется при вставке в одну партицию локальной таблицы.

Staging-таблицы поддерживаются только для следующих семейств движков в ClickHouse: MergeTree (в том числе их Replicated*-аналоги) и Distributed. Для остальных движков будет возвращаться ошибка при создании staging-окружения, так как не для всех типов движков можно реализовать подключение партиций в ClickHouse.

Возможные значения:

  • true — использовать staging-таблицы.

  • false — не использовать staging-таблицы. В этом режиме есть определенные риски, так как консистентность добавления данных может быть нарушена. Однако режим подходит для разовых вставок в пустые целевые таблицы.

 — 

Да

staging_table_name_format

TEXT

Определяет формат наименования staging-таблиц (см. use_staging выше). Пример: '$_tmp_$'. Первый подстановочный знак (placeholder) $ заменяется на имя целевой таблицы в ClickHouse (см. resource в таблице Опции сторонней таблицы), второй — на целочисленный идентификатор, автоматически генерируемый на мастер-хосте ADB

 — 

Да, если use_staging = true

clickhouse_properties

TEXT

Перечень кастомных опций ClickHouse в формате <custom_option>=<value>;[…​], где <custom_option> — имя опции, <value> — значение опции.

Для операций SELECT применяются только опции SSL.

Для операций INSERT см. конфигурацию Java-клиента ClickHouse. Если имя опции совпадает с настройкой самого ClickHouse (см. system.settings), опция передается в ClickHouse как настройка запроса

 — 

Нет

fdw_startup_cost

DOUBLE

Оценка стоимости получения первой строки от источника данных.

Для ввода допускаются дробные положительные числа.

Опция может быть использована только в запросах SELECT к ADQM/ClickHouse

1000.0

Нет

fdw_tuple_cost

DOUBLE

Оценка стоимости получения одной строки от источника данных.

Для ввода допускаются дробные положительные числа.

Опция может быть использована только в запросах SELECT к ADQM/ClickHouse

0.01

Нет

fdw_tuples_count

DOUBLE

Оценка количества всех строк в источнике данных. Без учета селективности запроса, условий LIMIT и т.д.

Для ввода допускаются дробные положительные числа >= 1.

Опция может быть использована только в запросах SELECT к ADQM/ClickHouse

100000.0

Нет

client_version

TEXT

JDBC-драйвер для клиента ClickHouse для операций INSERT:

  • v2 — официальный JDBC-драйвер ClickHouse. Используется по умолчанию начиная с ADB 6.32.0.

  • blynk — устаревший драйвер clickhouse4j.

v2

Нет
ПРИМЕЧАНИЕ

Устаревший драйвер clickhouse4j (client_version 'blynk') не поддерживает алгоритмы сжатия, которые используются по умолчанию в новых версиях ClickHouse Server. Если вы хотите использовать этот драйвер с последними версиями ClickHouse Server, укажите clickhouse_properties 'compress=false' на уровне сервера или таблицы.
Правила валидации опции hosts

  • Список хостов ClickHouse указывается в следующем формате: <hostname>:<port> [, …​], где <hostname> — имя каждого хоста, <port> — номер HTTP-порта для подключения к соответствующему хосту.

  • Максимальная длина имени каждого хоста <hostname> — 255 символов.

  • В <hostname> допускаются только числовые литералы 0-9, ASCII символы a-zA-Z, дефис -, нижнее подчеркивание _ и точка ..

  • Наличие для каждого <hostname> подстроки с номером порта <port> обязательно. В номере порта допускаются только числовые литералы 0-9. Максимальная длина номера порта <port> — 5 символов.

  • Максимальная длина строки hosts: (255 (максимальная длина <hostname>) + 1 (символ :) + 5 (максимальная длина <port>) + 1 (разделитель ,)) x 127 (число хостов) = 33274 символа.

Сопоставление пользователя

Для создания сопоставления пользователя предназначена команда CREATE USER MAPPING, базовый синтаксис которой приведен ниже:

CREATE USER MAPPING FOR { <username> | USER | CURRENT_USER | PUBLIC }
    SERVER <server_name>
    [ OPTIONS ( <option> '<value>' [, ... ] ) ]

где:

  • <username> — имя пользователя в базе данных ADB. Наряду с явным указанием пользователя, допускается ввод следующих констант:

    • USER или CURRENT_USER — текущий пользователь, установивший соединение с ADB.

    • PUBLIC — все существующие и будущие пользователи ADB.

  • <server_name> — имя сервера.

  • <option> — параметры сопоставления пользователя. Как правило, включают имя пользователя и пароль для подключения к внешнему источнику данных. Список возможных опций для ADB ClickHouse Connector приведен в таблице Опции сопоставления пользователя ниже.

  • <value> — значения соответствующих параметров <option>.

ПРИМЕЧАНИЕ

  • Чтобы создать сопоставление пользователя, необходимо быть владельцем соответствующего сервера.

  • Полную версию синтаксиса команды CREATE USER MAPPING можно посмотреть в документации Greengage DB.

  • Для редактирования параметров сопоставления пользователя предназначена команда ALTER USER MAPPING, для удаления — DROP USER MAPPING.
Опции сопоставления пользователя
Имя Тип Описание Default Обязательность

clickhouse_username

TEXT

Имя пользователя в ClickHouse

 — 

Да

clickhouse_password

TEXT

Пароль пользователя в ClickHouse. В случае отсутствия пароля (например, в тестовом окружении) указывается пустая строка

 — 

Да

Сторонняя таблица

Для создания сторонней таблицы предназначена команда CREATE FOREIGN TABLE, базовый синтаксис которой приведен ниже:

CREATE FOREIGN TABLE [ IF NOT EXISTS ] <table_name> ( [
    <column_name> <data_type> [ COLLATE <collation> ] [ <column_constraint> [ ... ] ]
      [, ... ]
] )
    SERVER <server_name>
  [ OPTIONS ( <option> '<value>' [, ... ] ) ]

где:

  • <table_name> — имя сторонней таблицы в ADB.

  • <column_name> — имя столбца.

  • <data_type> — тип данных столбца.

  • <collation> — используемая для столбца сортировка (collation).

  • <column_constraint> — ограничение (constraint), определенное на уровне столбца. Имя ограничения <constraint_name> указывается опционально. Синтаксис:

    [ CONSTRAINT <constraint_name> ]
{ NOT NULL |
  NULL |
  DEFAULT <default_expr> }

    Возможные ограничения:

    • NOT NULL — указывает, что столбец не может содержать null-значений.

    • NULL — указывает, что столбец может содержать null-значения. Это ограничение используется по умолчанию (если не указано NOT NULL).

    • DEFAULT — определяет для столбца значение по умолчанию <default_expr>.

  • <server_name> — имя сервера.

  • <option> — параметры сторонней таблицы. Для ADB ClickHouse Connector все опции, определенные на уровне сервера , могут быть переопределены на уровне сторонних таблиц (частично или полностью). При одновременном указании какой-либо опции для сервера и таблицы табличный уровень имеет больший приоритет. Дополнительно на уровне сторонней таблицы объявляются еще две опции, приведенные в таблице Опции сторонней таблицы ниже.

  • <value> — значения соответствующих параметров <option>.

ПРИМЕЧАНИЕ

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

  • Полную версию синтаксиса команды CREATE FOREIGN TABLE можно посмотреть в документации Greengage DB.

  • Для редактирования параметров сторонней таблицы предназначена команда ALTER FOREIGN TABLE, для удаления — DROP FOREIGN TABLE.
Опции сторонней таблицы
Имя Тип Описание Default Обязательность

resource

TEXT

Имя таблицы на стороне ClickHouse.

Если вам необходимо реализовать собственную стратегию распределения данных по хостам (шардирование), необходимо использовать вставку через распределенную (distributed) таблицу ClickHouse с настроенным ключом шардирования, указав ее имя в опции resource. При записи данных в distributed-таблицу важно помнить о том, чтобы физические (локальные) таблицы присутствовали на всех хостах кластера ClickHouse, в противном случае коннектор вернет ошибку.

Значение опции должно соответствовать регулярному выражению ^[a-zA-Z_][0-9a-zA-Z_]*$

 — 

Да

cluster

TEXT

Имя кластера в ClickHouse. Для получения дополнительной информации можно обратиться к статье Типовой кластер в документации ADQM.

При указании опции cluster список хостов ClickHouse hosts должен быть определен на уровне сторонней таблицы и состоять из одного элемента <hostname>:<port> — даже в случае, если он предварительно объявлен на уровне сервера. Иначе может возникнуть неоднозначная ситуация, когда на уровне объявления сервера задан некоторый список хостов, а работа фактически будет производиться с хостами, полученными из метаданных кластера ClickHouse.

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

Максимальная длина имени кластера — 128 символов

 — 

Нет

Параметры SSL

ПРИМЕЧАНИЕ

  • В официальном JDBC-драйвере ClickHouse (используется по умолчанию начиная с ADB 6.32.0) опция sslmode в настоящее время не поддерживается, и проверку сертификата для операций INSERT нельзя отключить (через sslmode=none). Если вы использовали sslmode=none до обновления до ADB 6.32.0, выполните одно из следующих действий:

    • Укажите корректный файл CA-сертификата в sslrootcert (рекомендуется).

    • Используйте опцию client_version 'blynk' на уровне стороннего сервера или сторонней таблицы, чтобы сохранить прежнее поведение.

  • До ADB 6.30.0 в коннекторе ADB ClickHouse поддерживался SSL только для операций INSERT. Начиная с версии 6.30.0 SSL также можно использовать с SELECT.

Параметры SSL для соединения коннектора с ClickHouse настраиваются с помощью опции clickhouse_properties. Например:

OPTIONS (
    clickhouse_properties 'ssl=true;sslrootcert=/home/gpadmin/tkh_fdw/certs/ca-cert.pem'
)

Более подробный пример приводится в статье Примеры использования.

Данная опция может быть использована как на уровне стороннего сервера, так и на уровне сторонней таблицы. В опции clickhouse_properties принимаются параметры, перечисленные ниже (в формате ключ=значение;ключ=значение;…​).

Имя Тип Описание Default

ssl

BOOL

Включает использование SSL для подключений к ClickHouse. Возможные значения:

  • true — использовать соединения по HTTPS;

  • false — использовать соединения по HTTP (без шифрования).

false

sslmode

TEXT

Определяет режим проверки сертификатов. Возможные значения:

  • strict — обязательная проверка сертификатов;

  • none — проверка сертификатов не производится.

Для операций INSERT опция может быть использована только с устаревшим драйвером clickhouse4j (см. client_version выше). В официальном драйвере ClickHouse, используемом по умолчанию для INSERT, опция не поддерживается

strict

sslrootcert

TEXT

Абсолютный путь к файлу корневого сертификата (CA), используемого для проверки сертификатов сервера. Файл должен быть размещен по указанному пути на всех хостах ADB (мастер-хосте и сегментных хостах)

none

SSL для соединения ADB с PXF

Для отправки данных в ClickHouse коннектор устанавливает соединение между сегментом ADB и сервисом PXF, которое по умолчанию использует протокол HTTP. Если в конфигурационных параметрах сервиса PXF включен SSL, необходимо также, чтобы коннектор использовал HTTPS для соединения между ADB и PXF (иначе отправка команды INSERT в ClickHouse завершится ошибкой). Для этого установите для опции pxf_protocol значение 'https'. Опцию можно задать на следующих уровнях (в порядке возрастания приоритета): сторонняя таблица, сторонний сервер и обертка сторонних данных (foreign-data wrapper).

Например, чтобы задать опцию с наивысшим приоритетом, добавьте ее в обертку сторонних данных:

ALTER FOREIGN DATA WRAPPER tkh_fdw
    OPTIONS (ADD pxf_protocol 'https');

Чтобы удалить опцию с уровня обертки сторонних данных, выполните следующую команду:

ALTER FOREIGN DATA WRAPPER tkh_fdw
    OPTIONS (DROP pxf_protocol);

Обратите внимание, что эта опция не включает SSL для соединений PXF → ClickHouse (SSL для этого соединения настраивается в clickhouse_properties) и не влияет на команды SELECT, при которых коннектор получает данные из ClickHouse напрямую, без участия PXF.

Опции парсера

Коннектор использует библиотеку univocity-parsers для парсинга данных перед их отправкой в ClickHouse. Опции парсера можно настраивать с помощью clickhouse_properties на уровне стороннего сервера или сторонней таблицы.

Опция в коннекторе Javadoc парсера По умолчанию

parser_auto_closing_enabled

setAutoClosingEnabled

true

parser_column_reordering_enabled

setColumnReorderingEnabled

true

parser_header_extraction_enabled

setHeaderExtractionEnabled

false

parser_ignore_leading_whitespaces

setIgnoreLeadingWhitespaces

true

parser_ignore_trailing_whitespaces

setIgnoreTrailingWhitespaces

true

parser_input_buffer_size

setInputBufferSize

1048576

parser_input_reading_on_separate_thread

setReadInputOnSeparateThread

true

parser_line_separator_detection_enabled

setLineSeparatorDetectionEnabled

false

parser_maximum_number_of_characters_per_column

setMaxCharsPerColumn

4096

parser_maximum_number_of_columns

setMaxColumns

512

parser_null_value

setNullValue

null

parser_number_of_records_to_read

setNumberOfRecordsToRead

-1 (no limit)

parser_error_content_length

setErrorContentLength

-1 (no limit)

parser_skip_bits_as_whitespace

setSkipBitsAsWhitespace

true

parser_skip_empty_lines

setSkipEmptyLines

true

parser_comment_character

setComment

'\0' (disabled)

parser_escape_character

setEscapeChar

'\'

parser_escaped_tab_char

setEscapedTabChar

't'

parser_line_separator

setLineSeparator

system line separator

Например, чтобы изменить ограничение по умолчанию в 512 столбцов и вставлять строки, содержащие до 1000 столбцов, создайте стороннюю таблицу с опцией parser_maximum_number_of_columns:

CREATE FOREIGN TABLE wide_table_ft (
    id      int,
    -- ... other columns --
    column_999 text
)
SERVER clickhouse_server
OPTIONS (
    resource 'wide_table',
    clickhouse_properties 'parser_maximum_number_of_columns=1000'
);
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней