SELECT и INSERT к данным, хранящимся на удалённом сервере PostgreSQL.
В настоящее время движок таблицы поддерживает только PostgreSQL версии 12 и выше.
Создание таблицы
- Имена столбцов должны совпадать с именами в исходной таблице PostgreSQL, но можно использовать только часть этих столбцов и в любом порядке.
- Типы столбцов могут отличаться от типов в исходной таблице PostgreSQL. ClickHouse пытается преобразовывать значения в типы данных ClickHouse.
- Настройка external_table_functions_use_nulls определяет, как обрабатывать столбцы с типом Nullable. Значение по умолчанию: 1. Если указано 0, табличная функция не создаёт столбцы с типом Nullable и вставляет значения по умолчанию вместо null. Это также применимо к значениям NULL внутри массивов.
host:port— адрес сервера PostgreSQL.database— имя удалённой базы данных.table— имя удалённой таблицы или запрос, передаваемый в PostgreSQL как есть (см. Передача запроса вместо имени таблицы).user— пользователь PostgreSQL.password— пароль пользователя.schema— схема таблицы, отличная от используемой по умолчанию. Необязательно.on_conflict— стратегия разрешения конфликтов. Пример:ON CONFLICT DO NOTHING. Необязательно. Примечание: добавление этой опции сделает вставку менее эффективной.
TLS/SSL
Параметры TLS/SSL передаются вlibpq и могут быть заданы как ключи именованной коллекции или как завершающие аргументы ключ-значение: sslmode (disable, allow, prefer, require, verify-ca или verify-full), а также сертификаты и ключ — в одном из двух вариантов. Если параметры не заданы, используются значения libpq по умолчанию (sslmode=prefer).
sslrootcert(CA‑сертификат или специальное значениеsystem),sslcert(клиентский сертификат) иsslkey(закрытый ключ клиента) задают пути к файлам, локальным для сервера. Их можно указать только в именованной коллекции, определённой в файле конфигурации сервера, и нельзя переопределить в запросе: сервер открывает эти файлы от своего имени.sslrootcert_pem,sslcert_pemиsslkey_pemпринимают вместо пути буквальное содержимое соответствующего файла. Их можно указать где угодно — в запросе, в именованной коллекции, созданной с помощью SQL, или при переопределении именованной коллекции. В журналах и запросахSHOWони маскируются, как пароль.
Настройки
Пул соединений, используемый движком таблицыPostgreSQL (и табличной функцией postgresql), можно настроить для каждой таблицы с помощью предложения SETTINGS. Если настройка не указана, по умолчанию используется значение соответствующей настройки postgresql_* на уровне запроса.
postgresql_connection_pool_size
Размер пула соединений (если все соединения заняты, запрос ожидает, пока одно из них не освободится). Значение должно быть ненулевым.
Значение по умолчанию: 16.
postgresql_connection_pool_wait_timeout
Тайм-аут операций push/pop в пуле соединений в миллисекундах, если пул пуст. 0 означает блокировку при пустом пуле.
Значение по умолчанию: 5000.
postgresql_connection_pool_retries
Число повторных попыток операций push/pop в пуле соединений.
Значение по умолчанию: 2.
postgresql_connection_pool_auto_close_connection
Закрывать соединение перед возвратом в пул.
Значение по умолчанию: false.
postgresql_connection_attempt_timeout
Тайм-аут подключения в секундах для одной попытки соединения с конечной точкой PostgreSQL. Значение передаётся как параметр connect_timeout в URL подключения.
Значение по умолчанию: 2.
Пример:
Подробности реализации
SELECT-запросы на стороне PostgreSQL выполняются как COPY (SELECT ...) TO STDOUT внутри PostgreSQL-транзакции в режиме только для чтения, с коммитом после каждого SELECT-запроса.
Простые предложения WHERE, такие как =, !=, >, >=, <, <= и IN, выполняются на сервере PostgreSQL.
Все JOIN, агрегации, сортировка, условия IN [ array ] и ограничение сэмплирования LIMIT выполняются в ClickHouse только после завершения запроса к PostgreSQL.
Передача запроса вместо имени таблицы
Вместо имени таблицы аргументtable может содержать SELECT-запрос, который передаётся в PostgreSQL как есть. Структура таблицы определяется по результату запроса. Запрос можно записать либо как подзапрос, либо обернуть в функцию query:
INSERT в неё не допускается. Тот же синтаксис поддерживается табличной функцией postgresql.
Форма подзапроса
(SELECT ...) разбирается ClickHouse и повторно сериализуется в диалекте PostgreSQL (экранирование идентификаторов PostgreSQL и строковых литералов) перед отправкой на сервер. Поэтому она должна быть корректным ClickHouse SQL. Чтобы передать синтаксис, специфичный для PostgreSQL, который ClickHouse не разбирает, используйте форму query('...'), текст которой отправляется в PostgreSQL дословно.Любой внешний WHERE, LIMIT, агрегация и т. д. из окружающего запроса ClickHouse не проталкиваются в переданный запрос — они применяются в ClickHouse после получения полного результата запроса. Чтобы ограничить данные, читаемые из PostgreSQL, поместите фильтр внутрь переданного запроса. При external_table_strict_query = 1 внешний фильтр по столбцам таблицы отклоняется с исключением вместо локального применения, поскольку его нельзя протолкнуть в переданный запрос. Проверка охватывает предикат WHERE верхнего уровня и каждый конъюнкт AND верхнего уровня. PREWHERE по столбцам этой таблицы не относится к данной настройке: этот движок таблицы не поддерживает PREWHERE, и такой запрос отклоняется с ошибкой ILLEGAL_PREWHERE независимо от настройки. Проверка выполняется только там, где фильтр вообще может быть протолкнут: когда эта таблица является единственной таблицей запроса, с любой стороны INNER JOIN или на сохраняющей стороне внешнего JOIN (левая сторона LEFT JOIN, правая сторона RIGHT JOIN). На несохраняющей стороне LEFT/RIGHT JOIN и с любой стороны FULL JOIN ничего не проталкивается и ничего не проверяется, поэтому фильтр по столбцам этой таблицы применяется локально после JOIN даже в строгом режиме. Там, где проверка выполняется, предикат, ссылающийся на другие таблицы, соединяемые в окружающем запросе, не проталкивается и исключается из проверки — как если он ссылается только на присоединённую сторону, так и если смешивает её с этой таблицей внутри одного выражения без AND (например, OR); такой предикат сохраняет обычную точку вычисления в ClickHouse (WHERE после JOIN, PREWHERE до него) и не отклоняется.INSERT-запросы на стороне PostgreSQL выполняются как COPY "table_name" (field1, field2, ... fieldN) FROM STDIN внутри PostgreSQL-транзакции с автокоммитом после каждого оператора INSERT.
Типы Array в PostgreSQL преобразуются в массивы ClickHouse.
Будьте внимательны: в PostgreSQL массив, созданный как
type_name[], может содержать многомерные массивы с разным количеством измерений в разных строках одного и того же столбца таблицы. В ClickHouse же допускаются только многомерные массивы с одинаковым количеством измерений во всех строках одного и того же столбца.|. Например:
0.
В примере ниже у реплики example01-1 наивысший приоритет: