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

Вся конфигурация клики описывается одним 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)] — количество оперативной памяти в байтах, которое будет выделено под каждый инстанс клики. Настройка предназначена только для продвинутых пользователей. Если вы не уверены, что она вам нужна, то рекомендуется оставить значение по умолчанию.

  • enable_sticky_query_distribution [%false] — распределить запросы по инстансам с учётом хешей этих запросов. Это позволяет увеличить эффективность использования кеша.

  • query_sticky_group_size [2] — размер группы инстансов, выбранных детерменированно по хешу запроса. Среди этих инстансов будет равномерно выбран координатор для исполнения запроса. Имеет смысл только при enable_sticky_query_distribution=%true.

Продвинутая конфигурация 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.

Внимание

Ограничение на max_data_weight_per_subquery использует поколоночные статистики для учета колоночной выборки из обрабатываемых таблиц. Поколоночная статистика может отсутствовать для старых таблиц, созданных до ее появления. Для таких таблиц поколоночность в ограничении не учитывается. Это означает, что при обработке очень узкого среза колонок, образующего 1% от общего объема таблицы и составляющего 1 GiB в пересчете на ядро, CHYT посчитает, что обрабатывается 100 GiB на ядро. CHYT не запустит такой запрос с настройками по умолчанию.

Если необходим именно такой сценарий, либо необходимо обрабатывать большие объемы данных, стоит выставить эту настройку в произвольно большее значение.

Продвинутая конфигурация 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:

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

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

Примечание

В качестве source можно указывать источники от оригинального 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"}};
            };
        ];
    };
}
Предыдущая
Настройки запросов
Следующая
Типы данных