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

Вся конфигурация клики описывается одним YSON-документом, называемым спеклет (speclet).

Спеклет клики хранится в Кипарисе по пути //sys/strawberry/chyt/<alias>/speclet. Также его можно получить с помощью команды CLI yt clickhouse ctl get-speclet.

Спеклет представляет собой набор опций, которые интерпретируются контроллером во время запуска клики. В частности, на основе данных опций контроллер генерирует конечную конфигурацию CHYT-инстансов.

Важным отличием CHYT от оригинального ClickHouse является то, что настройки задаются не в XML-формате, а в родном для системы YTsaurus YSON-формате. Ниже описан принцип, по которому интерпретируются настройки в таком формате.

Как формируется конфигурация

При составлении конфигурации используется следующая информация:

1. Базовый конфиг из Кипариса //sys/clickhouse/config.
2. Опции, описанные в спеклете.
3. Конфигурация нативного подключения к кластеру, которая берётся из содержимого //sys/@cluster_connection.

Доступные опции

Ниже перечислены опции клики, доступные для установки через команду set-option (в квадратных скобках указаны значения по умолчанию):

• active [%false] — если выставлена, контроллер будет пытаться запустить соответствующую клике Vanilla операцию. При значении %false клика будет неактивной — то есть она не будет обрабатывать запросы, при этом также не будет тратить ресурсов вычислительного пула. Опция может быть полезна для временного выключения клики с сохранением её конфигурации.

• pool — название вычислительного пула, в котором необходимо запускать операцию клики. Для выставления данной опции пользователю необходимо иметь право Use на указанный вычислительный пул. Выставление данной опции является обязательным для запуска операции клики под контроллером.

• enable_geodata [%true] — автоматически настроить системные словари, необходимые для работы некоторых Geo-функций clickhouse.

• restart_on_speclet_change [%true] — если выставлено, клика будет автоматически перезапускаться при любой реконфигурации (изменении спеклета). В противном случае для применения настроек клики необходимо перезапустить клику вручную.

• query_settings — словарь с настройками по умолчанию для всех запросов в клику. Про настройки запроса подробнее можно прочитать в соответствующем разделе документации.

• yt_config — словарь с конфигурацией YTsaurus части инстансов CHYT. Данная часть конфигурации будет записана в сгенерированную конфигурацию инстансов as is. Настройка предназначена для продвинутых пользователей. Использование данной опции не рекомендуется, так как структура данной конфигурации очень запутанна. По возможности необходимо пользоваться другими опциями, которые будут задавать необходимые изменения в конфигурации более простым способом.

• clickhouse_config — словарь с конфигурацией ClickHouse части инстансов CHYT. Эти настройки влияют на логику вычислительного движка ClickHouse и не отличаются от его оригинальных настроек. Аналогично yt_config, эта опция предназначена для продвинутых пользователей. Использовать её не рекомендуется.

• instance_count [1] — количество инстансов клики.

• preemption_mode [normal] — режим вытеснения, с которым будет запущена YTsaurus-операция клики. Настройка предназначена только для продвинутых пользователей. Если вы не уверены, что она вам нужна, то рекомендуется оставить значение по умолчанию.

• instance_cpu [16] — количество CPU, которое будет выделено под каждый инстанс клики. Настройка предназначена только для продвинутых пользователей. Если вы не уверены, что она вам нужна, то рекомендуется оставить значение по умолчанию.

• instance_total_memory [71940702208 (67 Gib)] — количество оперативной памяти в байтах, которое будет выделено под каждый инстанс клики. Настройка предназначена только для продвинутых пользователей. Если вы не уверены, что она вам нужна, то рекомендуется оставить значение по умолчанию.

Продвинутая конфигурация YTsaurus-части инстанса

YTsaurus-часть конфигурации инстанса живет в опции yt_config. Через данную опцию можно задать продвинутые настройки, которые не вынесены в отдельные опции спеклета. Поддерживаются следующие подопции:

• settings — CHYT-специфичные настройки запросов по умолчанию. Изменение настройки в данном разделе приводит к изменению значения по умолчанию для этой настройки для всех запросов в клике.

• table_writer — конфигурация Table Writer.

• table_attribute_cache — конфигурация кеша атрибутов таблиц. Данный кеш существенно повышает отзывчивость CHYT, но на текущий момент потенциально может приводить к неконсистентным чтениям (в таблице данные уже появились, а CHYT их еще не видит). Чтобы отключить данный кеш, можно воспользоваться конфигурацией:

  {read_from=follower;expire_after_successful_update_time=0;expire_after_failed_update_time=0;refresh_time=0;expire_after_access_time=0}
  

• create_table_default_attributes [{optimize_for = scan}] — атрибуты по умолчанию, с которыми будут создаваться таблицы при CREATE-запросах в CHYT.

• health_checker — конфигурация Health Checker. Состоит из 3 полей:

  — queries [["select * from `//sys/clickhouse/sample_table`"]] — список тестовых запросов, работоспособность которых будет регулярно проверяться.

  Внимание

  Запросы от Health Checker на данный момент исполняются от имени пользователя yt-clickhouse, который должен иметь права read на доступ к таблице.

  — period [60000] — период срабатывания проверки в миллисекундах.

  — timeout [0.9 * period / len(queries)] — таймаут на срабатывание каждого из сконфигурированных запросов. Если запрос не укладывается в таймаут, он считается failed.

• subquery — конфигурация основной части системы, которая координирует исполнение ClickHouse-запросов поверх таблиц YTsaurus. Перед конфигурированием этой части прочитайте статью об исполнении запроса внутри клики.

  — min_data_weight_per_thread [64 MiB] — (в байтах) при нарезании входа на подзапросы координатор будет пытаться выдать на каждое ядро каждого инстанса не меньше, чем заданный объем.

  — max_data_weight_per_subquery [50 GiB] — (в байтах) максимальный допустимый объем данных, обрабатываемый на одном ядре одного инстанса. Данное ограничение является защитным и защищает пользователей клики от случайного запуска огромного запроса, обрабатывающего петабайты. Константа 50 GiB выбрана из соображения, что такой объем обрабатывается на одном ядре примерно за десятки минут.

• show_tables — конфигурация поведения запроса SHOW TABLES. Позволяет настроить список директорий, в которых SHOW TABLES будет показывать список таблиц.

  — roots — список YPath-путей директорий в Кипарисе, из которых будут собираться таблицы для показа по SHOW TABLES.

Продвинутая конфигурация ClickHouse-части инстанса

Для настройки конфигурации ClickHouse-части предназначена опция clickhouse_config. Задавать эту опцию необходимо таким образом, чтобы она соответствовала стандартной XML конфигурации ClickHouse.

Правила преобразования XML конфигурации ClickHouse в YSON конфигурацию CHYT можно описать следующим образом:

• Любой не множественный по смыслу в конфигурации ClickHouse узел конфигурации является словарем (map).
• Множественный узел представлен списком (list).

Ниже представлен пример преобразования искусственной XML конфигурации в YSON конфигурацию:

<foo>42</foo>
<bar>qwe</bar>
<baz>
    <quux>3.14</quux>
</baz>
<baz></baz>
<baz>hi!</baz>

{
    foo = 42;
    bar = "qwe";
    baz = [
        {quux = 3.14};
        {};
        "hi!";
    ];
}

Отметим подопции clickhouse_config, которые могут оказаться удобны в CHYT:

• dictionaries ([]) — конфигурация внешних словарей. Значением должен быть список конфигураций словарей. Каждый словарь конфигурируется map'ом со следующими полями, сохраняющими смысл оригинальной конфигурации ClickHouse:
  • name — имя внешнего словаря;
  • source — источник данных для внешнего словаря;
  • layout — представление внешнего словаря в памяти инстанса;
  • structure — схема данных, хранящихся в словаре;
  • lifetime — время жизни словаря.

Внешние словари

CHYT поддерживает все настройки layout, structure и lifetime обычного ClickHouse.

Также есть дополнительный тип источника данных, в котором можно использовать статические таблицы в YTsaurus. Данный тип называется yt и имеет один параметр:

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

В качестве примера подключения YTsaurus таблицы как внешнего словаря ClickHouse можно посмотреть на:

• Пример конфигурации CHYT, подключающий данную таблицу как внешний словарь ClickHouse.
• Пример использования внешнего словаря в запросах:

select dictGet('OS', 'OS', toUInt64(38)) as os_name,
    dictGetHierarchy('OS', toUInt64(38)) as hierarchy,
    dictGetChildren('OS', toUInt64(101)) as children

Пример конфигурации

Ниже приведен пример полной конфигурации, которую можно указать c помощью команды set-speclet.

{
    instance_count = 1;
    query_settings = {
        extremes = 1;
    };
    yt_config = {
        subquery = {
            max_data_weight_per_subquery = 1000000000000;
        };
    };
    clickhouse_config = {
        dictionaries = [
            {
                name = OS;
                layout = {flat = {}};
                structure = {
                    id = {name = Id};
                    attribute = [
                        {
                            name = "OS";
                            type = "Nullable(String)";
                            null_value = "NULL";
                        };
                        {
                            name = "ParentId";
                            type = "Nullable(UInt64)";
                            null_value = "NULL";
                            hierarchical = %true;
                        };
                        {
                            name = "RootId";
                            type = "Nullable(UInt64)";
                            null_value = "NULL";
                        };
                    ];
                };
                lifetime = 0;
                source = {yt = {path = "//sys/clickhouse/dictionaries/OS"}};
            };
        ];
    };
}