Версия: v2.8.x

Настройки «ClickHouse»

Общие сведения

Для ознакомления с данной документацией рекомендуется изучить следующие материалы:

Схема таблиц

Имя таблицы	Тип таблицы	Описание
`messagesTable`	`ReplicatedMergeTree`	Основная реплицируемая таблица для хранения событий в Системе Логикор. Состав данных на каждом узле зависит от настроек кластера
`messages`	`Distributed`	Распределенная таблица для чтения событий со всех шардов кластера. Запросы к событиям необходимо выполнять через эту таблицу
`tagsTable`	`ReplicatedMergeTree`	Основная таблица для хранения списка используемых тегов
`tags`	`Distributed`	Распределенная таблица для чтения информации по тегам со всего кластера баз данных
`mv_tagsTable`	`MATERIALIZED VIEW`	Материализованное представление для сохранения используемых тегов из таблицы `messagesTable` в таблицу `tagsTable`

Настройки ClickHouse

Настройки ClickHouse состоят из нескольких элементов:

общие настройки сервера: /etc/clickhouse-server/config.xml.

Содержит основные настройки сервера, портов, таблиц журналирования и метрик, а также параметры использования ресурсов и потоков;
настройки кластера: /etc/clickhouse-server/config.d/config-cluster.xml.

Содержит адреса узлов ClickHouse, входящих в шарды и реплики кластера Логикор, а также узлов ClickHouse-Keeper, обеспечивающих координацию работы базы данных;
настройки макросов: /etc/clickhouse-server/config.d/config-macros.xml.

Содержит идентификаторы шарда и реплики конкретного узла ClickHouse;
настройки хранения: /etc/clickhouse-server/config.d/config-ilm.xml.

Определяет используемые диски и правила размещения данных по разделам и дискам;
настройки профилей: /etc/clickhouse-server/users.d/default-profile.xml.

Содержит профили пользователей с предустановленными параметрами, например настройками выполнения запросов;
настройки пользователей: /etc/clickhouse-server/users.d/default-user.xml.

Содержит настройки двух предустановленных пользователей: logger для записи данных в базу данных и logger_reader для чтения;
настройки таблиц.

Часть параметров задается на уровне отдельных таблиц. Для просмотра их определения и настроек используется запрос SHOW TABLE {tablename}.

Формат и правила заполнения конфигурационных файлов описаны в документации ClickHouse.

Общие настройки сервера

Общие настройки сервера задаются в файле /etc/clickhouse-server/config.xml.

Доступные параметры и их значения описаны в документации ClickHouse.

Настройки кластера

Настройки кластера logger_cluster и координаторов ClickHouse-Keeper задаются в файле /etc/clickhouse-server/config.d/config-cluster.xml.

Подробная информация об устройстве кластеров ClickHouse приведена в документации. Также можно ознакомиться с описанием заполнения конфигурации кластера.

Настройки кластера базы данных

Пример настроек кластера logger_cluster:

<clickhouse>
    <remote_servers>
        <logger_cluster>
            <shard>
                <replica>
                    <host>clickhouse-1-1</host>
                    <port>9000</port>
                    <user from_env="CLICKHOUSE_USER" replace="1"/>
                    <password from_env="CLICKHOUSE_PASSWORD" replace="1"/>
                </replica>
                <replica>
                    <host>clickhouse-1-2</host>
                    <port>9000</port>
                    <user from_env="CLICKHOUSE_USER" replace="1"/>
                    <password from_env="CLICKHOUSE_PASSWORD" replace="1"/>
                </replica>
            </shard>
        </logger_cluster>
        ...
    </remote_servers>
</clickhouse>  

В данном примере кластер logger_cluster состоит из одного шарда с двумя репликами. Их количество может меняться в зависимости от потребностей конкретного развертывания.

В параметре host указывается IP-адрес или имя узла ClickHouse, входящего в кластер.

Учетные данные для доступа к серверам передаются через переменные окружения, но могут передаваться и другим доступным способом.

Настройки ClickHouse-Keeper для кластера

В этом же файле задаются параметры подключения к узлам ClickHouse-Keeper:

    <zookeeper>
        <node>
            <host>clickhouse-keeper-1</host>
            <port>9181</port>
        </node>
        <node>
            <host>clickhouse-keeper-2</host>
            <port>9181</port>
        </node>
        <node>
            <host>clickhouse-keeper-3</host>
            <port>9181</port>
        </node>
    </zookeeper>

В данном примере используются три узла ClickHouse-Keeper для координации работы реплицируемых таблиц.

Настройки удаленных серверов

Для использования тенантов в Системе Логикор необходимо указать список доступных внешних серверов ClickHouse. Настройка задается в этом же файле. По умолчанию разрешен доступ ко всем внешним серверам:

    <remote_url_allow_hosts>
        <host>127.0.0.1</host>
        <host_regexp>.*</host_regexp>
    </remote_url_allow_hosts>

Настройки макросов

Настройки макросов задаются отдельно для каждого узла кластера ClickHouse в файле /etc/clickhouse-server/config.d/config-macros.xml.

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

<clickhouse>
    <macros>
        <shard>1</shard>
        <replica>2</replica>
    </macros>
</clickhouse>

В данном примере настройки переменных макросов относятся ко второй реплике первого шарда.

При необходимости содержимое файла можно изменить в соответствии с документацией ClickHouse.

Настройки хранения

Данные настройки отвечают за выбор дисков и разделов, резервирование свободного места и задание значения параметра move_factor.

Подробнее об организации хранения данных можно прочитать в документации ClickHouse. Описание доступных параметров приведено в разделе о настройках хранения.

Настройки дисков

В файле /etc/clickhouse-server/config.d/config-ilm.xml для каждого диска задаются настройки: путь (path) и объем резервируемого свободного места в байтах (keep_free_space_bytes), который ClickHouse не должен занимать данными.

        <disks>
           <hot_disk>
              <path>/data/hot/</path>
              <keep_free_space_bytes>20000000000</keep_free_space_bytes>
           </hot_disk>
           <warm_disk>
              <path>/data/warm/</path>
	          <keep_free_space_bytes>20000000000</keep_free_space_bytes>
           </warm_disk>
           <cold_disk>
              <path>/data/cold/</path>
              <keep_free_space_bytes>20000000000</keep_free_space_bytes>
           </cold_disk>
        </disks>

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

Это связано с тем, что при слиянии нескольких партов сначала создается новый парт, в который записываются данные. После завершения записи исходные парты удаляются.

Рекомендуется резервировать свободное место в объеме не меньше размера одной средней партиции данных.

Настройки разделов

Для существующих дисков можно настроить несколько политик хранения. Каждая из них будет определяться используемыми разделами на дисках.

В данном примере заданы две политики хранения: logiq_policy и default:

            <logiq_policy>
                <volumes>
                    <hot_volume>
                        <disk>hot_disk</disk>
                    </hot_volume>
                    <warm_volume>
                        <disk>warm_disk</disk>
                    </warm_volume>
                    <cold_volume>
                        <disk>cold_disk</disk>
                    </cold_volume>
                </volumes>
                <move_factor>0.2</move_factor>
            </logiq_policy>
            <default>
                <volumes>
                    <default>
                        <disk>default</disk>
                    </default>
                </volumes>
            </default>

В политике logiq_policy параметр move_factor имеет значение 0.2. При заполнении раздела более чем на 80% данные автоматически перемещаются на следующий свободный раздел. Порядок использования определяется по мере их перечисления в списке volumes.

Если все разделы заполнены более чем на 80%, при попытке записи ClickHouse выдаст ошибку о недостаточном объеме свободного места.

Данные таблиц размещаются на дисках и разделах в соответствии с заданной для них политикой хранения. Если она не указана, используется политика по умолчанию default.

Диск default

В отличие от остальных дисков из предыдущего примера, перечисленных в списке disks, путь к диску default задается параметром path в файле /etc/clickhouse-server/config.xml.

Пример определения диска default:

<path>/var/lib/clickhouse/</path>

Настройки профилей

В файле /etc/clickhouse-server/users.d/default-profile.xml определены два профиля Системы Логикор: default и logger_reader. Последний предназначен для чтения данных.

Пример настройки профилей:

  <profiles>
        <default>
            <!-- Async Inserts options -->
            <async_insert>1</async_insert>                                      
            <async_insert_max_data_size>2000000000</async_insert_max_data_size>   
            <async_insert_use_adaptive_busy_timeout>1</async_insert_use_adaptive_busy_timeout> 
            <async_insert_busy_timeout_ms>5000</async_insert_busy_timeout_ms>
            <async_insert_busy_timeout_min_ms>3000</async_insert_busy_timeout_min_ms>
            <async_insert_busy_timeout_max_ms>10000</async_insert_busy_timeout_max_ms>    
            <async_insert_deduplicate>0</async_insert_deduplicate>              
            <wait_for_async_insert>0</wait_for_async_insert>                    

            <!-- Date/Time options -->
            <date_time_output_format>iso</date_time_output_format>             
            <date_time_input_format>best_effort</date_time_input_format>       
            <format_csv_null_representation/>                                  

            <!-- Queries options -->
            <materialize_ttl_after_modify>0</materialize_ttl_after_modify> 

            <!-- Data Types Options -->
            <enable_json_type>1</enable_json_type> <!-- используется в версиях ДО 26.3 -->
        </default>

        <logger_reader>
        </logger_reader>
    </profiles>

Настройки профилей и доступные параметры сессии описаны в документации ClickHouse.

Настройки профиля применяются к сессии подключения и выполняемым в ней запросам к базе данных.

Предустановленные значения, указанные в рамках каждого профиля, не требуется передавать с каждым запросом. Если соответствующие параметры указаны в самом запросе, они имеют приоритет над значениями профиля.

Настройки пользователей

В файле /etc/clickhouse-server/users.d/default-user.xml задаются настройки предустановленных пользователей для каждого узла ClickHouse.

Подробное описание параметров настройки пользователей через XML приведено в документации ClickHouse.

Пример настройки пользователя logger_reader:

      <users>
        <logger_reader>
          <profile>logger_reader</profile>
          <networks>
            <ip>::/0</ip>
          </networks>
          <password from_env="CLICKHOUSE_READER_PASSWORD" replace="true"/>
          <quota>default</quota>
          <access_management>0</access_management>
          <named_collection_control>1</named_collection_control>
        </logger_reader>
      </users>

Для каждого пользователя указываются один из профилей, определенных выше, учетные данные и дополнительные настройки прав.

Настройки таблиц

При создании каждой таблицы можно задать собственные настройки.

Для просмотра параметров таблицы, например messagesTable, необходимо выполнить запрос:

SHOW TABLE logger.messagesTable

В результате будут отображены схема таблицы и ее настройки:

CREATE TABLE logger.messagesTable
(
    `timestamp` DateTime('UTC'),
    `uuid` UUID,
...
)
ENGINE = ReplicatedMergeTree('/clickhouse/tables/messagesTable/{shard}', '{replica}')

PARTITION BY toStartOfInterval(timestamp, toIntervalDay(1))

ORDER BY (timestamp, uuid)

TTL 
  timestamp + toIntervalDay(2) RECOMPRESS CODEC(ZSTD(3)), 
  timestamp + toIntervalDay(7) TO DISK 'cold_disk', 
  timestamp + toIntervalMonth(6)
  
SETTINGS index_granularity = 8192, 
         ttl_only_drop_parts = 1, 
         merge_with_ttl_timeout = 86400, 
         storage_policy = 'logiq_policy'

В данном примере messagesTable является реплицируемой таблицей (ReplicatedMergeTree). В ее конфигурации используются макросы {shard} и {replica}, описанные в разделе «Настройки макросов».

Информация о синхронизации в ClickHouse-Keeper размещается по пути /clickhouse/tables/messagesTable/{shard}/{replica}.

Партиционирование

Параметр PARTITION BY toStartOfInterval(timestamp, toIntervalDay(1)) задает партиционирование, то есть объединение данных в большие логические разделы таблицы. В данном примере оно ежедневное: события каждого дня объединяются в одну логическую партицию с целью оптимизации выполнения запросов.

Фактически партиция состоит из множества партов данных, которые со временем объединяются между собой.

Подробная информация о партиционировании приведена в документации ClickHouse.

Первичный ключ

Параметр ORDER BY (timestamp, uuid) задает ключ сортировки таблицы. В данном примере им является пара полей timestamp и uuid.

TTL

Далее задаются правила TTL (time to live) таблицы. В данной таблице сроки отсчитываются от даты события, указанной в поле timestamp.

Предусмотрены следующие действия:

рекомпрессия данных с использованием ZSTD(3) через 2 дня:

timestamp + toIntervalDay(2) RECOMPRESS CODEC(ZSTD(3));
перемещение партов данных на диск cold_disk через 7 дней:

timestamp + toIntervalDay(7) TO DISK 'cold_disk';
автоматическое удаление данных из таблицы через 6 месяцев:

timestamp + toIntervalMonth(6).

Подробная информация о настройке TTL таблиц приведена в документации ClickHouse.

Другие настройки

Также в разделе SETTINGS приведены индивидуальные настройки, относящиеся к конкретной таблице:

index_granularity = 8192 — системная настройка, отвечающая за гранулярность индекса таблицы;
storage_policy = 'logiq_policy' — настройка политики хранения таблицы. В данном случае используется настроенная ранее политика logiq_policy;
ttl_only_drop_parts = 1 — настройка, отвечающая за удаление партов данных по TTL целиком вместо удаления конкретных строк из парта. При включенной настройке (1) парт удаляется, когда все его строки соответствуют условию TTL на удаление. В данном примере они должны быть старше 6 месяцев;
merge_with_ttl_timeout = 86400 — минимальная задержка в секундах перед повторным запуском слияния с TTL на удаление. В данном примере она составляет сутки. Если задачу TTL по удалению парта выполнить не удалось, она будет повторена через указанный интервал времени;
merge_with_recompression_ttl_timeout=14400 — минимальная задержка в секундах перед повторным выполнением слияния с перекомпрессией по TTL. Указанное значение соответствует 4 часам. Если задачу TTL по перекомпрессии парта выполнить не удалось, она будет повторена через указанный интервал времени;
try_fetch_recompressed_part_timeout=7200 — таймаут в секундах перед началом слияния с перекомпрессией. В течение этого времени ClickHouse пытается получить перекомпрессированный парт с реплики, которой назначена данная операция, не запуская собственное слияние;
max_bytes_to_merge_at_max_space_in_pool=161061273600 — максимальный суммарный размер партов в байтах, которые могут быть объединены в один парт при наличии достаточных ресурсов;
max_number_of_merges_with_ttl_in_pool=2 — максимальное количество задач слияния с TTL в пуле на одном узле. Если их количество превышает указанное значение, новые задачи с TTL не назначаются. Это позволяет оставить свободные потоки для обычных слияний и избежать ошибки Too many parts. Для продуктивных систем рекомендуется установить max_number_of_merges_with_ttl_in_pool = 16;
max_replicated_merges_with_ttl_in_queue=1 — максимальное количество задач слияния партов с TTL в очереди отдельной таблицы ReplicatedMergeTree на конкретной реплике. Для продуктивных систем рекомендуется установить max_replicated_merges_with_ttl_in_queue = 32;
number_of_free_entries_in_pool_to_lower_max_size_of_merge=8 — количество свободных элементов в пуле для выполнения больших слияний. Когда их число в пуле или реплицированной очереди становится меньше заданного значения, уменьшается максимальный суммарный размер партов для обработки или постановки в очередь. Это позволяет выполнять небольшие слияния, не заполняя пул длительными крупными операциями;
string_serialization_version = 'with_size_stream' — параметр, управляющий форматом сериализации и хранения строк типа String в файлах данных таблиц семейства MergeTree. В продуктивных средах рекомендуется использовать string_serialization_version = 'with_size_stream' совместно с propagate_types_serialization_versions_to_nested_types = 0;
propagate_types_serialization_versions_to_nested_types = 1 — параметр таблиц семейства MergeTree, управляющий распространением настроенных версий сериализации на вложенные типы данных.

Подробную информацию по настройкам таблиц можно найти в документации ClickHouse.

Изменение TTL

Для изменения TTL таблицы используется следующая конструкция:

ALTER TABLE [db.]table_name [ON CLUSTER cluster] MODIFY TTL ttl_expression;

Пример изменения правил TTL для основной таблицы messagesTable:

ALTER TABLE logger.messagesTable ON CLUSTER logger_cluster 
MODIFY TTL 
  timestamp + toIntervalDay(2) RECOMPRESS CODEC(ZSTD(8)), 
  timestamp + toIntervalDay(4) TO DISK 'cold_disk', 
  timestamp + toIntervalMonth(1)
SETTINGS materialize_ttl_after_modify=0

В данном примере изменены параметры TTL для основной таблицы.

внимание

Обратите внимание, что в запросе используется настройка materialize_ttl_after_modify=0. Она указывает, что при изменении TTL не требуется запускать обработку по новым правилам для уже сформированных и сохраненных партов. В противном случае при больших объемах хранимых данных это может привести к высокой нагрузке на ClickHouse и потере работоспособности.

Новые значения TTL применяются к вновь создаваемым партам. При последующих слияниях они также могут применяться к старым данным.

Данная настройка также задана в профиле default. Однако ее значение при выполнении запроса зависит от используемого профиля пользователя. Поэтому рекомендуется указывать эту настройку дополнительно.

Общие сведения​

Схема таблиц​

Настройки ClickHouse​

Общие настройки сервера​

Настройки кластера​

Настройки кластера базы данных​

Настройки ClickHouse-Keeper для кластера​

Настройки удаленных серверов​

Настройки макросов​

Настройки хранения​

Настройки дисков​

Настройки разделов​

Диск default​

Настройки профилей​

Настройки пользователей​

Настройки таблиц​

Партиционирование​

Первичный ключ​

TTL​

Другие настройки​

Изменение TTL​

Рекомендации​