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

Дарья Барышева
Содержание

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

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

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

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

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

ВАЖНО

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

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

Server

Для создания сервера предназначена команда 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 приведен в таблице Опции сервера ниже. Обратите внимание, что эти опции могут быть определены как на уровне сервера, так и на уровне foreign-таблицы. При этом опции, отмеченные как обязательные, должны быть указаны на одном из уровней.

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

ПРИМЕЧАНИЕ

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

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

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

database

TEXT

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

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

 — 

Да

hosts

TEXT

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

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

 — 

Да

lines_batch_size

INT

Максимальное количество строк в батче данных, отправляемых в ClickHouse со стороны коннектора.

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

100000

Нет

bytes_batch_size_mb

INT

Максимальный размер батча данных, отправляемых в ClickHouse со стороны коннектора (в МБ). При одновременном указании с параметром lines_batch_size будет использоваться значение bytes_batch_size_mb.

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

 — 

Нет

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.

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

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

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

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

 — 

Да

staging_table_name_format

TEXT

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

 — 

Да, если use_staging = true

clickhouse_properties

TEXT

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

 — 

Нет

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

Нет
Правила валидации опции 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 символа.

User mapping

Для создания сопоставления пользователей предназначена команда 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>.

ПРИМЕЧАНИЕ

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

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

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

clickhouse_username

TEXT

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

 — 

Да

clickhouse_password

TEXT

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

 — 

Да

Foreign table

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

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

ПРИМЕЧАНИЕ

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

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

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

resource

TEXT

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

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

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

 — 

Да

cluster

TEXT

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

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

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

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

 — 

Нет
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней