Настройка Tkhemali Connector 1.X

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

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

  1. Создать внешнюю таблицу writable external table, указав в директиве LOCATION протокол PXF с профилем TKH и опции соединения с ClickHouse.

  2. Если при отправке данных используется staging-слой (рекомендуемый способ):

    • Вызвать функцию txn, передав в ее аргументах запрос INSERT для добавления данных во внешнюю таблицу.

    • В случае непредвиденных сбоев (например, обрыва соединения) выполнить очистку промежуточных таблиц.

  3. Если staging-таблицы не планируется использовать, выполнить запрос INSERT к внешней таблице, созданной на шаге 1, напрямую.

Примеры отправки данных из ADB в ADQM с использованием описанных ниже настроек приведены в статье Примеры использования Tkhemali Connector 1.X.

Создание внешней таблицы

Чтобы создать внешнюю таблицу для записи данных, необходимо использовать команду CREATE WRITABLE EXTERNAL TABLE, базовый синтаксис которой приведен ниже:

CREATE WRITABLE EXTERNAL TABLE <table_name> (
    { <column_name> <data_type> [, ...] | LIKE <other_table> }
)
LOCATION (
    'pxf://<clickhouse_table_name>?<pxf_profile>[&<option>=<value> [...]]'
)
FORMAT 'TEXT'
ENCODING 'UTF8';

где:

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

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

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

  • <other_table> — исходная таблица, из которой в новую внешнюю таблицу будут скопированы имена столбцов, их типы данных и политика распределения данных. Обратите внимание, что ограничения и значения по умолчанию, указанные в исходной таблице, не копируются, так как они не поддерживаются во внешних таблицах.

  • <clickhouse_table_name> — полное имя целевой таблицы в ClickHouse, включающее имя базы данных. При использовании staging-слоя в опции необходимо указать имя промежуточной (staging) таблицы, добавив к имени целевой таблицы значение параметра ending_pattern (см. таблицу Аргументы функции txn). Например, если имя таблицы в ClickHouse default.t, то в директиве LOCATION следует указать default.t_tmp_$ (если используется значение ending_pattern по умолчанию).

  • <pxf_profile> — имя профиля PXF, которое можно определить двумя способами:

    { PROFILE=TKH | ACCESSOR=io.arenadata.tkh.pxf.TkhAccessor&RESOLVER=io.arenadata.tkh.pxf.TkhResolver }

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

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

ПРИМЕЧАНИЕ

  • Для оптимальной производительности политика распределения данных во внешней таблице должна быть указана аналогично таблице-источнику, из которой будут браться данные при передаче в ClickHouse. Это позволит не перераспределять данные перед отправкой, а отправлять их напрямую с сегментов ADB. Для этого при создании внешней таблицы рекомендуется использовать выражение LIKE или явно указывать аналогичный ключ распределения в выражении DISTRIBUTED BY.

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

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

url

TEXT

Разделенный запятыми список хостов в ClickHouse, на которых расположена целевая таблица. Заполняется в следующем формате: <user>:<password>@<hostname>:<port> [, …​], где:

  • <user> — имя пользователя в ClickHouse.

  • <password> — пароль пользователя в ClickHouse. В случае отсутствия пароля (например, в тестовом окружении) не заполняется.

  • <hostname> — имя каждого хоста.

  • <port> — номер HTTP-порта для подключения к соответствующему хосту.

 — 

Да, если distribution == LIST

distribution

TEXT

Тип распределения нагрузки между хостами ClickHouse.

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

  • LIST — хост выбирается случайным образом из списка, указанного в опции url.

  • GPREQUEST — хост выбирается из списка хостов, возвращенного запросом gp_request (см. ниже), с использованием алгоритма round-robin.

LIST

Нет

gp_url

TEXT

URL Master-хоста ADB для выполнения запроса gp_request

 — 

Да, если distribution == GPREQUEST

gp_user

TEXT

Имя пользователя ADB для выполнения запроса gp_request

 — 

Да, если distribution == GPREQUEST

gp_password

TEXT

Пароль пользователя ADB для выполнения запроса gp_request

 — 

Да, если distribution == GPREQUEST

gp_request

TEXT

Запрос для получения списка хостов ClickHouse, выбор из которого будет производиться с использованием алгоритма round-robin. Формат результата запроса должен быть идентичен указанному выше для опции url

 — 

Да, если distribution == GPREQUEST

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

Нет

Использование функции txn

Функция txn имеет следующее определение:

FUNCTION txn(query TEXT, http_port INT DEFAULT 8123, debug BOOLEAN DEFAULT false, ending_pattern TEXT DEFAULT '_tmp_$')
RETURNS void

Аргументы функции txn перечислены ниже.

Аргументы функции txn
Имя Тип Описание Default Обязательность

query

TEXT

Запрос для вставки данных во внешнюю таблицу. Рекомендуется использовать форму записи $$ INSERT INTO...$$ вместо кавычек, поскольку она позволяет использовать переход на новую строку и кавычки внутри $$

 — 

Да

http_port

INT

HTTP-порт ClickHouse, общий для всех нод, используемых в запросе. В данный момент нет возможности получить это значение с помощью SQL. Необходимо заполнить, если значение отлично от 8123

8123

Нет

debug

BOOL

Флаг, указывающий на необходимость логирования функции txn. Выводит информацию о всех внутренних операциях: создание промежуточных (staging) таблиц, валидация данных, переключение и удаление кусков данных в ClickHouse

false

Нет

ending_pattern

TEXT

Определяет формат наименования staging-таблиц — промежуточного слоя, создаваемого коннектором в ClickHouse перед выполнением вставки данных в целевую таблицу. Подстановочный знак (placeholder) $ заменяется на целочисленный идентификатор, автоматически генерируемый на Master-ноде ADB для эмуляции номеров транзакций в ClickHouse

'_tmp_$'

Нет

Вызов функции txn осуществляется с помощью запроса SELECT:

SELECT txn('INSERT INTO <external_table> VALUES(...);');
SELECT txn('INSERT INTO <external_table> SELECT ... FROM ...;');

где <external_table> — имя предварительно созданной внешней таблицы.

Очистка staging-таблиц

В случае непредвиденных сбоев может потребоваться удаление staging-таблиц на всех нодах кластера ClickHouse. Для этого необходимо выполнить следующие шаги на стороне ADB:

  1. Определите уникальный идентификатор, который был автоматически сгенерирован на стороне ADB при отправке данных в ClickHouse для использования в именах staging-таблиц:

    SELECT database || '.' || name AS tbl FROM sys_tables('<hostname>', <port>)
WHERE database = '<database_name>' and name like '<table_name><postfix>%';

    где:

    • <hostname> — имя одного из хостов ClickHouse, на котором расположена целевая таблица ClickHouse.

    • <port> — номер HTTP-порта для подключения к соответствующему хосту <hostname>.

    • <database_name> — имя базы данных в ClickHouse.

    • <table_name> — имя целевой таблицы ClickHouse, в которую производилась запись из ADB.

    • <postfix> — постфикс, который добавлялся к имени целевой таблицы в ClickHouse для формирования имени staging-таблиц. Совпадает со значением опции ending_pattern без подстановочного знака (placeholder) $ (см. Аргументы функции txn выше).

    Пример:

    SELECT database || '.' || name AS tbl FROM sys_tables('dev-adqm-01', 8123)
where database = 'default' and name like 'test_distr_tmp_%';

    Результат запроса приведен ниже. Число 59306 — искомый идентификатор.

                 tbl
------------------------------
 default.test_distr_tmp_59306
(1 row)

  2. Используя найденный идентификатор, выполните удаление промежуточных таблиц на всех нодах кластера с помощью функции drop_staging_tbl_based_on:

    WITH ch(h, p) AS (values ('<hostname>', <port>) [, ...])
SELECT drop_staging_tbl_based_on('<database_name>', '<table_name>', ch.h, ch.p, '<user>', '<password>', <debug>, '<postfix><id>') from ch;

    где:

    • <hostname> — имя хоста ClickHouse. Необходимо перечислить все хосты в кластере через запятую. Каждый хост указывается с номером порта <port> в круглых скобках.

    • <port> — номер HTTP-порта для подключения к соответствующему хосту <hostname>.

    • <database_name> — имя базы данных в ClickHouse.

    • <table_name> — имя целевой таблицы ClickHouse, в которую производилась запись из ADB.

    • <user> — имя пользователя в ClickHouse.

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

    • <debug> — флаг, указывающий на необходимость запуска функции в режиме отладки. По умолчанию false.

    • <postfix> — постфикс, который добавлялся к имени целевой таблицы в ClickHouse для формирования имени staging-таблиц. Совпадает со значением опции ending_pattern без подстановочного знака (placeholder) $ (см. Аргументы функции txn выше).

    • id — идентификатор, полученный на шаге 1.

    Пример:

    WITH ch(h, p) AS (values ('dev-adqm-01', 8123), ('dev-adqm-02', 8123), ('dev-adqm-03', 8123), ('dev-adqm-04', 8123))
SELECT drop_staging_tbl_based_on('default', 'test_distr', ch.h, ch.p, 'default', '', false, '_tmp_59306') FROM ch;

    Результат:

     drop_staging_tbl_based_on
---------------------------




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