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

Приоритет уровней

Опции коннектора можно задать на разных уровнях DDL - побеждает первое найденное значение, в таком порядке:

FOREIGN TABLE > USER MAPPING > SERVER > FOREIGN DATA WRAPPER > clickhouse-site.xml

clickhouse-site.xml - не уровень каталога Greenplum, а запасной вариант на стороне PXF: он применяется, только если опция вообще не задана ни на одном уровне DDL.

Исключение - опция format. Задавать её не нужно: FDW-объекты clickhouse_fdw и tkh_fdw уже несут format 'text', и это единственный рабочий формат обмена данными между Greenplum и PXF для этого коннектора.

Учётные данные

Два равноправных способа, оба - стандартная модель PXF.

USER MAPPING (как в ADB):

CREATE USER MAPPING FOR analyst
    SERVER clickhouse_server
    OPTIONS (clickhouse_username 'gp_writer', clickhouse_password 'secret');

Без USER MAPPING коннектор подключается к ClickHouse как default с пустым паролем.

Конфигурация PXF-сервера. Если пароль не должен храниться в каталоге Greenplum (он виден суперпользователю через pg_user_mapping), заведите отдельный PXF-сервер с файлом clickhouse-site.xml:

CREATE SERVER clickhouse_prod
    FOREIGN DATA WRAPPER clickhouse_fdw
    OPTIONS (config 'ch_prod', database 'default');

config 'ch_prod' указывает на файл $PXF_BASE/servers/ch_prod/clickhouse-site.xml на хостах PXF, где задаются clickhouse.user/clickhouse.password (и, при желании, адреса хостов вместо hosts в DDL). Файл читает PXF, Greenplum его не видит. Если задан и USER MAPPING, и clickhouse-site.xml, приоритет у USER MAPPING.

Пароль ни при одном из способов не попадает в лог в открытом виде - коннектор маскирует его при записи опций в лог.

Основные опции SERVER / FOREIGN TABLE

Опция	Уровень	Умолчание	Описание
`database`	SERVER/TABLE	-	база ClickHouse
`hosts`	SERVER/TABLE	-	список хостов ClickHouse через запятую, `host[:port]`, порт по умолчанию 8123
`resource`	TABLE	-	целевая таблица ClickHouse: `table` или `db.table`
`write_mode`	SERVER/TABLE	`stream`	`stream` - один непрерывный запрос на весь `INSERT`; `batch` - пакеты с паузами, как в ADB
`lines_batch_size`	SERVER/TABLE	100000	строк на пакет (в `batch`) или ограничение размера блока ClickHouse (в `stream`)
`bytes_batch_size_mb`	SERVER/TABLE	0 (выкл.)	дополнительный порог батча по объёму данных
`send_compressed`	SERVER/TABLE	false	сжимать тело запроса gzip
`distribution_type`	SERVER/TABLE	`random`	как выбирать хост при нескольких `hosts`: `random` или `round-robin`
`connect_retries`	SERVER/TABLE	2	сколько раз переключиться на другой хост при сетевой ошибке
`connect_timeout_ms` / `query_timeout_ms`	SERVER/TABLE	10000 / без ограничения	таймауты соединения и ожидания ответа
`column_map`	SERVER/TABLE	-	сопоставление колонок, если имена в Greenplum и ClickHouse не совпадают: `gp_col=ch_col,...`
`strict_types`	SERVER/TABLE	true	что делать при несовпадении типа колонки: ошибка (`true`) или предупреждение в лог PXF (`false`)
`cluster`	TABLE	-	имя кластера ClickHouse - подменяет список хостов репликами из `system.clusters`; `hosts` при этом всё равно обязателен как стартовый адрес
`cluster_http_port`	SERVER/TABLE	8123	HTTP-порт для хостов, полученных через `cluster`
`use_staging`	SERVER/TABLE	false	включает транзакционную запись через промежуточную таблицу, см. страницу Использование
`staging_table_name_format`	SERVER/TABLE	-	обязательна вместе с `use_staging 'true'`, шаблон имени staging-таблицы, ровно один символ `$`
`staging_move_mode`	SERVER/TABLE	`auto`	как переносить данные из staging в целевую таблицу: `auto`, `attach_partition` или `insert_select`
`staging_control_timeout_ms`	SERVER/TABLE	600000	таймаут операций staging
`slice_mode`	SERVER/TABLE	`hash`	деление таблицы на срезы чтения: `hash`, `range` или `single`
`split_key`	SERVER/TABLE	ключ сортировки таблицы	колонка для деления по хэшу
`fragments_per_segment`	SERVER/TABLE	1	число фрагментов чтения на сегмент
`disable_ppd`	TABLE	false	отключить передачу условий `WHERE` в ClickHouse
`clickhouse_properties`	SERVER/TABLE	-	SSL и произвольные настройки ClickHouse, см. ниже

Список неполный - опции переноса из ADB (insert_distributed_sync, send_delay и другие), а также опции чтения диапазонами (range_column, range, interval) работают так же, как в ADB ClickHouse Connector 2.0.

SSL

Три ключа опции clickhouse_properties управляют TLS-соединением, остальные передаются в ClickHouse как настройки запроса:

OPTIONS (clickhouse_properties 'ssl=true;sslmode=strict;sslrootcert=/etc/clickhouse-certs/ca.pem')

Ключ	Умолчание	Описание
`ssl`	false	использовать HTTPS для хостов без явного `https://`
`sslmode`	strict	`strict` - проверка сертификата сервера по `sslrootcert`; `none` - доверять любому сертификату, только для тестового контура
`sslrootcert`	-	путь к PEM-файлу с корневым сертификатом

Опция cluster

cluster (плюс cluster_http_port) опрашивает system.clusters на одном из хостов hosts и подменяет рабочий список хостов репликами кластера. hosts при этом всё равно нужен - без стартового адреса опросить system.clusters не с чего, полностью бесхостовый режим не реализован.

Коннектор ходит по адресам, которые вернул сам ClickHouse (host_address из system.clusters), а не по адресам из DDL. Если кластер описан внутренними DNS-именами или IP-адресами (например, в контейнерной среде), убедитесь, что эти адреса достижимы с каждого сегмента Greenplum, а не только с хоста, откуда идёт первый запрос.

Маппинг типов

Greenplum	ClickHouse	Комментарий
`bool`	`Bool` / `UInt8`	на передаче - `1`/`0`
`int2`/`int4`/`int8`	`Int16`/`Int32`/`Int64`	более широкие `UInt*` тоже принимаются
`float4`/`float8`	`Float32`/`Float64`	`NaN`/`Infinity` передаются как `nan`/`inf`
`numeric(p,s)`	`Decimal(p,s)`	текстом, без потери точности
`text`/`varchar`/`char`	`String`/`FixedString`/`LowCardinality(String)`/`Enum`	пустая строка и `NULL` различаются корректно
`bytea`	`String`	сырые байты, без перекодировки в UTF-8
`date`	`Date`/`Date32`	`Date` не вмещает даты после 2149 года - для более поздних используйте `Date32`
`timestamp`	`DateTime`/`DateTime64(6)`	`DateTime` - секундная точность, дробная часть отбрасывается; для микросекунд нужен `DateTime64(6)`
`timestamptz`	`DateTime('UTC')`/`DateTime64(6,'UTC')`	приводится к UTC при записи
`uuid`	`UUID`
`json`/`jsonb`	`String`/`JSON`	текстом как есть
массив (`T[]`)	`Array(T)`	вложенные массивы поддерживаются; `NULL`-элемент требует `Array(Nullable(T))`; `bytea[]` не поддерживается

Map, Tuple, Nested, IPv4, IPv6 в ClickHouse коннектором не поддерживаются.

Метрики

Каждый хост PXF отдаёт метрики коннектора в формате Prometheus тем же портом, что и общее состояние PXF (по умолчанию 5888):

curl -s localhost:5888/actuator/prometheus | grep pxf_clickhouse

Метрика	Тип	Что считает
`pxf_clickhouse_rows_total`	counter	записанные и прочитанные строки
`pxf_clickhouse_bytes_total`	counter	переданные байты
`pxf_clickhouse_batches_total`	counter	пакеты запроса, успешные и неудачные
`pxf_clickhouse_errors_total`	counter	ошибки по видам: сетевые, соединения, ClickHouse
`pxf_clickhouse_batch_duration_seconds`	timer	время выполнения успешного пакета
`pxf_clickhouse_staging_duration_seconds`	timer	время операций staging - переноса, отката, очистки