--- metadata: - name: generator content: Diplodoc Platform v5.50.4 alternate: - https://ydb.tech/docs/en/concepts/query_execution/federated_query/clickhouse.md - https://ydb.tech/docs/ru/concepts/query_execution/federated_query/clickhouse.md sourcePath: ru/core/concepts/query_execution/federated_query/clickhouse.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Работа с базами данных ClickHouse В этом разделе описана основная информация про работу с внешней базой данных [ClickHouse](https://clickhouse.com). Для работы с внешней базой данных ClickHouse необходимо выполнить следующие шаги: 1. Создать [секрет](https://ydb.tech/docs/ru/concepts/datamodel/secrets.md), содержащий пароль для подключения к базе данных. ```yql CREATE SECRET clickhouse_datasource_user_password WITH (value = ""); ``` 1. Создать [внешний источник данных](https://ydb.tech/docs/ru/concepts/datamodel/external_data_source.md), описывающий целевую базу данных внутри кластера ClickHouse. Для соединения с ClickHouse можно использовать либо [нативный TCP-протокол](https://clickhouse.com/docs/ru/interfaces/tcp) (`PROTOCOL="NATIVE"`), либо [протокол HTTP](https://clickhouse.com/docs/ru/interfaces/http) (`PROTOCOL="HTTP"`). Включить шифрование соединений к внешней базе данных можно с помощью параметра `USE_TLS="TRUE"`. ```yql CREATE EXTERNAL DATA SOURCE clickhouse_datasource WITH ( SOURCE_TYPE="ClickHouse", LOCATION=":", DATABASE_NAME="", AUTH_METHOD="BASIC", LOGIN="", PASSWORD_SECRET_PATH="clickhouse_datasource_user_password", PROTOCOL="NATIVE", USE_TLS="TRUE" ); ``` 1. Развернуть [коннектор](https://ydb.tech/docs/ru/concepts/query_execution/federated_query/architecture.md#connectors) и [настроить](https://ydb.tech/docs/ru/devops/deployment-options/manual/federated-queries/index.md) динамические узлы YDB на взаимодействие с ним. Также необходимо обеспечить сетевой доступ с динамических узлов YDB к внешнему источнику данных (по адресу, указанному в параметре `LOCATION` запроса `CREATE EXTERNAL DATA SOURCE`). В случае, если на предыдущем шаге было включено шифрование сетевых соединений к внешнему источнику, коннектор будет использовать системные корневые сертификаты (более подробно о настройке TLS можно узнать в [инструкции](https://ydb.tech/docs/ru/devops/deployment-options/manual/federated-queries/connector-deployment.md) по разворачиванию коннектора). 2. [Выполнить запрос](#query) к базе данных. ## Синтаксис запросов {#query} Для работы с ClickHouse используется следующая форма SQL-запроса: ```yql SELECT * FROM clickhouse_datasource. ``` где: - `clickhouse_datasource` - идентификатор внешнего источника данных; - `` - имя таблицы внутри внешнего источника данных. ## Ограничения {#limitations} При работе с кластерами ClickHouse существует ряд ограничений: 1. Внешние источники доступны только для чтения данных через запросы `SELECT`. Запросы, модифицирующие таблицы во внешних источниках, движком обработки федеративных запросов в настоящее время не поддерживаются. 1. Если значение даты, хранящейся во внешнем источнике данных, находится вне допустимого для YDB диапазона (все используемые даты должны быть позднее 1970-01-01, но ранее 2105-12-31), в YDB такое значение будет преобразовано в `NULL`. 1. Система обработки федеративных запросов YDB умеет передавать исполнение некоторых частей запроса системе, выступающей в качестве источника данных. Фрагменты запроса передаются сквозь YDB непосредственно во внешнюю систему и обрабатываются внутри неё. С помощью этой оптимизации, которая носит название «пушдауна предикатов» (predicate pushdown), удаётся значительно снизить объём данных, передаваемых от источника к движку обработки федеративных запросов. Благодаря этому снижается нагрузка на сеть и экономятся вычислительные ресурсы YDB. Частный случай пушдауна предикатов, при котором выполняется передача фильтрующих выражений, указанных после ключевого слова `WHERE`, называется «пушдауном фильтров» (filter pushdown). Пушдаун фильтров возможен при использовании: |Описание|Пример| |---|---| |Проверка на `NULL`|`WHERE column1 IS NULL` или `WHERE column1 IS NOT NULL`| |Логических условий `OR`, `NOT`, `AND` и круглых скобок для управление приоритетом вычислений. |`WHERE column1 IS NULL OR (column2 IS NOT NULL AND column3 > 10)`.| |[Операторов сравнения](../../../yql/reference/syntax/expressions.md#comparison-operators) c другими колонками или константами. |`WHERE column1 > column2 OR column3 <= 10`, `WHERE column1 + column2 > 10`, `WHERE column1 = (10 + 10)`| При использовании других видов фильтров пушдаун на источник не выполняется: фильтрация строк внешней таблицы будет выполнена на стороне федеративной YDB, что означает, что YDB выполнит полное чтение (full scan) внешней таблицы в момент обработки запроса. Поддерживаемые типы данных для пушдауна фильтров: |Тип данных YDB| |----| |`Bool`| |`Int8`| |`Uint8`| |`Int16`| |`Uint16`| |`Int32`| |`Uint32`| |`Int64`| |`Uint64`| |`Float`| |`Double`| |`String`| ## Поддерживаемые типы данных По умолчанию в ClickHouse колонки физически не могут содержать значение `NULL`, однако пользователь имеет возможность создать таблицу с колонками опциональных, или [nullable](https://clickhouse.com/docs/ru/sql-reference/data-types/nullable) типов. Типы колонок, отображаемые YDB при извлечении данных из внешней базы данных ClickHouse, будут зависеть от того, используются ли в таблице ClickHouse примитивные или опциональные типы. При этом в связи с рассмотренными выше ограничениями типов YDB, использующихся для хранения дат и времени, все аналогичные типы ClickHouse отображаются в YDB как [опциональные](https://ydb.tech/docs/ru/yql/reference/types/optional.md). Ниже приведены таблицы соответствия типов ClickHouse и YDB. Все остальные типы данных, за исключением перечисленных, не поддерживаются. ### Примитивные типы данных |Тип данных ClickHouse|Тип данных YDB|Примечания| |---|----|------| |`Bool`|`Bool`|| |`Int8`|`Int8`|| |`UInt8`|`Uint8`|| |`Int16`|`Int16`|| |`UInt16`|`Uint16`|| |`Int32`|`Int32`|| |`UInt32`|`Uint32`|| |`Int64`|`Int64`|| |`UInt64`|`Uint64`|| |`Float32`|`Float`|| |`Float64`|`Double`|| |`Date`|`Date`|| |`Date32`|`Optional`|Допустимый диапазон дат с 1970-01-01 и до 2105-12-31. При выходе значения за границы диапазона возвращается `NULL`.| |`DateTime`|`Optional`|Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение `NULL`.| |`DateTime64`|`Optional`|Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение `NULL`.| |`String`|`String`|| |`FixedString`|`String`|Нулевые байты `FixedString` переносятся в `String` без изменений.| ### Опциональные типы данных |Тип данных ClickHouse|Тип данных YDB|Примечания| |---|----|------| |`Nullable(Bool)`|`Optional`|| |`Nullable(Int8)`|`Optional`|| |`Nullable(UInt8)`|`Optional`|| |`Nullable(Int16)`|`Optional`|| |`Nullable(UInt16)`|`Optional`|| |`Nullable(Int32)`|`Optional`|| |`Nullable(UInt32)`|`Optional`|| |`Nullable(Int64)`|`Optional`|| |`Nullable(UInt64)`|`Optional`|| |`Nullable(Float32)`|`Optional`|| |`Nullable(Float64)`|`Optional`|| |`Nullable(Date)`|`Optional`|| |`Nullable(Date32)`|`Optional`|Допустимый диапазон дат с 1970-01-01 и до 2105-12-31. При выходе значения за границы диапазона возвращается `NULL`.| |`Nullable(DateTime)`|`Optional`|Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение `NULL`.| |`Nullable(DateTime64)`|`Optional`|Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение `NULL`.| |`Nullable(String)`|`Optional`|| |`Nullable(FixedString)`|`Optional`|Нулевые байты `FixedString` переносятся в `String` без изменений.|