ClickHouse/docs/ru/operations/settings/settings.rst

.. _settings-distributed_product_mode:

distributed_product_mode
------------------------
Изменяет поведение :ref:`распределенных подзапросов <queries-distributed-subrequests>`, т.е. в тех случаях, когда запрос содержит произведение распределённых таблиц.

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

Условия применения:

* Только подзапросы для IN, JOIN.
* Только если в секции FROM используется распределённая таблица.
* Не используется в случае табличной функции :ref:`remote <table_functions-remote>`.

Возможные значения:

.. list-table::
    :widths: 20 80
    :header-rows: 1

    * - Значение
      - Поведение ClickHouse
    * - ``deny`` (по умолчанию)
      - Генерирует исключение.
    * - ``allow``
      - Выполняет запрос без изменения логики.
    * - ``global``
      - Преобразует ``IN`` в ``GLOBAL IN``, ``JOIN`` в ``GLOBAL JOIN``.
    * - ``local``
      - Преобразует все вхождения Distributed-таблиц в соответствующие им удалённые таблицы.


.. _settings-settings-fallback_to_stale_replicas_for_distributed_queries:

fallback_to_stale_replicas_for_distributed_queries
--------------------------------------------------
Форсирует запрос в устаревшую реплику в случае, если актуальные данные недоступны.  Смотрите :ref:`table_engines-replication`.

Из устаревших реплик таблицы ClickHouse выбирает наиболее актуальную.

Используется при выполнении ``SELECT`` из распределенной таблицы, которая указывает на реплицированные таблицы.

По умолчанию - 1 (включена).


.. _settings-settings-force_index_by_date:

force_index_by_date
-------------------

Запрещает выполнение запросов, если использовать индекс по дате невозможно.

Работает с таблицами семейства MergeTree.

При ``force_index_by_date=1`` ClickHouse проверяет, есть ли в запросе условие на ключ даты, которое может использоваться для отсечения диапазонов данных. Если подходящего условия нет - кидается исключение. При этом не проверяется, действительно ли условие уменьшает объём данных для чтения. Например, условие ``Date != '2000-01-01'`` подходит даже в том случае, когда соответствует всем данным в таблице (т.е. для выполнения запроса требуется full scan). Подробнее про диапазоны данных в таблицах MergeTree читайте в разделе :ref:`table_engines-mergetree`.


.. _settings-settings-force_primary_key:

force_primary_key
-----------------

Запрещает выполнение запросов, если использовать индекс по первичному ключу невозможно.

Работает с таблицами семейства MergeTree.

При ``force_primary_key=1`` ClickHouse проверяет, есть ли в запросе условие на первичный ключ, которое может использоваться для отсечения диапазонов данных. Если подходящего условия нет - кидается исключение. При этом не проверяется, действительно ли условие уменьшает объём данных для чтения. Подробнее про диапазоны данных в таблицах MergeTree читайте в разделе :ref:`table_engines-mergetree`.


.. _settings_settings_fsync_metadata:

fsync_metadata
--------------

Включить или отключить fsync при записи .sql файлов. По-умолчанию включено. 

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

input_format_allow_errors_num
-----------------------------
Устанавливает максимальное количество допустимых ошибок при чтении из текстовых форматов (CSV, TSV и т.п.).

Значение по умолчанию - 0.

Используйте обязательно в паре с ``input_format_allow_errors_ratio``. Для пропуска ошибок, значения обеих настроек должны быть больше 0.

Если при чтении строки возникла ошибка, но при этом счетчик ошибок меньше ``input_format_allow_errors_num``, то ClickHouse игнорирует строку и переходит к следующей.

В случае превышения ``input_format_allow_errors_num`` ClickHouse генерирует исключение.


input_format_allow_errors_ratio
-------------------------------
Устанавливает максимальную долю допустимых ошибок при чтении из текстовых форматов (CSV, TSV и т.п.).
Доля ошибок задаётся в виде числа с плавающей запятой от 0 до 1.

Значение по умолчанию - 0.

Используйте обязательно в паре с ``input_format_allow_errors_num``. Для пропуска ошибок, значения обеих настроек должны быть больше 0.

Если при чтении строки возникла ошибка, но при этом текущая доля ошибок меньше ``input_format_allow_errors_ratio``, то ClickHouse игнорирует строку и переходит к следующей.

В случае превышения ``input_format_allow_errors_ratio`` ClickHouse генерирует исключение.



max_block_size
--------------
Данные в ClickHouse обрабатываются по блокам (наборам кусочков столбцов). Внутренние циклы обработки одного блока достаточно эффективны, но при этом существуют заметные издержки на каждый блок. ``max_block_size`` - это рекомендация, какого размера блоки (в количестве строк) загружать из таблицы. Размер блока должен быть не слишком маленьким, чтобы издержки на каждый блок оставались незаметными, и не слишком большим, чтобы запрос с LIMIT-ом, который завершается уже после первого блока, выполнялся быстро; чтобы не использовалось слишком много оперативки при вынимании большого количества столбцов в несколько потоков; чтобы оставалась хоть какая-нибудь кэш-локальность.

По умолчанию - 65 536.

Из таблицы не всегда загружаются блоки размера ``max_block_size``. Если ясно, что нужно прочитать меньше данных, то будет считан блок меньшего размера.

preferred_block_size_bytes
--------------------------
Служит для тех же целей что и ``max_block_size``, но задает реккомедуемый размер блоков в байтах, выбирая адаптивное количество строк в блоке.
При этом размер блока не может быть более ``max_block_size`` строк.
По-умолчанию выключен (равен 0), работает только при чтении из MergeTree-движков.

.. _settings-log_queries:

log_queries
------------

Установка логгирования запроса.

Запросы, переданные в ClickHouse с этой установкой, логгируются согласно правилам конфигурационного параметра сервера :ref:`server_settings-query_log`.

**Пример** ::

  log_queries=1

max_insert_block_size
---------------------
Формировать блоки указанного размера, при вставке в таблицу.
Эта настройка действует только в тех случаях, когда сервер сам формирует такие блоки.
Например, при INSERT-е через HTTP интерфейс, сервер парсит формат данных, и формирует блоки указанного размера.
А при использовании clickhouse-client, клиент сам парсит данные, и настройка max_insert_block_size на сервере не влияет на размер вставляемых блоков.
При использовании INSERT SELECT, настройка так же не имеет смысла, так как данные будут вставляться теми блоками, которые вышли после SELECT-а.

По умолчанию - 1 048 576.

Это намного больше, чем ``max_block_size``. Это сделано, потому что некоторые движки таблиц (``*MergeTree``) будут на каждый вставляемый блок формировать кусок данных на диске, что является довольно большой сущностью. Также, в таблицах типа ``*MergeTree``, данные сортируются при вставке, и достаточно большой размер блока позволяет отсортировать больше данных в оперативке.


.. _settings_settings_max_replica_delay_for_distributed_queries:

max_replica_delay_for_distributed_queries 
-----------------------------------------
Отключает отстающие реплики при распределенных запросах. Смотрите :ref:`table_engines-replication`.

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

Значение по умолчанию: 0 (отключено).

Используется при выполнении ``SELECT`` из распределенной таблицы, которая указывает на реплицированные таблицы.


max_threads
-----------
Максимальное количество потоков обработки запроса
- без учёта потоков для чтения данных с удалённых серверов (смотрите параметр max_distributed_connections).

Этот параметр относится к потокам, которые выполняют параллельно одни стадии конвейера выполнения запроса.
Например, если чтение из таблицы, вычисление выражений с функциями, фильтрацию с помощью WHERE и предварительную агрегацию для GROUP BY можно делать параллельно с использованием как минимум max_threads потоков, то будет использовано max_threads потоков.

По умолчанию - 8.

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

Для запросов, которые быстро завершаются из-за LIMIT-а, имеет смысл выставить max_threads поменьше. Например, если нужное количество записей находится в каждом блоке, то при max_threads = 8 будет считано 8 блоков, хотя достаточно было прочитать один.

Чем меньше ``max_threads``, тем меньше будет использоваться оперативки.

max_compress_block_size
-----------------------
Максимальный размер блоков не сжатых данных перед сжатием при записи в таблицу. По умолчанию - 1 048 576 (1 MiB). При уменьшении размера, незначительно уменьшается коэффициент сжатия, незначительно возрастает скорость сжатия и разжатия за счёт кэш-локальности, и уменьшается потребление оперативки. Как правило, не имеет смысла менять эту настройку.

Не путайте блоки для сжатия (кусок памяти, состоящий из байт) и блоки для обработки запроса (пачка строк из таблицы).

min_compress_block_size
-----------------------
Для таблиц типа :ref:`MergeTree <table_engines-mergetree>`. В целях уменьшения задержек при обработке запросов, блок сжимается при записи следующей засечки, если его размер не меньше min_compress_block_size. По умолчанию - 65 536.

Реальный размер блока, если несжатых данных меньше max_compress_block_size, будет не меньше этого значения и не меньше объёма данных на одну засечку.

Рассмотрим пример. Пусть index_granularity, указанная при создании таблицы - 8192.

Пусть мы записываем столбец типа UInt32 (4 байта на значение). При записи 8192 строк, будет всего 32 КБ данных. Так как min_compress_block_size = 65 536, сжатый блок будет сформирован на каждые две засечки.

Пусть мы записываем столбец URL типа String (средний размер - 60 байт на значение). При записи 8192 строк, будет, в среднем, чуть меньше 500 КБ данных. Так как это больше 65 536 строк, то сжатый блок будет сформирован на каждую засечку. В этом случае, при чтении с диска данных из диапазона в одну засечку, не будет разжато лишних данных.

Как правило, не имеет смысла менять эту настройку.

max_query_size
--------------
Максимальный кусок запроса, который будет считан в оперативку для разбора парсером языка SQL.
Запрос INSERT также содержит данные для INSERT-а, которые обрабатываются отдельным, потоковым парсером (расходующим O(1) оперативки), и не учитываются в этом ограничении.

По умолчанию - 256 KiB.

interactive_delay
-----------------
Интервал в микросекундах для проверки, не запрошена ли остановка выполнения запроса, и отправки прогресса.

По умолчанию - 100 000 (проверять остановку запроса и отправлять прогресс десять раз в секунду).

connect_timeout
---------------

receive_timeout
---------------

send_timeout
------------
Таймауты в секундах на сокет, по которому идёт общение с клиентом.

По умолчанию - 10, 300, 300.

poll_interval
-------------
Блокироваться в цикле ожидания запроса в сервере на указанное количество секунд.

По умолчанию - 10.

max_distributed_connections
---------------------------
Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке одного запроса к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере.

По умолчанию - 100.

Следующие параметры имеют значение только на момент создания таблицы типа Distributed (и при запуске сервера), поэтому их не имеет смысла менять в рантайме.

distributed_connections_pool_size
---------------------------------
Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке всех запросов к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере.

По умолчанию - 128.

connect_timeout_with_failover_ms
--------------------------------
Таймаут в миллисекундах на соединение с удалённым сервером, для движка таблиц Distributed, если используются секции shard и replica в описании кластера.
В случае неуспеха, делается несколько попыток соединений с разными репликами.

По умолчанию - 50.

connections_with_failover_max_tries
-----------------------------------
Максимальное количество попыток соединения с каждой репликой, для движка таблиц Distributed.

По умолчанию - 3.

extremes
--------
Считать ли экстремальные значения (минимумы и максимумы по столбцам результата запроса). Принимает 0 или 1. По умолчанию - 0 (выключено).
Подробнее смотрите раздел "Экстремальные значения".

.. _settings-use_uncompressed_cache:

use_uncompressed_cache
----------------------
Использовать ли кэш разжатых блоков. Принимает 0 или 1. По умолчанию - 0 (выключено).
Кэш разжатых блоков (только для таблиц семейства MergeTree) позволяет существенно уменьшить задержки и увеличить пропускную способность при обработке большого количества коротких запросов. Включите эту настройку для пользователей, от которых идут частые короткие запросы. Также обратите внимание на конфигурационный параметр uncompressed_cache_size (настраивается только в конфигурационном файле) - размер кэша разжатых блоков. По умолчанию - 8 GiB. Кэш разжатых блоков заполняется по мере надобности; наиболее невостребованные данные автоматически удаляются.

Для запросов, читающих хоть немного приличный объём данных (миллион строк и больше), кэш разжатых блоков автоматически выключается, чтобы оставить место для действительно мелких запросов. Поэтому, можно держать настройку use_uncompressed_cache всегда выставленной в 1.

replace_running_query
---------------------
При использовании HTTP-интерфейса, может быть передан параметр query_id - произвольная строка, являющаяся идентификатором запроса.
Если в этот момент, уже существует запрос от того же пользователя с тем же query_id, то поведение определяется параметром replace_running_query.

``0`` - (по умолчанию) кинуть исключение (не давать выполнить запрос, если запрос с таким же query_id уже выполняется);

``1`` - отменить старый запрос и начать выполнять новый.

Эта настройка, выставленная в 1, используется в Яндекс.Метрике для реализации suggest-а значений для условий сегментации. После ввода очередного символа, если старый запрос ещё не выполнился, его следует отменить.

.. _settings-load_balancing:

load_balancing
--------------
На какие реплики (среди живых реплик) предпочитать отправлять запрос (при первой попытке) при распределённой обработке запроса.

random (по умолчанию)
~~~~~~~~~~~~~~~~~~~~~
Для каждой реплики считается количество ошибок. Запрос отправляется на реплику с минимальным числом ошибок, а если таких несколько, то на случайную из них.
Недостатки: не учитывается близость серверов; если на репликах оказались разные данные, то вы будете получать так же разные данные.

nearest_hostname
~~~~~~~~~~~~~~~~
Для каждой реплики считается количество ошибок. Каждые 5 минут, число ошибок целочисленно делится на 2 - таким образом, обеспечивается расчёт числа ошибок за недавнее время с экспоненциальным сглаживанием. Если есть одна реплика с минимальным числом ошибок (то есть, на других репликах недавно были ошибки) - запрос отправляется на неё. Если есть несколько реплик с одинаковым минимальным числом ошибок, то запрос отправляется на реплику, имя хоста которой в конфигурационном файле минимально отличается от имени хоста сервера (по количеству отличающихся символов на одинаковых позициях, до минимальной длины обеих имён хостов).

Для примера, example01-01-1 и example01-01-2.yandex.ru отличаются в одной позиции, а example01-01-1 и example01-02-2 - в двух.
Этот способ может показаться несколько дурацким, но он не использует внешние данные о топологии сети, и не сравнивает IP-адреса, что было бы сложным для наших IPv6-адресов.

Таким образом, если есть равнозначные реплики, предпочитается ближайшая по имени.
Также можно сделать предположение, что при отправке запроса на один и тот же сервер, в случае отсутствия сбоев, распределённый запрос будет идти тоже на одни и те же серверы. То есть, даже если на репликах расположены разные данные, запрос будет возвращать в основном одинаковые результаты.

in_order
~~~~~~~~
Реплики перебираются в таком порядке, в каком они указаны. Количество ошибок не имеет значения.
Этот способ подходит для тех случаев, когда вы точно знаете, какая реплика предпочтительнее.

totals_mode
-----------
Каким образом вычислять TOTALS при наличии HAVING, а также при наличии max_rows_to_group_by и group_by_overflow_mode = 'any'.
Смотрите раздел "Модификатор WITH TOTALS".

totals_auto_threshold
---------------------
Порог для ``totals_mode = 'auto'``.
Смотрите раздел "Модификатор WITH TOTALS".

default_sample
--------------
Число с плавающей запятой от 0 до 1. По умолчанию - 1.
Позволяет выставить коэффициент сэмплирования по умолчанию для всех запросов SELECT.
(Для таблиц, не поддерживающих сэмплирование, будет кидаться исключение.)
Если равно 1 - сэмплирование по умолчанию не делается.

max_parallel_replicas
---------------------
Максимальное количество используемых реплик каждого шарда при выполнении запроса.
Для консистентности (чтобы получить разные части одного и того же разбиения), эта опция работает только при заданном ключе сэмплирования.
Отставание реплик не контролируется.

compile
-------
Включить компиляцию запросов. По умолчанию - 0 (выключено).

Компиляция предусмотрена только для части конвейера обработки запроса - для первой стадии агрегации (GROUP BY).
В случае, если эта часть конвейера была скомпилирована, запрос может работать быстрее, за счёт разворачивания коротких циклов и инлайнинга вызовов агрегатных функций. Максимальный прирост производительности (до четырёх раз в редких случаях) достигается на запросах с несколькими простыми агрегатными функциями. Как правило, прирост производительности незначителен. В очень редких случаях возможно замедление выполнения запроса.

min_count_to_compile
--------------------
После скольких раз, когда скомпилированный кусок кода мог пригодиться, выполнить его компиляцию. По умолчанию - 3.
В случае, если значение равно нулю, то компиляция выполняется синхронно, и запрос будет ждать окончания процесса компиляции перед продолжением выполнения. Это можно использовать для тестирования, иначе используйте значения, начиная с 1. Как правило, компиляция занимает по времени около 5-10 секунд.
В случае, если значение равно 1 или больше, компиляция выполняется асинхронно, в отдельном потоке. При готовности результата, он сразу же будет использован, в том числе, уже выполняющимися в данный момент запросами.

Скомпилированный код требуется для каждого разного сочетания используемых в запросе агрегатных функций и вида ключей в GROUP BY.
Результаты компиляции сохраняются в директории build в виде .so файлов. Количество результатов компиляции не ограничено, так как они не занимают много места. При перезапуске сервера, старые результаты будут использованы, за исключением случая обновления сервера - тогда старые результаты удаляются.

input_format_skip_unknown_fields
--------------------------------
Если значение истинно, то при выполнении INSERT из входных данных пропускаются (не рассматриваются) колонки с неизвестными именами, иначе в данной ситуации будет сгенерировано исключение.
Работает для форматов JSONEachRow и TSKV.

output_format_json_quote_64bit_integers
---------------------------------------
Если значение истинно, то при использовании JSON* форматов UInt64 и Int64 числа выводятся в кавычках (из соображений совместимости с большинством реализаций JavaScript), иначе - без кавычек.

.. _settings-strict_insert_defaults:

strict_insert_defaults
----------------------

Строгое присвоение значений по умолчанию при добавлении данных.

Если при выполнении запроса :ref:`queries-insert` данные для столбца не заданы, то ClickHouse присваивает полям значения по умолчанию.  Значения по умолчанию определяются свойством ``DEFAULT`` для каждого столбца в настройках таблицы. Если для столбца не определен ``DEFAULT``, то когда:

* ``strict_insert_defaults=0`` - полям столбца присваиваются нули и пустые строки.
* ``strict_insert_defaults=1`` - ClickHouse генерирует исключение и обязывает пользователя передать данные в столбец.