ClickHouse/docs/ru/operations/settings/settings.rst
BayoNet 2f19c69bf9 Merge remote-tracking branch 'upstream/master'
Restructured articles of "aggregate functions" are added.

Conflicted changes in index.rst are merged.
2017-09-25 14:52:47 +03:00

364 lines
32 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.. _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 генерирует исключение и обязывает пользователя передать данные в столбец.