Работа с базами данных ClickHouse

В этом разделе описана основная информация про работу с внешней базой данных ClickHouse.

Для работы с внешней базой данных ClickHouse необходимо выполнить следующие шаги:

  1. Создать секрет, содержащий пароль для подключения к базе данных.

    CREATE OBJECT clickhouse_datasource_user_password (TYPE SECRET) WITH (value = "<password>");
    
  2. Создать внешний источник данных, описывающий целевую базу данных внутри кластера ClickHouse. Для соединения с ClickHouse можно использовать либо нативный TCP-протокол (PROTOCOL="NATIVE"), либо протокол HTTP (PROTOCOL="HTTP"). Включить шифрование соединений к внешней базе данных можно с помощью параметра USE_TLS="TRUE".

    CREATE EXTERNAL DATA SOURCE clickhouse_datasource WITH (
        SOURCE_TYPE="ClickHouse",
        LOCATION="<host>:<port>",
        DATABASE_NAME="<database>",
        AUTH_METHOD="BASIC",
        LOGIN="<login>",
        PASSWORD_SECRET_NAME="clickhouse_datasource_user_password",
        PROTOCOL="NATIVE",
        USE_TLS="TRUE"
    );
    
  3. Развернуть коннектор и настроить динамические узлы YDB на взаимодействие с ним. Также необходимо обеспечить сетевой доступ с динамических узлов YDB к внешнему источнику данных (по адресу, указанному в параметре LOCATION запроса CREATE EXTERNAL DATA SOURCE). В случае, если на предыдущем шаге было включено шифрование сетевых соединений к внешнему источнику, коннектор будет использовать системные корневые сертификаты (более подробно о настройке TLS можно узнать в инструкции по разворачиванию коннектора).

  4. Выполнить запрос к базе данных.

Синтаксис запросов

Для работы с ClickHouse используется следующая форма SQL-запроса:

SELECT * FROM clickhouse_datasource.<table_name>

где:

  • clickhouse_datasource - идентификатор внешнего источника данных;
  • <table_name> - имя таблицы внутри внешнего источника данных.

Ограничения

При работе с кластерами ClickHouse существует ряд ограничений:

  1. Внешние источники доступны только для чтения данных через запросы SELECT. Запросы, модифицирующие таблицы во внешних источниках, движком обработки федеративных запросов в настоящее время не поддерживаются.

  2. Если значение даты, хранящейся во внешнем источнике данных, находится вне допустимого для YDB диапазона (все используемые даты должны быть позднее 1970-01-01, но ранее 2105-12-31), в YDB такое значение будет преобразовано в NULL.

  3. Система обработки федеративных запросов YDB умеет передавать исполнение некоторых частей запроса системе, выступающей в качестве источника данных. Фрагменты запроса передаются сквозь YDB непосредственно во внешнюю систему и обрабатываются внутри неё. С помощью этой оптимизации, которая носит название «пушдауна предикатов» (predicate pushdown), удаётся значительно снизить объём данных, передаваемых от источника к движку обработки федеративных запросов. Благодаря этому снижается нагрузка на сеть и экономятся вычислительные ресурсы YDB.

    Частный случай пушдауна предикатов, при котором выполняется передача фильтрующих выражений, указанных после ключевого слова WHERE, называется «пушдауном фильтров» (filter pushdown). Пушдаун фильтров возможен при использовании:

    Описание Пример
    Фильтров вида IS NULL/IS NOT NULL WHERE column1 IS NULL или WHERE column1 IS NOT NULL
    Логических условий OR, NOT, AND. WHERE column IS NULL OR column2 is NOT NULL.
    Условий сравнения =, <>, <, <=, >, >= c другими колонками или константами. WHERE column3 > column4 OR column5 <= 10.

    Поддерживаемые типы данных для пушдауна фильтров:

    Тип данных YDB
    Bool
    Int8
    Uint8
    Int16
    Uint16
    Int32
    Uint32
    Int64
    Uint64
    Float
    Double

Поддерживаемые типы данных

По умолчанию в ClickHouse колонки физически не могут содержать значение NULL, однако пользователь имеет возможность создать таблицу с колонками опциональных, или nullable типов. Типы колонок, отображаемые YDB при извлечении данных из внешней базы данных ClickHouse, будут зависеть от того, используются ли в таблице ClickHouse примитивные или опциональные типы. При этом в связи с рассмотренными выше ограничениями типов YDB, использующихся для хранения дат и времени, все аналогичные типы ClickHouse отображаются в YDB как опциональные.

Ниже приведены таблицы соответствия типов 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<Date> Допустимый диапазон дат с 1970-01-01 и до 2105-12-31. При выходе значения за границы диапазона возвращается NULL.
DateTime Optional<DateTime> Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение NULL.
DateTime64 Optional<Timestamp> Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение NULL.
String String
FixedString String Нулевые байты FixedString переносятся в String без изменений.

Опциональные типы данных

Тип данных ClickHouse Тип данных YDB Примечания
Nullable(Bool) Optional<Bool>
Nullable(Int8) Optional<Int8>
Nullable(UInt8) Optional<Uint8>
Nullable(Int16) Optional<Int16>
Nullable(UInt16) Optional<Uint16>
Nullable(Int32) Optional<Int32>
Nullable(UInt32) Optional<Uint32>
Nullable(Int64) Optional<Int64>
Nullable(UInt64) Optional<Uint64>
Nullable(Float32) Optional<Float>
Nullable(Float64) Optional<Double>
Nullable(Date) Optional<Date>
Nullable(Date32) Optional<Date> Допустимый диапазон дат с 1970-01-01 и до 2105-12-31. При выходе значения за границы диапазона возвращается NULL.
Nullable(DateTime) Optional<DateTime> Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение NULL.
Nullable(DateTime64) Optional<Timestamp> Допустимый диапазон значений времени с 1970-01-01 00:00:00 и до 2105-12-31 23:59:59. При выходе значения за границы диапазона возвращается значение NULL.
Nullable(String) Optional<String>
Nullable(FixedString) Optional<String> Нулевые байты FixedString переносятся в String без изменений.