From dc49f93b9907ed0df00303f2d376da97c6630541 Mon Sep 17 00:00:00 2001 From: BayoNet Date: Mon, 26 Jun 2017 10:14:13 +0300 Subject: [PATCH 1/5] New part "Server configuration parameters" of the document is added. Other changes are made related to this new part. --- docs/ru/dicts/external_dicts.rst | 13 +- docs/ru/operations/configuration_files.rst | 2 +- docs/ru/operations/server_settings/index.rst | 17 + .../operations/server_settings/settings.rst | 804 ++++++++++++++++++ docs/ru/operations/settings/index.rst | 2 + docs/ru/operations/settings/settings.rst | 16 + docs/ru/query_language/queries.rst | 2 + .../system.asynchronous_metrics.rst | 2 + docs/ru/system_tables/system.events.rst | 2 + docs/ru/system_tables/system.metrics.rst | 2 + docs/ru/table_engines/distributed.rst | 2 + docs/ru/table_engines/graphitemergetree.rst | 30 +- docs/ru/table_engines/replication.rst | 2 + docs/ru/table_engines/resharding.rst | 2 + 14 files changed, 875 insertions(+), 23 deletions(-) create mode 100644 docs/ru/operations/server_settings/index.rst create mode 100644 docs/ru/operations/server_settings/settings.rst diff --git a/docs/ru/dicts/external_dicts.rst b/docs/ru/dicts/external_dicts.rst index f8dc1a5fcb6..4001eeff87f 100644 --- a/docs/ru/dicts/external_dicts.rst +++ b/docs/ru/dicts/external_dicts.rst @@ -1,3 +1,5 @@ +.. _dicts-external_dicts: + Внешние словари =============== @@ -5,12 +7,12 @@ Источником данных для словаря может быть файл на локальной файловой системе, сервер ClickHouse, сервер MySQL, MongoDB или любой ODBC источник. Словарь может полностью храниться в оперативке и периодически обновляться, или быть частично закэшированным в оперативке и динамически подгружать отсутствующие значения. -Конфигурация внешних словарей находится в отдельном файле или файлах, указанных в конфигурационном параметре dictionaries_config. -Этот параметр содержит абсолютный или относительный путь к файлу с конфигурацией словарей. Относительный путь - относительно директории с конфигурационным файлом сервера. Путь может содержать wildcard-ы \* и ? - тогда рассматриваются все подходящие файлы. Пример: dictionaries/\*.xml. +Конфигурация внешних словарей находится в отдельном файле или файлах, указанных в конфигурационном параметре :ref:`dictionaries_config `. +Этот параметр содержит абсолютный или относительный путь к файлу с конфигурацией словарей. Относительный путь - относительно директории с конфигурационным файлом сервера. Путь может содержать wildcard-ы \* и ? - тогда рассматриваются все подходящие файлы. Пример: ``dictionaries/*.xml``. Конфигурация словарей, а также множество файлов с конфигурацией, может обновляться без перезапуска сервера. Сервер проверяет обновления каждые 5 секунд. То есть, словари могут подключаться динамически. -Создание словарей может производиться при старте сервера или при первом использовании. Это определяется конфигурационном параметром dictionaries_lazy_load (в основном конфигурационном файле сервера). Параметр не обязателен, по умолчанию - true. Если true, то каждый словарь создаётся при первом использовании; если словарь не удалось создать - вызов функции, использующей словарь, кидает исключение. Если false, то все словари создаются при старте сервера, и в случае ошибки, сервер завершает работу. +Создание словарей может производиться при старте сервера или при первом использовании. Это определяется конфигурационном параметром :ref:`dictionaries_lazy_load ` (в основном конфигурационном файле сервера). Параметр не обязателен, по умолчанию - ``true``. Если true, то каждый словарь создаётся при первом использовании; если словарь не удалось создать - вызов функции, использующей словарь, кидает исключение. Если ``false``, то все словари создаются при старте сервера, и в случае ошибки, сервер завершает работу. Конфигурационный файл словарей имеет вид: @@ -170,7 +172,7 @@ Существует шесть способов размещения словаря в памяти. flat ----- +----- В виде плоских массивов. Самый эффективный способ. Он подходит, если все ключи меньше 500 000. Если при создании словаря обнаружен ключ больше, то кидается исключение и словарь не создаётся. Словарь загружается в оперативку целиком. Словарь использует количество оперативки, пропорциональное максимальному значению ключа. Ввиду ограничения на 500 000, потребление оперативки вряд ли может быть большим. Поддерживаются все виды источников. При обновлении, данные (из файла, из таблицы) читаются целиком. @@ -189,9 +191,6 @@ range_hashed Пример: таблица содержит скидки для каждого рекламодателя в виде: -.. code-block:: text - -.. code-block:: text +------------------+-----------------------------+------------+----------+ | id рекламодателя | дата начала действия скидки | дата конца | величина | diff --git a/docs/ru/operations/configuration_files.rst b/docs/ru/operations/configuration_files.rst index efe396a89fa..2ef120f7e19 100644 --- a/docs/ru/operations/configuration_files.rst +++ b/docs/ru/operations/configuration_files.rst @@ -15,7 +15,7 @@ Если указано ``remove`` - удалить элемент. -Также в конфиге могут быть указаны "подстановки". Если у элемента присутствует атрибут ``incl``, то в качестве значения будет использована соответствующая подстановка из файла. По умолчанию, путь к файлу с подстановками - ``/etc/metrika.xml``. Он может быть изменён в конфиге в элементе ``include_from``. Значения подстановок указываются в элементах ``/yandex/имя_подстановки`` этого файла. +Также в конфиге могут быть указаны "подстановки". Если у элемента присутствует атрибут ``incl``, то в качестве значения будет использована соответствующая подстановка из файла. По умолчанию, путь к файлу с подстановками - ``/etc/metrika.xml``. Он может быть изменён в конфигурации сервера в элементе :ref:`server_settings-include_from`. Значения подстановок указываются в элементах ``/yandex/имя_подстановки`` этого файла. Если подстановка, заданная в ``incl`` отсутствует, то в лог попадает соответствующая запись. Чтобы ClickHouse не писал в лог об отсутствии подстановки, необходимо указать атрибут ``optional="true"`` (например, настройка :ref:`server_settings-macros`). Подстановки могут также выполняться из ZooKeeper. Для этого укажите у элемента атрибут ``from_zk="/path/to/node"``. Значение элемента заменится на содержимое узла ``/path/to/node`` в ZooKeeper. В ZooKeeper-узел также можно положить целое XML-поддерево, оно будет целиком вставлено в исходный элемент. diff --git a/docs/ru/operations/server_settings/index.rst b/docs/ru/operations/server_settings/index.rst new file mode 100644 index 00000000000..490af776729 --- /dev/null +++ b/docs/ru/operations/server_settings/index.rst @@ -0,0 +1,17 @@ +.. _server_settings: + +Конфигурационные параметры сервера +================================== + +Раздел содержит описания настроек сервера, которые не могут изменяться на уровне сессии или запроса. + +Рассмотренные настройки хранятся в файле ``config.xml`` сервера ClickHouse. + +Прочие настройки описаны в разделе :ref:`settings`. + +Перед изучением настроек ознакомьтесь с разделом :ref:`configuration_files`, обратите внимание на использование подстановок (атрибуты ``incl`` и ``optional``). + +.. toctree:: + :glob: + + * diff --git a/docs/ru/operations/server_settings/settings.rst b/docs/ru/operations/server_settings/settings.rst new file mode 100644 index 00000000000..c99054a18fa --- /dev/null +++ b/docs/ru/operations/server_settings/settings.rst @@ -0,0 +1,804 @@ +.. _server_settings-builtin_dictionaries_reload_interval: + +builtin_dictionaries_reload_interval +------------------------------------ +Интервал (в секундах) перезагрузки встроенных словарей. + +ClickHouse перезагружает встроенные словари с заданным интервалом. Это позволяет править словари "на лету" без перезапуска сервера. + +Значение по умолчанию - 3600. + +**Пример** + +.. code-block:: xml + + 3600 + +.. _server_settings-compression: + +compression +----------- +Настройки компрессии данных. + +.. warning:: Не используйте, если вы только начали работать с ClickHouse. + +Общий вид конфигурации: + +.. code-block:: xml + + + + + + ... + + + +Можно сконфигурировать несколько разделов ````. + +Поля блока ````: + ++---------------------+--------------------------------------------------------------------------+ +| Параметр | Описание | ++=====================+==========================================================================+ +| min_part_size | Минимальный размер части таблицы. | ++---------------------+--------------------------------------------------------------------------+ +| min_part_size_ratio | Отношение размера минимальной части таблицы к полному размеру таблицы. | ++---------------------+--------------------------------------------------------------------------+ +| method | Метод сжатия. Возможные значения: ``lz4``, ``zstd`` (экспериментальный). | ++---------------------+--------------------------------------------------------------------------+ + +ClickHouse проверит условия ``min_part_size`` и ``min_part_size_ratio`` и выполнит те блоки ``case``, для которых условия совпали. Если ни один ```` не подходит, то ClickHouse применит алгоритм сжатия ``lz4``. + +**Пример** + +.. code-block:: xml + + + + 10000000000 + 0.01 + zstd + + + + +.. _server_settings-default_database: + +default_database +---------------- +База данных по умолчанию. + +Перечень баз данных можно получить запросом :ref:`query_language_queries_show_databases`. + +**Пример** + +.. code-block:: xml + + default + + + +.. _server_settings-default_profile: + +default_profile +--------------- +Профиль настроек по умолчанию. + +Профили настроек находятся в файле, указанном в параметре :ref:`server_settings-users_config`. + +**Пример** + +.. code-block:: xml + + default + + +.. _server_settings-dictionaries_config: + +dictionaries_config +------------------- +Конфигурация внешних словарей. + +Смотрите раздел :ref:`dicts-external_dicts`. + +**Пример** + +.. code-block:: xml + + *_dictionary.xml + + +.. _server_settings-dictionaries_lazy_load: + +dictionaries_lazy_load +---------------------- + +Отложенная загрузка словарей. + +С установленным параметром словари подгружаются не при запуске сервера, а при первом обращении. + +**Пример** + +.. code-block:: xml + + true + + +.. _server_settings-graphite: + +graphite +-------- +Отправка даных в `Graphite `_. + +Настройки: + ++----------------------+------------------------------------------------------------------------------+ +| Настройка | Описание | ++======================+==============================================================================+ +| host | Сервер Graphite. | ++----------------------+------------------------------------------------------------------------------+ +| port | Порт сервера Graphite. | ++----------------------+------------------------------------------------------------------------------+ +| interval | Период отправки в секундах. | ++----------------------+------------------------------------------------------------------------------+ +| timeout | Таймаут отправки данных в секундах. | ++----------------------+------------------------------------------------------------------------------+ +| root_path | Префикс для ключей. | ++----------------------+------------------------------------------------------------------------------+ +| metrics | Отправка данных из таблицы :ref:`system_tables-system.metrics`. | ++----------------------+------------------------------------------------------------------------------+ +| events | Отправка данных из таблицы :ref:`system_tables-system.events`. | ++----------------------+------------------------------------------------------------------------------+ +| asynchronous_metrics | Отправка данных из таблицы :ref:`system_tables-system.asynchronous_metrics`. | ++----------------------+------------------------------------------------------------------------------+ + + +Можно определить несколько секций ````, например, для передачи различных данных с различной частотой. + +**Пример** + +.. code-block:: xml + + + localhost + 42000 + 0.1 + 60 + one_min + true + true + true + + + +.. _server_settings-graphite_rollup: + +graphite_rollup +--------------- + +Настройка прореживания данных для Graphite. + +Подробнее читайте в разделе :ref:`table_engines-graphitemergetree`. + +**Пример** + +.. code-block:: xml + + + + max + + 0 + 60 + + + 3600 + 300 + + + 86400 + 3600 + + + + + +.. _server_settings-http_port: + +http_port/https_port +-------------------- +Порт для обращений к серверу по протоколу HTTP(s). + +Если указан ``https_port``, то требуется конфигурирование :ref:`server_settings-openSSL`. + +Если указан ``http_port``, то настройка :ref:`server_settings-openSSL` игнорируется, даже если она задана. + +**Пример** + +.. code-block:: xml + + 0000 + + +.. _server_settings-http_server_default_response: + +http_server_default_response +---------------------------- +Страница, показываемая по умолчанию, при обращении к HTTP(s) серверу ClickHouse. + +**Пример** + +Показывает ``https://tabix.io/`` при обращенинии к ``http://localhost:http_port``. + +.. code-block:: xml + + +
]]> + + +.. _server_settings-include_from: + +include_from +------------ +Путь к файлу с подстановками. + +Подробности смотрите в разделе :ref:`configuration_files`. + +**Пример** + +.. code-block:: xml + + /etc/metrica.xml + + +.. _server_settings-interserver_http_port: + +interserver_http_port +--------------------- + +Порт для обмена между серверами ClickHouse. + +**Пример** + +.. code-block:: xml + + 9009 + + +.. _server_settings-interserver_http_host: + +interserver_http_host +--------------------- + +Имя хоста, которое могут использовать другие серверы для обращения к этому. + +Если не указано, то определяется аналогично команде ``hostname -f``. + +Удобно использовать, чтобы отвязаться от конкретного сетевого интерфейса. + + +**Пример** + +.. code-block:: xml + + example.yandex.ru + + +.. _server_settings-keep_alive_timeout: + +keep_alive_timeout +------------------ + +Время в миллисекундах, в течение которого ClickHouse ожидает входящих запросов прежде, чем закрыть соединение. + +**Пример** + +.. code-block:: xml + + 3 + + +.. _server_settings-listen_host: + +listen_host +----------- + +Ограничение по хостам, с которых может прийти запрос. Если необходимо, чтобы сервер отвечал всем, то надо указать ``::``. + +Примеры: + +.. code-block:: xml + + ::1 + 127.0.0.1 + + +.. _server_settings-logger: + +logger +------ +Настройки логгирования. + +Ключи: + ++----------+-----------------------------------------------------------------------------------------------------------+ +| Ключ | Описание | ++==========+===========================================================================================================+ +| level | Уровень логгирования. Допустимые значения: ``trace``, ``debug``, ``information``, ``warning``, ``error``. | ++----------+-----------------------------------------------------------------------------------------------------------+ +| log | Файл лога. Содержит все записи согласно ``level``. | ++----------+-----------------------------------------------------------------------------------------------------------+ +| errorlog | Файл лога ошибок. | ++----------+-----------------------------------------------------------------------------------------------------------+ +| size | Размер файла. Действует для ``log`` и ``errorlog``. Как только файл достиг размера ``size``, | +| | ClickHouse архивирует и переименовывает его, а на его месте создает новый файл лога. | ++----------+-----------------------------------------------------------------------------------------------------------+ +| count | Количество заархивированных файлов логов, которые сохраняет ClickHouse. | ++----------+-----------------------------------------------------------------------------------------------------------+ + + +**Пример** + +.. code-block:: xml + + + trace + /var/log/clickhouse-server/clickhouse-server.log + /var/log/clickhouse-server/clickhouse-server.err.log + 1000M + 10 + + +.. _server_settings-macros: + +macros +------ +Подстановки параметров реплицируемых таблиц. + +Можно не указывать, если реплицируемых таблицы не используются. + +Подробнее смотрите в разделе :ref:`table_engines-replication-creation_of_rep_tables`. + +**Пример** + +.. code-block:: xml + + + + +.. _server_settings-mark_cache_size: + +mark_cache_size +--------------- +Приблизительный размер (в байтах) кеша "засечек", используемых движками таблиц семейства :ref:`table_engines-mergetree`. + +Кеш общий для сервера, память выделяется по мере необходимости. Кеш не может быть меньше, чем 5368709120. + +**Пример** + +.. code-block:: xml + + 5368709120 + + +.. _server_settings-max_concurrent_queries: + +max_concurrent_queries +---------------------- + +Максимальное количество одновременно обрабатываемых запросов. + +**Пример** + +.. code-block:: xml + + 100 + + +.. _server_settings-max_connections: + +max_connections +--------------- + +Максимальное количество входящих соединений. + +**Пример** + +.. code-block:: xml + + 4096 + +.. _server_settings-max_open_files: + +max_open_files +-------------- + +Максимальное количество открытых файлов. + +По умолчанию - ``maximum``. + +Рекомендуется использовать в Mac OS X, поскольу функция ``getrlimit()`` возвращает некорректное значение. + +**Пример** + +.. code-block:: xml + + 262144 + + +.. _server_settings-max_table_size_to_drop: + +max_table_size_to_drop +---------------------- + +Ограничение на удаление таблиц. + +Если размер таблицы семейства :ref:`table_engines-mergetree` превышает ``max_table_size_to_drop`` (в байтах), то ее нельзя удалить запросом DROP. + +Если таблицу все же необходимо удалить, не перезапуская при этом сервер ClickHouse, то необходимо создать файл ``/flags/force_drop_table`` и выполнить запрос DROP. + +Значение по умолчанию - 50GB. + +Значение 0 означает, что можно удалять все таблицы без ограничений. + +**Пример** + +.. code-block:: xml + + 0 + + +.. _server_settings-merge_tree: + +merge_tree +---------- +Тонкая настройка таблиц семейства :ref:`table_engines-mergetree`. + +Подробнее смотрите в заголовочном файле MergeTreeSettings.h. + +**Пример** + +.. code-block:: xml + + + 5 + + + + +.. _server_settings-openSSL: + +openSSL +------- + +Настройки клиента/сервера SSL. + +Поддержку SSL обеспечивает библиотека ``libpoco``. Описание интерфейса находится в файле `SSLManager.h `_ + +Ключи настроек сервера/клиента: + ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| Ключ | Описание | ++=============================+==========================================================================================================================+ +| privateKeyFile | Путь к файлу с секретным ключем сертификата в формате PEM. Файл может содержать ключ и сертификат одновременно. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| certificateFile | Путь к файлу сертификата клиента/сервера в формате PEM. Можно не указывать, если ``privateKeyFile`` содержит сертификат. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| caConfig | Путь к файлу или каталогу, которые содержат доверенные корневые сертификаты. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| verificationMode | Способ проверки сертификатов узла. Подробности находятся в описании класса | +| | `Context `_. | +| | Допустимые значения: ``none``, ``relaxed``, ``strict``, ``once``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| verificationDepth | Максимальная длина верификационой цепи. | +| | Верификация завершится ошибкой, если длина цепи сертификатов превысит установленное значение. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| loadDefaultCAFile | Признак того, что будут использоваться встроенные CA-сертификаты для OpenSSL. Допустимые значения: ``true``, ``false``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| cipherList | Поддерживаемые OpenSSL-шифры. Например, ``ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| cacheSessions | Включение/выключение кеширования сессии. | +| | Использовать обязательно вместе с ``sessionIdContext``. Допустимые значения: ``true``, ``false``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| sessionIdContext | Уникальный набор произвольных символов, которые сервер добавляет к каждому сгенерированному идентификатору. | +| | Длина строки не должна превышать ``SSL_MAX_SSL_SESSION_ID_LENGTH``. Рекомендуется к использованию всегда, | +| | поскольку позволяет избежать проблем как в случае, если сервер кеширует сессию, | +| | так и если клиент затребовал кеширование. По умолчанию ``${application.name}``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| sessionCacheSize | Максимальное количество сессий, которые кэширует сервер. | +| | По умолчанию - 1024\*20. 0 - неограниченное количество сессий. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| sessionTimeout | Время кеширования сессии на севрере. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| extendedVerification | Автоматическая расширенная проверка сертификатов после завершении сессии. | +| | Допустимые значения: ``true``, ``false``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| requireTLSv1 | Требование соединения TLSv1. Допустимые значения: ``true``, ``false``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| requireTLSv1_1 | Требование соединения TLSv1.1. Допустимые значения: ``true``, ``false``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| requireTLSv1_2 | Требование соединения TLSv1.2. Допустимые значения: ``true``, ``false``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| fips | Активация режима OpenSSL FIPS. Поддерживается, если версия OpenSSL, с которой собрана библиотека поддерживает fips. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| privateKeyPassphraseHandler | Класс (подкласс PrivateKeyPassphraseHandler)запрашивающий кодовую фразу доступа к | +| | секретному ключу. Например, ```` ``KeyFileHandler`` | +| | ``test`` ````. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| invalidCertificateHandler | Класс (подкласс CertificateHandler) для подтвеждения невалидных сертификатов. | +| | Например, `` ConsoleCertificateHandler ``. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| disableProtocols | Запрещенные к искользованию протоколы. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| preferServerCiphers | Предпочтение серверных шифров на клиенте. | ++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+ + + + +**Пример настройки:** + +.. code-block:: xml + + + + + /etc/clickhouse-server/server.crt + /etc/clickhouse-server/server.key + + /etc/clickhouse-server/dhparam.pem + none + true + true + sslv2,sslv3 + true + + + true + true + sslv2,sslv3 + true + + + + RejectCertificateHandler + + + + +.. _server_settings-part_log: + +part_log +-------- + +Логгирование событий, связанных с данными типа :ref:`table_engines-mergetree`. Например, события добавления или мержа данных. Лог можно использовать для симуляции алгоритмов слияния, чтобы сравнивать их характеристики. Также, можно визуализировать процесс слияния. + +Запросы логгируются не в отдельный файл, а в таблицу ClickHouse. + +Столбцы лога: + ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| Столбец | Описание | ++===============+=======================================================================================================================+ +| event_time | Дата события. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| duration_ms | Время события. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| event_type | Тип события. 1 - кусок новый, 2 - результат мержа, 3 - кусок скачан с реплики, 4 - кусок удаляется. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| database_name | Имя базы даных. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| table_name | Имя таблицы. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| part_name | Имя куска данных. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| size_in_bytes | Размер куска данных в байтах. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| merged_from | Массив имён кусков, из которых он образован при мерже (так же заполняется в случае скачивания уже смерженного куска). | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ +| merge_time_ms | Время, потраченное на мерж. | ++---------------+-----------------------------------------------------------------------------------------------------------------------+ + +При настройке логгирования используются следующие параметры: + ++-----------------------------+-----------------------------------------------------+ +| Параметр | Описание | ++=============================+=====================================================+ +| database | Имя базы данных. | ++-----------------------------+-----------------------------------------------------+ +| table | Имя таблицы. | ++-----------------------------+-----------------------------------------------------+ +| flush_interval_milliseconds | Период сброса данных из оперативной памяти на диск. | ++-----------------------------+-----------------------------------------------------+ + + +**Пример** + +.. code-block:: xml + + + system + part_log
+ 7500 + + + +.. _server_settings-path: + +path +---- +Путь к каталогу с данными. + +.. warning:: Завершающий слеш обязателен. + +**Пример** + +.. code-block:: xml + + /var/lib/clickhouse/ + +.. _server_settings-query_log: + +query_log +--------- + +Настройка логгирования запросов, принятых с настройкой :ref:`log_queries=1 `. + +Запросы логгируются не в отдельный файл, а в таблицу ClickHouse. + +При настройке логгирования используются следующие параметры: + ++-----------------------------+-----------------------------------------------------+ +| Параметр | Описание | ++=============================+=====================================================+ +| database | Имя базы данных. | ++-----------------------------+-----------------------------------------------------+ +| table | Имя таблицы. | ++-----------------------------+-----------------------------------------------------+ +| flush_interval_milliseconds | Период сброса данных из оперативной памяти на диск. | ++-----------------------------+-----------------------------------------------------+ + +Если таблица не существует, то ClickHouse создаст её. Если структура журнала запросов изменилась при обновлении сервера ClickHouse, то таблица со старой структурой переименовывается, а новая таблица создается автоматически. + +**Пример** + +.. code-block:: xml + + + system + query_log
+ 7500 + + + +.. _server_settings-remote_servers: + +remote_servers +-------------- +Конфигурация кластеров, которые использует движок таблиц Distributed. + +Пример настройки смотрите в разделе :ref:`Движки таблиц/Distributed `. + +**Пример** + +.. code-block:: xml + + + +Значение атрибута ``incl`` смотрите в разделе :ref:`configuration_files`. + +.. _server_settings-resharding: + +resharding +---------- + +Путь в ZooKeeper к очереди задач. + +Подробнее читайте в разделе :ref:`table_engines-resharding`. + +**Пример** + +.. code-block:: xml + + + /clickhouse/task_queue + + + +.. _server_settings-timezone: + +timezone +-------- +Временная зона сервера. + +Указывается идентификатором IANA в виде часового пояса UTC или географического положения (например, Africa/Abidjan). + +Временная зона необходима при преобразованиях между форматами String и DateTime, которые возникают при выводе полей DateTime в текстовый формат (на экран или в файл) и при получении DateTime из строки. Также, временная зона используется в функциях, которые работают со временем и датой, если они не получили временную зону в параметрах вызова. + +**Пример** + +.. code-block:: xml + + Europe/Moscow + + +.. _server_settings-tcp_port: + +tcp_port +-------- + +Порт для взаимодействия с клиентами по протоколу TCP. + +**Пример** + +.. code-block:: xml + + 9000 + + +.. _server_settings-tmp_path: + +tmp_path +-------- +Путь ко временным данным для обработки больших запросов. + +.. warning:: Завершающий слеш обязателен. + +**Пример** + +.. code-block:: xml + + /var/lib/clickhouse/tmp/ + +.. _server_settings-uncompressed_cache_size: + +uncompressed_cache_size +----------------------- +Размер кеша (в байтах) для несжатых данных, используемых движками таблиц семейства :ref:`table_engines-mergetree`. + +Кеш единый для сервера. Память выделяется по-требованию. Кеш используется в том случае, если включена опция :ref:`settings-use_uncompressed_cache`. + +Несжатый кеш выгодно использовать для очень коротких запросов в отдельных случаях. + +**Пример** + +.. code-block:: xml + + 8589934592 + + +.. _server_settings-users_config: + +users_config +------------ + +Путь к файлу, который содержит: + - Конфигурации пользователей. + - Права доступа. + - Профили настроек. + - Настройки квот. + +**Пример** + +.. code-block:: xml + + users.xml + + +.. _server_settings-zookeeper: + +zookeeper +--------- +Конфигурация серверов ZooKeeper. + +ClickHouse использует ZooKeeper для хранения метаданных о репликах при использовании реплицированных таблиц. + +Параметр можно не указывать, если реплицированные таблицы не используются. + +Подробно о репликации читайте в разделе :ref:`table_engines-replication`. + +**Пример** + +.. code-block:: xml + + \ No newline at end of file diff --git a/docs/ru/operations/settings/index.rst b/docs/ru/operations/settings/index.rst index 8e90e22a3a8..e1e23052f35 100644 --- a/docs/ru/operations/settings/index.rst +++ b/docs/ru/operations/settings/index.rst @@ -1,3 +1,5 @@ +.. _settings: + Настройки ========= diff --git a/docs/ru/operations/settings/settings.rst b/docs/ru/operations/settings/settings.rst index 2110064713c..ed6f78ff00d 100644 --- a/docs/ru/operations/settings/settings.rst +++ b/docs/ru/operations/settings/settings.rst @@ -85,6 +85,19 @@ preferred_block_size_bytes При этом размер блока не может быть более ``max_block_size`` строк. По-умолчанию выключен (равен 0), работает только при чтении из MergeTree-движков. +.. _settings-log_queries: + +log_queries +------------ + +Установка логгирования запроса. + +Запросы, переданные в ClickHouse с этой установкой, логгируются согласно правилам конфигурационного параметра сервера :ref:`server_settings-query_log`. + +**Пример** :: + + log_queries=1 + max_insert_block_size --------------------- Формировать блоки указанного размера, при вставке в таблицу. @@ -157,6 +170,7 @@ max_query_size interactive_delay ----------------- Интервал в микросекундах для проверки, не запрошена ли остановка выполнения запроса, и отправки прогресса. + По умолчанию - 100 000 (проверять остановку запроса и отправлять прогресс десять раз в секунду). connect_timeout @@ -209,6 +223,8 @@ extremes Считать ли экстремальные значения (минимумы и максимумы по столбцам результата запроса). Принимает 0 или 1. По умолчанию - 0 (выключено). Подробнее смотрите раздел "Экстремальные значения". +.. _settings-use_uncompressed_cache: + use_uncompressed_cache ---------------------- Использовать ли кэш разжатых блоков. Принимает 0 или 1. По умолчанию - 0 (выключено). diff --git a/docs/ru/query_language/queries.rst b/docs/ru/query_language/queries.rst index 0b550f57395..90fbbf45d22 100644 --- a/docs/ru/query_language/queries.rst +++ b/docs/ru/query_language/queries.rst @@ -420,6 +420,8 @@ ALTER Для запросов ``ALTER ... ATTACH|DETACH|DROP`` можно настроить ожидание, с помощью настройки ``replication_alter_partitions_sync``. Возможные значения: ``0`` - не ждать, ``1`` - ждать выполнения только у себя (по умолчанию), ``2`` - ждать всех. +.. _query_language_queries_show_databases: + SHOW DATABASES ~~~~~~~~~~~~~~ diff --git a/docs/ru/system_tables/system.asynchronous_metrics.rst b/docs/ru/system_tables/system.asynchronous_metrics.rst index d12131acbd7..38da983aa4b 100644 --- a/docs/ru/system_tables/system.asynchronous_metrics.rst +++ b/docs/ru/system_tables/system.asynchronous_metrics.rst @@ -1,3 +1,5 @@ +.. _system_tables-system.asynchronous_metrics: + system.asynchronous_metrics --------------------------- diff --git a/docs/ru/system_tables/system.events.rst b/docs/ru/system_tables/system.events.rst index 3f4ab0c90f5..8168559d25b 100644 --- a/docs/ru/system_tables/system.events.rst +++ b/docs/ru/system_tables/system.events.rst @@ -1,3 +1,5 @@ +.. _system_tables-system.events: + system.events ------------- diff --git a/docs/ru/system_tables/system.metrics.rst b/docs/ru/system_tables/system.metrics.rst index dee53b399e6..25038d3e92e 100644 --- a/docs/ru/system_tables/system.metrics.rst +++ b/docs/ru/system_tables/system.metrics.rst @@ -1,2 +1,4 @@ +.. _system_tables-system.metrics: + system.metrics -------------- diff --git a/docs/ru/table_engines/distributed.rst b/docs/ru/table_engines/distributed.rst index 75b73737b10..4ab76d1e8c1 100644 --- a/docs/ru/table_engines/distributed.rst +++ b/docs/ru/table_engines/distributed.rst @@ -1,3 +1,5 @@ +.. _table_engines-distributed: + Distributed ----------- diff --git a/docs/ru/table_engines/graphitemergetree.rst b/docs/ru/table_engines/graphitemergetree.rst index d036f267ec6..5b741522061 100644 --- a/docs/ru/table_engines/graphitemergetree.rst +++ b/docs/ru/table_engines/graphitemergetree.rst @@ -1,3 +1,5 @@ +.. _table_engines-graphitemergetree: + GraphiteMergeTree ----------------- @@ -13,7 +15,7 @@ Graphite хранит в ClickHouse полные данные, а получат Используется движок ``GraphiteMergeTree``. -Движок наследует свойства `MergeTree`. Настройки прореживания данных размещаются в :ref:`общей конфигурации ` ClickHouse (config.xml). +Движок наследует свойства `MergeTree`. Настройки прореживания данных задаются параметром :ref:`server_settings-graphite_rollup` в конфигурации сервера . Использование движка ^^^^^^^^^^^^^^^^^^^^ @@ -29,7 +31,7 @@ Graphite хранит в ClickHouse полные данные, а получат .. code-block:: text - pattern + pattern regexp function age -> precision @@ -45,19 +47,17 @@ Graphite хранит в ClickHouse полные данные, а получат Поля шаблона правил. -.. code-block:: text - - +---------------+----------------------------------------------------------------------------------------------------------------------------+ - | Поле | Описание | - +===============+============================================================================================================================+ - | ``age`` | Минимальный возраст данных в секундах. | - +---------------+----------------------------------------------------------------------------------------------------------------------------+ - | ``function`` | Имя агрегирующей функции, которую следует применить к данным, чей возраст оказался в интервале ``[age, age + precision]``. | - +---------------+----------------------------------------------------------------------------------------------------------------------------+ - | ``precision`` | Точность определения возраста данных в секундах. | - +---------------+----------------------------------------------------------------------------------------------------------------------------+ - | ``regexp`` | Шаблон имени метрики. | - +---------------+----------------------------------------------------------------------------------------------------------------------------+ ++---------------+----------------------------------------------------------------------------------------------------------------------------+ +| Поле | Описание | ++===============+============================================================================================================================+ +| ``age`` | Минимальный возраст данных в секундах. | ++---------------+----------------------------------------------------------------------------------------------------------------------------+ +| ``function`` | Имя агрегирующей функции, которую следует применить к данным, чей возраст оказался в интервале ``[age, age + precision]``. | ++---------------+----------------------------------------------------------------------------------------------------------------------------+ +| ``precision`` | Точность определения возраста данных в секундах. | ++---------------+----------------------------------------------------------------------------------------------------------------------------+ +| ``regexp`` | Шаблон имени метрики. | ++---------------+----------------------------------------------------------------------------------------------------------------------------+ Пример настройки: diff --git a/docs/ru/table_engines/replication.rst b/docs/ru/table_engines/replication.rst index c7d8e84dc68..83f97928dea 100644 --- a/docs/ru/table_engines/replication.rst +++ b/docs/ru/table_engines/replication.rst @@ -67,6 +67,8 @@ ReplicatedSummingMergeTree Система следит за синхронностью данных на репликах и умеет восстанавливаться после сбоя. Восстановление после сбоя автоматическое (в случае небольших различий в данных) или полуавтоматическое (когда данные отличаются слишком сильно, что может свидетельствовать об ошибке конфигурации). +.. _table_engines-replication-creation_of_rep_tables: + Создание реплицируемых таблиц ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ru/table_engines/resharding.rst b/docs/ru/table_engines/resharding.rst index af92fc9b127..06ac38967a2 100644 --- a/docs/ru/table_engines/resharding.rst +++ b/docs/ru/table_engines/resharding.rst @@ -1,3 +1,5 @@ +.. _table_engines-resharding: + Перешардирование ---------------- From 1f6229d279e3b48d3bdffc0f6676868251ee2faa Mon Sep 17 00:00:00 2001 From: BayoNet Date: Mon, 31 Jul 2017 11:31:30 +0300 Subject: [PATCH 2/5] External dictionaries topic is restructured and updated. --- docs/ru/dicts/external_dicts.rst | 343 +--------------- docs/ru/dicts/external_dicts_dict.rst | 35 ++ docs/ru/dicts/external_dicts_dict_layout.rst | 250 +++++++++++ .../ru/dicts/external_dicts_dict_lifetime.rst | 38 ++ docs/ru/dicts/external_dicts_dict_sources.rst | 388 ++++++++++++++++++ .../dicts/external_dicts_dict_structure.rst | 125 ++++++ docs/ru/dicts/index.rst | 4 +- docs/ru/formats/index.rst | 2 + docs/ru/functions/ext_dict_functions.rst | 4 +- docs/ru/functions/other_functions.rst | 2 + .../operations/server_settings/settings.rst | 14 +- 11 files changed, 877 insertions(+), 328 deletions(-) create mode 100644 docs/ru/dicts/external_dicts_dict.rst create mode 100644 docs/ru/dicts/external_dicts_dict_layout.rst create mode 100644 docs/ru/dicts/external_dicts_dict_lifetime.rst create mode 100644 docs/ru/dicts/external_dicts_dict_sources.rst create mode 100644 docs/ru/dicts/external_dicts_dict_structure.rst diff --git a/docs/ru/dicts/external_dicts.rst b/docs/ru/dicts/external_dicts.rst index 4001eeff87f..00374b5a91e 100644 --- a/docs/ru/dicts/external_dicts.rst +++ b/docs/ru/dicts/external_dicts.rst @@ -1,345 +1,44 @@ .. _dicts-external_dicts: +*************** Внешние словари -=============== +*************** -Существует возможность подключать свои собственные словари из различных источников данных. -Источником данных для словаря может быть файл на локальной файловой системе, сервер ClickHouse, сервер MySQL, MongoDB или любой ODBC источник. -Словарь может полностью храниться в оперативке и периодически обновляться, или быть частично закэшированным в оперативке и динамически подгружать отсутствующие значения. +Существует возможность подключать собственные словари из различных источников данных. Источником данных для словаря может быть локальный текстовый/исполняемый файл, HTTP(s) ресурс или другая СУБД. Подробнее смотрите в разделе ":ref:`dicts-external_dicts_dict_sources`". -Конфигурация внешних словарей находится в отдельном файле или файлах, указанных в конфигурационном параметре :ref:`dictionaries_config `. -Этот параметр содержит абсолютный или относительный путь к файлу с конфигурацией словарей. Относительный путь - относительно директории с конфигурационным файлом сервера. Путь может содержать wildcard-ы \* и ? - тогда рассматриваются все подходящие файлы. Пример: ``dictionaries/*.xml``. +ClickHouse может полностью или частично хранить словари в оперативной памяти, периодически обновлять их и динамически подгружать отсутствующие значения. -Конфигурация словарей, а также множество файлов с конфигурацией, может обновляться без перезапуска сервера. Сервер проверяет обновления каждые 5 секунд. То есть, словари могут подключаться динамически. +Конфигурация внешних словарей находится в одном или нескольких файлах. Путь к конфигурации указывается в параметре :ref:`server_settings-dictionaries_config`. -Создание словарей может производиться при старте сервера или при первом использовании. Это определяется конфигурационном параметром :ref:`dictionaries_lazy_load ` (в основном конфигурационном файле сервера). Параметр не обязателен, по умолчанию - ``true``. Если true, то каждый словарь создаётся при первом использовании; если словарь не удалось создать - вызов функции, использующей словарь, кидает исключение. Если ``false``, то все словари создаются при старте сервера, и в случае ошибки, сервер завершает работу. +Периодически ClickHouse обновляет конфигурацию словарей и словари. Т.о. словари можно подгружать динамически. + +Словари могут загружаться при старте сервера или при первом использовании, в зависимости от настройки :ref:`server_settings-dictionaries_lazy_load`. Конфигурационный файл словарей имеет вид: .. code-block:: xml - Не обязательный элемент с любым содержимым; полностью игнорируется. + Необязательный элемент с любым содержимым. Полностью игнорируется. - - - os - - - - - - - - /opt/dictionaries/os.tsv - - TabSeparated - - - - - - - + + - - - - cat /opt/dictionaries/os.tsv - - TabSeparated - - - - - http://[::1]/os.tsv - - TabSeparated - - - - - - - 300 - 360 - - - - - - - - - - - - - - - - Id - - - - - Name - - String - - - - - - - ParentID - UInt64 - 0 - - true - - true - + ... - - - expr - UInt64 - rand64() - 0 - - + + -Идентификатор (ключевой атрибут) словаря должен быть числом, помещающимся в UInt64. -Также есть возможность задавать произвольные составные ключи (см. раздел "Словари с составными ключами"). Замечание: составной ключ может состоять и из одного элемента, что даёт возможность использовать в качестве ключа, например, строку. +В одном файле можно :ref:`сконфигурировать ` произвольное количество словарей. Формат файла сохраняется даже если словарь один (т.е. `` ``). +Смотрите также ":ref:`ext_dict_functions`" . -Существует шесть способов размещения словаря в памяти. +.. attention:: Вы можете преобразовать значения по небольшому словарю, описав его в запросе ``SELECT`` (см. функцию ":ref:`other_functions-transform`"). Эта функциональность не связана с внешними словарями. -flat ------ -В виде плоских массивов. Самый эффективный способ. Он подходит, если все ключи меньше 500 000. Если при создании словаря обнаружен ключ больше, то кидается исключение и словарь не создаётся. Словарь загружается в оперативку целиком. Словарь использует количество оперативки, пропорциональное максимальному значению ключа. Ввиду ограничения на 500 000, потребление оперативки вряд ли может быть большим. -Поддерживаются все виды источников. При обновлении, данные (из файла, из таблицы) читаются целиком. - -hashed ------- -В виде хэш-таблиц. Слегка менее эффективный способ. Словарь тоже загружается в оперативку целиком, и может содержать произвольное количество элементов с произвольными идентификаторами. На практике, имеет смысл использовать до десятков миллионов элементов, пока хватает оперативки. -Поддерживаются все виды источников. При обновлении, данные (из файла, из таблицы) читаются целиком. - -cache ------ -Наименее эффективный способ. Подходит, если словарь не помещается в оперативку. Представляет собой кэш из фиксированного количества ячеек, в которых могут быть расположены часто используемые данные. Поддерживается источник MySQL, ClickHouse, executable, http; источник-файл не поддерживается. При поиске в словаре, сначала просматривается кэш. На каждый блок данных, все не найденные в кэше ключи (или устаревшие ключи) собираются в пачку, и с этой пачкой делается запрос к источнику вида SELECT attrs... FROM db.table WHERE id IN (k1, k2, ...). Затем полученные данные записываются в кэш. - -range_hashed ------------- -В таблице прописаны какие-то данные для диапазонов дат, для каждого ключа. Дать возможность доставать эти данные для заданного ключа, для заданной даты. - - -Пример: таблица содержит скидки для каждого рекламодателя в виде: - - +------------------+-----------------------------+------------+----------+ - | id рекламодателя | дата начала действия скидки | дата конца | величина | - +==================+=============================+============+==========+ - | 123 | 2015-01-01 | 2015-01-15 | 0.15 | - +------------------+-----------------------------+------------+----------+ - | 123 | 2015-01-16 | 2015-01-31 | 0.25 | - +------------------+-----------------------------+------------+----------+ - | 456 | 2015-01-01 | 2015-01-15 | 0.05 | - +------------------+-----------------------------+------------+----------+ - -Добавляем ``layout = range_hashed``. -При использовании такого layout, в structure должны быть элементы ``range_min``, ``range_max``. - -Пример: - -.. code-block:: xml - - - - Id - - - first - - - last - - ... - -Эти столбцы должны иметь тип Date. Другие типы пока не поддерживаем. -Столбцы обозначают закрытый диапазон дат. - -Для работы с такими словарями, функции dictGetT должны принимать ещё один аргумент - дату: - -``dictGetT('dict_name', 'attr_name', id, date)`` - -Функция достаёт значение для данного id и для диапазона дат, в который входит переданная дата. Если не найден id или для найденного id не найден диапазон, то возвращается значение по умолчанию для словаря. - -Если есть перекрывающиеся диапазоны, то можно использовать любой подходящий. - -Если граница диапазона является NULL или является некорректной датой (1900-01-01, 2039-01-01), то диапазон следует считать открытым. Диапазон может быть открытым с обеих сторон. - -В оперативке данные представлены в виде хэш-таблицы со значением в виде упорядоченного массива диапазонов и соответствующих им значений. - -Пример словаря по диапазонам: - -.. code-block:: xml - - - - xxx - - - xxx - 3306 - xxx - - xxx - 1 - - dicts - xxx
- - - - 300 - 360 - - - - - - - Abcdef - - - StartDate - - - EndDate - - - XXXType - String - - - - - - -complex_key_hashed ------------------- - -Для использования с составными ключами. Аналогичен hashed. - -complex_key_cache ------------------ - -Для использования с составными ключами. Аналогичен cache. - -Примечания ----------- - -Рекомендуется использовать способ ``flat``, если возможно, или ``hashed``, ``complex_key_hashed``. Скорость работы словарей с таким размещением в памяти является безупречной. - -Способы ``cache`` и ``complex_key_cache`` следует использовать лишь если это неизбежно. Скорость работы кэша очень сильно зависит от правильности настройки и сценария использования. Словарь типа cache нормально работает лишь при достаточно больших hit rate-ах (рекомендуется 99% и выше). Посмотреть средний hit rate можно в таблице system.dictionaries. Укажите достаточно большой размер кэша. Количество ячеек следует подобрать экспериментальным путём - выставить некоторое значение, с помощью запроса добиться полной заполненности кэша, посмотреть на потребление оперативки (эта информация находится в таблице system.dictionaries); затем пропорционально увеличить количество ячеек так, чтобы расходовалось разумное количество оперативки. В качестве источника для кэша рекомендуется MySQL, MongoDB, так как ClickHouse плохо обрабатывает запросы со случайными чтениями. - -Во всех случаях, производительность будет выше, если вызывать функцию для работы со словарём после ``GROUP BY``, или если доставаемый атрибут помечен как инъективный. Для cache словарей, производительность будет лучше, если вызывать функцию после LIMIT-а - для этого можно использовать подзапрос с LIMIT-ом, и снаружи вызывать функцию со словарём. - -Атрибут называется инъективным, если разным ключам соответствуют разные значения атрибута. Тогда при использовании в ``GROUP BY`` функции, достающей значение атрибута по ключу, эта функция автоматически выносится из GROUP BY. - -При обновлении словарей из файла, сначала проверяется время модификации файла, и загрузка производится только если файл изменился. -При обновлении из MySQL, для flat и hashed словарей, сначала делается запрос ``SHOW TABLE STATUS`` и смотрится время обновления таблицы. И если оно не NULL, то оно сравнивается с запомненным временем. Это работает для MyISAM таблиц, а для InnoDB таблиц время обновления неизвестно, поэтому загрузка из InnoDB делается при каждом обновлении. - -Для cache-словарей может быть задано время устаревания (``lifetime``) данных в кэше. Если от загрузки данных в ячейке прошло больше времени, чем lifetime, то значение не используется, и будет запрошено заново при следующей необходимости его использовать. - -Если словарь не удалось ни разу загрузить, то при попытке его использования, будет брошено исключение. -Если при запросе к источнику cached словаря возникла ошибка, то будет брошено исключение. -Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы - во время обновления используется старая версия словаря. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей. - -Список внешних словарей и их статус можно посмотреть в таблице ``system.dictionaries``. - -Для использования внешних словарей, смотрите раздел "Функции для работы с внешними словарями". - -Обратите внимание, что вы можете преобразовать значения по небольшому словарю, указав всё содержимое словаря прямо в запросе SELECT - смотрите раздел "Функция transform". Эта функциональность никак не связана с внешними словарями. - -Словари с составными ключами ----------------------------- - -В качестве ключа может выступать кортеж (tuple) из полей произвольных типов. Параметр layout в этом случае должен быть равен complex_key_hashed или complex_key_cache. - -Структура ключа задаётся не в элементе ````, а в элементе ````. Поля ключа задаются в том же формате, что и атрибуты словаря. Пример: - -.. code-block:: xml - - - - - field1 - String - - - field2 - UInt32 - - ... - - ... - - -При использовании такого словаря, в функции dictGet* в качестве ключа передаётся Tuple со значениями полей. Пример: ``dictGetString('dict_name', 'attr_name', tuple('field1', 123))``. +.. toctree:: + :glob: + + external_dicts_dict* diff --git a/docs/ru/dicts/external_dicts_dict.rst b/docs/ru/dicts/external_dicts_dict.rst new file mode 100644 index 00000000000..b400261f0e5 --- /dev/null +++ b/docs/ru/dicts/external_dicts_dict.rst @@ -0,0 +1,35 @@ +.. _dicts-external_dicts_dict: + +************************** +Настройка внешнего словаря +************************** + +Конфигурация словаря имеет следующую структуру: + +.. code-block:: xml + + + dict_name + + + + + + + + + + + + + + + + + + +* name - Идентификатор, под которым словарь будет доступен для использования. Используйте символы ``[a-zA-Z0-9_\-]``. +* :ref:`source ` - Источник словаря. +* :ref:`layout ` - Размещение словаря в памяти. +* :ref:`structure ` - Ключ словаря. +* :ref:`lifetime ` - Периодичность обновления словарей. diff --git a/docs/ru/dicts/external_dicts_dict_layout.rst b/docs/ru/dicts/external_dicts_dict_layout.rst new file mode 100644 index 00000000000..4ee4cc6fe05 --- /dev/null +++ b/docs/ru/dicts/external_dicts_dict_layout.rst @@ -0,0 +1,250 @@ +.. _dicts-external_dicts_dict_layout: + +************************** +Хранение словарей в памяти +************************** + +Словари можно размещать в памяти :ref:`множеством способов `. + +Рекомендуем :ref:`dicts-external_dicts_dict_layout-flat`, :ref:`dicts-external_dicts_dict_layout-hashed` и :ref:`dicts-external_dicts_dict_layout-complex_key_hashed`. Скорость обработки словарей при этом максимальна. + +Размещение с кэшированием не рекомендуется использовать из-за потенциально низкой производительности и сложностей в подборе оптимальных параметров. Читайте об этом подробнее в разделе ":ref:`dicts-external_dicts_dict_layout-cache`". + +Повысить производительнось словарей можно следующими способами: + +* Вызывать функцию для работы со словарём после ``GROUP BY``. +* Помечать извлекаемые атрибуты как инъективные. Атрибут называется инъективным, если разным ключам соответствуют разные значения атрибута. Тогда при использовании в ``GROUP BY`` функции, достающей значение атрибута по ключу, эта функция автоматически выносится из ``GROUP BY``. + +ClickHouse периодически обновляет словари. Сначала проверяется время модификации файла/таблицы, затем, если файл/таблица обновились, обновляется словарь. Если словарь хранится в таблице типа MyISAM, то время модификации проверяется запросом ``SHOW TABLE STATUS``. Для таблиц InnoDB нельзя получить время модификации, поэтому словарь обновляется каждый раз. + +Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы - во время обновления используется старая версия словаря. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей. + +При ошибках работы со словарями ClickHouse генерирует исключения. Например, в следующих ситуациях: + +* При обращении к словарю, который не удалось загрузить. +* При ошибке запроса к ``cached``-словарю. + + +Список внешних словарей и их статус можно посмотреть в таблице ``system.dictionaries``. + +Общий вид конфигурации: + +.. code-block:: xml + + + + ... + + + + + + ... + + + + +.. _dicts-external_dicts_dict_layout-manner: + +Способы размещения словарей в памяти +==================================== + +* :ref:`dicts-external_dicts_dict_layout-flat` +* :ref:`dicts-external_dicts_dict_layout-hashed` +* :ref:`dicts-external_dicts_dict_layout-cache` +* :ref:`dicts-external_dicts_dict_layout-range_hashed` +* :ref:`dicts-external_dicts_dict_layout-complex_key_hashed` +* :ref:`dicts-external_dicts_dict_layout-complex_key_cache` + + +.. _dicts-external_dicts_dict_layout-flat: + +flat +---- + +Словарь полностью хранится в оперативной памяти в виде плоских массивов. Объем памяти, занимаемой словарем? пропорционален размеру самого большого (по размеру) ключа. + +Ключ словаря имеет тип ``UInt64`` и его величина ограничена 500 000. Если при создании словаря обнаружен ключ больше, то ClickHouse бросает исключение и не создает словарь. + +Поддерживаются все виды источников. При обновлении, данные (из файла, из таблицы) читаются целиком. + +Это метод обеспечивает максимальную производительность среди всех доступных способов размещения словаря. + +Пример конфигурации: + +.. code-block:: xml + + + + + + +.. _dicts-external_dicts_dict_layout-hashed: + +hashed +------ + +Словарь полностью хранится в оперативной памяти в виде хэш-таблиц. Словарь может содержать произвольное количество элементов с произвольными идентификаторами. На практике, количество ключей может достигать десятков миллионов элементов. + +Поддерживаются все виды источников. При обновлении, данные (из файла, из таблицы) читаются целиком. + +Пример конфигурации: + +.. code-block:: xml + + + + + + +.. _dicts-external_dicts_dict_layout-complex_key_hashed: + +complex_key_hashed +------------------ + +Тип размещения предназначен для использования с составными :ref:`ключами `. Аналогичен hashed. + +Пример конфигурации: + +.. code-block:: xml + + + + + + +.. _dicts-external_dicts_dict_layout-range_hashed: + +range_hashed +------------ + +Словарь хранится в оперативной памяти в виде хэш-таблицы с упорядоченным массивом диапазонов и соответствующих им значений. + +Этот способ размещения работает также как и hashed и позволяет дополнительно к ключу использовать дипазоны по дате/времени, если они указаны в словаре. + +Пример: таблица содержит скидки для каждого рекламодателя в виде: + + +------------------+-----------------------------+------------+----------+ + | id рекламодателя | дата начала действия скидки | дата конца | величина | + +==================+=============================+============+==========+ + | 123 | 2015-01-01 | 2015-01-15 | 0.15 | + +------------------+-----------------------------+------------+----------+ + | 123 | 2015-01-16 | 2015-01-31 | 0.25 | + +------------------+-----------------------------+------------+----------+ + | 456 | 2015-01-01 | 2015-01-15 | 0.05 | + +------------------+-----------------------------+------------+----------+ + +Столбцы с датами в словаре должны иметь тип ``Date``. + +Чтобы использовать выборку по диапазонам дат, необходимо в :ref:`structure ` определить элементы ``range_min``, ``range_max``. + +Пример: + +.. code-block:: xml + + + + Id + + + first + + + last + + ... + + + +Для работы с такими словарями в функцию ``dictGetT`` необходимо передавать дополнительный аргумент - дату: :: + + dictGetT('dict_name', 'attr_name', id, date) + +Функция возвращает значение для заданных ``id`` и диапазона дат, в который входит переданная дата. + +Особенности алгоритма: + +* Если не найден ``id`` или для найденного ``id`` не найден диапазон, то возвращается значение по умолчанию для словаря. +* Если есть перекрывающиеся диапазоны, то можно использовать любой подходящий. +* Если граница диапазона ``NULL`` или некорректная дата (1900-01-01, 2039-01-01), то диапазон считается открытым. Диапазон может быть открытым с обеих сторон. + + +Пример конфигурации: + +.. code-block:: xml + + + + + ... + + + + + + + + Abcdef + + + StartDate + + + EndDate + + + XXXType + String + + + + + + + + +.. _dicts-external_dicts_dict_layout-cache: + +cache +----- + +Словарь хранится в кэше, состоящем из фиксированного количества ячеек. Ячейки содержат часто используемые элементы. + +При поиске в словаре сначала просматривается кэш. На каждый блок данных, все не найденные в кэше или устаревшие ключи запрашиваются у источника с помощью ``SELECT attrs... FROM db.table WHERE id IN (k1, k2, ...)``. Затем, полученные данные записываются в кэш. + +Для cache-словарей может быть задано время устаревания (:ref:`lifetime `) данных в кэше. Если от загрузки данных в ячейке прошло больше времени, чем ``lifetime``, то значение не используется, и будет запрошено заново при следующей необходимости его использовать. + +Это наименее эффективный из всех способов размещения словарей. Скорость работы кэша очень сильно зависит от правильности настройки и сценария использования. Словарь типа cache показывает высокую производительность лишь при достаточно больших hit rate-ах (рекомендуется 99% и выше). Посмотреть средний hit rate можно в таблице ``system.dictionaries``. + +Чтобы увеличить производительность кэша, используйте подзапрос с ``LIMIT``, а снаружи вызывайте функцию со словарём. + +Поддерживаются :ref:`источники `: MySQL, ClickHouse, executable, HTTP. + +Пример настройки: + +.. code-block:: xml + + + + + 1000000000 + + + +Укажите достаточно большой размер кэша. Количество ячеек следует подобрать экспериментальным путём: + +1. Выставить некоторое значение. +2. Запросами добиться полной заполненности кэша. +3. Оценить потребление оперативной памяти с помощью таблицы ``system.dictionaries``. +4. Увеличивать/уменьшать количество ячеек до получения требуемого расхода оперативной памяти. + +.. warning:: Не используйте в качестве источника ClickHouse, поскольку он медленно обрабатывает запросы со случайным чтением. + + +.. _dicts-external_dicts_dict_layout-complex_key_cache: + +complex_key_cache +----------------- + +Тип размещения предназначен для использования с составными :ref:`ключами `. Аналогичен ``cache``. + diff --git a/docs/ru/dicts/external_dicts_dict_lifetime.rst b/docs/ru/dicts/external_dicts_dict_lifetime.rst new file mode 100644 index 00000000000..d3de506b800 --- /dev/null +++ b/docs/ru/dicts/external_dicts_dict_lifetime.rst @@ -0,0 +1,38 @@ +.. _dicts-external_dicts_dict_lifetime: + +******************* +Обновление словарей +******************* + +ClickHouse периодически обновляет словари. Интервал обновления для полностью загружаемых словарей и интервал инвалидации для кэшируемых словарей определяется в теге ```` в секундах. + +Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы, во время обновления используется старая версия словаря. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей. + +Пример настройки: + +.. code-block:: xml + + + ... + 300 + ... + + + +Настройка ``0`` запрещает обновление словарей. + + +Можно задать интервал, внутри которого ClickHouse равномерно-случайно выберет время для обновления. Это необходимо для распределения нагрузки на источник словаря при обновлении на большом количестве серверов. + +Пример настройки: + +.. code-block:: xml + + + ... + + 300 + 360 + + ... + diff --git a/docs/ru/dicts/external_dicts_dict_sources.rst b/docs/ru/dicts/external_dicts_dict_sources.rst new file mode 100644 index 00000000000..035287b1a52 --- /dev/null +++ b/docs/ru/dicts/external_dicts_dict_sources.rst @@ -0,0 +1,388 @@ +.. _dicts-external_dicts_dict_sources: + +************************** +Источники внешних словарей +************************** + +Внешний словарь можно подключить из множества источников. + +Общий вид конфигурации: + +.. code-block:: xml + + + + ... + + + + + + ... + + ... + + +Источник настраивается в разделе ``source``. + +Типы источников (``source_type``): + + * :ref:`dicts-external_dicts_dict_sources-local_file` + * :ref:`dicts-external_dicts_dict_sources-executable` + * :ref:`dicts-external_dicts_dict_sources-http` + * :ref:`dicts-external_dicts_dict_sources-odbc` + * СУБД: + + * :ref:`dicts-external_dicts_dict_sources-mysql` + * :ref:`dicts-external_dicts_dict_sources-clickhouse` + * :ref:`dicts-external_dicts_dict_sources-mongodb` + + +.. _dicts-external_dicts_dict_sources-local_file: + +Локальный файл +============== + +Пример настройки: + +.. code-block:: xml + + + + /opt/dictionaries/os.tsv + TabSeparated + + + +Поля настройки: + +* ``path`` - Абсолютный путь к файлу. +* ``format`` - Формат файла. Поддерживаются все форматы, описанные в разделе ":ref:`formats`". + + +.. _dicts-external_dicts_dict_sources-executable: + +Исполняемый файл +================ + +Работа с исполняемым файлом зависит от :ref:`размещения словаря в памяти `. Если тип размещения словаря ``cache`` и ``complex_key_cache``, то ClickHouse запрашивает необходимые ключи, отправляя запрос в ``STDIN`` исполняемого файла. + +Пример настройки: + +.. code-block:: xml + + + + cat /opt/dictionaries/os.tsv + TabSeparated + + + +Поля настройки: + +* ``command`` - Абсолютный путь к исполняемому файлу или имя файла (если каталог программы прописан в ``PATH``). +* ``format`` - Формат файла. Поддерживаются все форматы, описанные в разделе ":ref:`formats`". + + +.. _dicts-external_dicts_dict_sources-http: + +HTTP(s) +======= + +Работа с HTTP(s) сервером зависит от :ref:`размещения словаря в памяти `. Если тип размещения словаря ``cache`` и ``complex_key_cache``, то ClickHouse запрашивает необходимые ключи, отправляя запрос методом ``POST``. + +Пример настройки: + +.. code-block:: xml + + + + http://[::1]/os.tsv + TabSeparated + + + +Чтобы ClickHouse смог обратиться к HTTPS-ресурсу, необходимо прописать :ref:`настройки openSSL ` в конфигурации сервера. + +Поля настройки: + +* ``url`` - URL источника. +* ``format`` - Формат файла. Поддерживаются все форматы, описанные в разделе ":ref:`formats`". + + +.. _dicts-external_dicts_dict_sources-odbc: + +ODBC +==== + +Этим способом можно подключить любую базу данных, имеющую ODBC драйвер. + +Пример настройки: + +.. code-block:: xml + + + DatabaseName + TableName
+ DSN=some_parameters + + +Поля настройки: + +* ``db`` - Имя базы данных. Не указывать, если имя базы задано в параметрах ````. +* ``table`` - Имя таблицы. +* ``connection_string`` - Строка соединения. + + +Пример подключения PostgreSQL +----------------------------- + +ОС Ubuntu. + +Установка unixODBC и ODBC-драйвера для PostgreSQL: :: + + sudo apt-get install -y unixodbc odbcinst odbc-postgresql + + +Настройка ``/etc/odbc.ini`` (или ``~/.odbc.ini``): :: + + [DEFAULT] + Driver = myconnection + + [myconnection] + Description = PostgreSQL connection to my_db + Driver = PostgreSQL Unicode + Database = my_db + Servername = 127.0.0.1 + UserName = username + Password = password + Port = 5432 + Protocol = 9.3 + ReadOnly = No + RowVersioning = No + ShowSystemTables = No + ConnSettings = + + +Конфигурация словаря в ClickHouse: + +.. code-block:: xml + + + table_name + + + + + DSN=myconnection + postgresql_table
+ + + + 300 + 360 + + + + + + + id + + + some_column + UInt64 + 0 + + + + +Может понадобиться в ``odbc.ini`` указать полный путь до библиотеки с драйвером ``DRIVER=/usr/local/lib/psqlodbcw.so``. + +Пример подключения MS SQL Server +-------------------------------- + +ОС Ubuntu. + +Установка драйвера: :: + + sudo apt-get install tdsodbc freetds-bin sqsh + +Настройка драйвера: :: + + $ cat /etc/freetds/freetds.conf + ... + + [MSSQL] + host = 192.168.56.101 + port = 1433 + tds version = 7.0 + client charset = UTF-8 + + $ cat /etc/odbcinst.ini + ... + + [FreeTDS] + Description = FreeTDS + Driver = /usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so + Setup = /usr/lib/x86_64-linux-gnu/odbc/libtdsS.so + FileUsage = 1 + UsageCount = 5 + + $ cat ~/.odbc.ini + ... + + [MSSQL] + Description = FreeTDS + Driver = FreeTDS + Servername = MSSQL + Database = test + UID = test + PWD = test + Port = 1433 + + +Настройка словаря в ClickHouse: + +.. code-block:: xml + + + + test + + + dict
+ DSN=MSSQL;UID=test;PWD=test + + + + + 300 + 360 + + + + + + + + + k + + + s + String + + + + + + + + +СУБД +==== + +.. _dicts-external_dicts_dict_sources-mysql: + +MySQL +----- + +Пример настройки: + +.. code-block:: xml + + + + 3306 + clickhouse + qwerty + + example01-1 + 1 + + + example01-2 + 1 + + conv_main + counters
+ id=10 + + + + +Поля настройки: + +* ``port`` - порт сервера MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ````). +* ``user`` - имя пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ````). +* ``password`` - пароль пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ````). +* ``replica`` - блок конфигурации реплики. Блоков может быть несколько. + + * ``replica/host`` - хост MySQL. + * ``replica/priority`` - приоритет реплики. При попытке соединения ClickHouse обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет. +* ``db`` - имя базы данных. +* ``table`` - имя таблицы. +* ``where`` - условие выбора. Может отсутствовать. + +.. _dicts-external_dicts_dict_sources-clickhouse: + +ClickHouse +---------- + +Пример настройки: + +.. code-block:: xml + + + + example01-01-1 + 9000 + default + + default + ids
+ id=10 + + + +Поля настройки: + +* ``host`` - хост ClickHouse. Если host локальный, то запрос выполняется без сетевого взаимодействия. Чтобы повысить отказоустойчивость решения, можно создать таблицу типа :ref:`Distributed ` и прописать её в дальнейших настройках. +* ``port`` - порт сервера ClickHouse. +* ``user`` - имя пользователя ClickHouse. +* ``password`` - пароль пользователя ClickHouse. +* ``db`` - имя базы данных. +* ``table`` - имя таблицы. +* ``where`` - условие выбора. Может отсутствовать. + + +.. _dicts-external_dicts_dict_sources-mongodb: + +MongoDB +------- + +Пример настройки: + +.. code-block:: xml + + + + localhost + 27017 + + + test + dictionary_source + + + + +Поля настройки: + +* ``host`` - хост MongoDB. +* ``port`` - порт сервера MongoDB. +* ``user`` - имя пользователя MongoDB. +* ``password`` - пароль пользователя MongoDB. +* ``db`` - имя базы данных. +* ``collection`` - имя коллекции. diff --git a/docs/ru/dicts/external_dicts_dict_structure.rst b/docs/ru/dicts/external_dicts_dict_structure.rst new file mode 100644 index 00000000000..ec0ae0be370 --- /dev/null +++ b/docs/ru/dicts/external_dicts_dict_structure.rst @@ -0,0 +1,125 @@ +.. _dicts-external_dicts_dict_structure: + +******************* +Ключ и поля словаря +******************* + +Секция ```` описывает ключ словаря и поля, доступные для запросов. + + +Общий вид структуры: + +.. code-block:: xml + + + + + Id + + + + + + + ... + + + + +В структуре описываются столбцы: + +* ```` - :ref:`ключевой столбец `. +* ```` - :ref:`столбец данных `. Столбцов может быть много. + +.. _dicts-external_dicts_dict_structure-key: + +Ключ +==== + +ClickHouse поддерживает следующие виды ключей: + +* Числовой ключ. Формат UInt64. Описывается в теге ````. +* Составной ключ. Набор значений разного типа. Описывается в теге ````. + +Структура может содержать либо ```` либо ````. + + +.. attention:: Ключ не надо дополнительно описывать в атрибутах. + +Числовой ключ +-------------- + +Формат: ``UInt64``. + +Пример конфигурации: + +.. code-block:: xml + + + Id + + + +Поля конфигурации: + +* name - имя столбца с ключами. + + +Составной ключ +--------------- + +Ключем может быть кортеж (``tuple``) из полей произвольных типов. :ref:`layout ` в этом случае должен быть ``complex_key_hashed`` или ``complex_key_cache``. + +.. tip:: Cоставной ключ может состоять и из одного элемента, что даёт возможность использовать в качестве ключа, например, строку. + +Структура ключа задаётся в элементе ````. Поля ключа задаются в том же формате, что и :ref:`атрибуты ` словаря. Пример: + +.. code-block:: xml + + + + + field1 + String + + + field2 + UInt32 + + ... + + ... + + +При запросе в функции ``dictGet*`` в качестве ключа передаётся кортеж. Пример: ``dictGetString('dict_name', 'attr_name', tuple('string for field1', num_for_field2))``. + + +.. _dicts-external_dicts_dict_structure-attributes: + +Атрибуты +======== + +Пример конфигурации: + +.. code-block:: xml + + + ... + + Name + Type + + rand64() + true + true + + + +Поля конфигурации: + +* ``name`` - Имя столбца. +* ``type`` - Тип столбца. Задает способ интерпретации данных в источнике. Например, в случае MySQL, в таблице-источнике поле может быть ``TEXT``, ``VARCHAR``, ``BLOB``, но загружено может быть как ``String``. +* ``null_value`` - Значение по умолчанию для несуществующего элемента. В примере - пустая строка. +* ``expression`` - Атрибут может быть выражением. Тег не обязательный. +* ``hierarchical`` - Поддержка иерархии. Отображение в идентификатор родителя. По умолчанию, ``false``. +* ``injective`` - Признак инъективности отображения ``id -> attribute``. Если ``true``, то можно оптимизировать ``GROUP BY``. По умолчанию, ``false``. diff --git a/docs/ru/dicts/index.rst b/docs/ru/dicts/index.rst index a8ad75e9cd2..8cd65b643e7 100644 --- a/docs/ru/dicts/index.rst +++ b/docs/ru/dicts/index.rst @@ -7,6 +7,6 @@ Существуют встроенные и подключаемые (внешние) словари. .. toctree:: - :glob: - * + external_dicts + internal_dicts diff --git a/docs/ru/formats/index.rst b/docs/ru/formats/index.rst index 6db2890830f..b7510f79d3b 100644 --- a/docs/ru/formats/index.rst +++ b/docs/ru/formats/index.rst @@ -1,3 +1,5 @@ +.. _formats: + Форматы ======= diff --git a/docs/ru/functions/ext_dict_functions.rst b/docs/ru/functions/ext_dict_functions.rst index 0e27687efe3..963c670c5af 100644 --- a/docs/ru/functions/ext_dict_functions.rst +++ b/docs/ru/functions/ext_dict_functions.rst @@ -1,6 +1,8 @@ +.. _ext_dict_functions: + Функции для работы с внешними словарями --------------------------------------- -Подробнее смотрите в разделе "Внешние словари". +Информация о подключении и настройке внешних словарей смотрите в разделе :ref:`dicts-external_dicts`. dictGetUInt8, dictGetUInt16, dictGetUInt32, dictGetUInt64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ru/functions/other_functions.rst b/docs/ru/functions/other_functions.rst index 32a9c0a3ed3..b9b284e4293 100644 --- a/docs/ru/functions/other_functions.rst +++ b/docs/ru/functions/other_functions.rst @@ -108,6 +108,8 @@ bar │ 23 │ 400397 │ █████████████▎ │ └────┴────────┴────────────────────┘ +.. _other_functions-transform: + transform ~~~~~~~~~ Преобразовать значение согласно явно указанному отображению одних элементов на другие. diff --git a/docs/ru/operations/server_settings/settings.rst b/docs/ru/operations/server_settings/settings.rst index c99054a18fa..9d7370e895a 100644 --- a/docs/ru/operations/server_settings/settings.rst +++ b/docs/ru/operations/server_settings/settings.rst @@ -98,9 +98,13 @@ default_profile dictionaries_config ------------------- -Конфигурация внешних словарей. +Путь к конфигурации внешних словарей. -Смотрите раздел :ref:`dicts-external_dicts`. +Путь: + * Указывается абсолютным или относительно конфигурационного файла сервера. + * Может содержать wildcard-ы \* и ?. + +Про внешние словари читайте в разделе :ref:`dicts-external_dicts`. **Пример** @@ -116,7 +120,11 @@ dictionaries_lazy_load Отложенная загрузка словарей. -С установленным параметром словари подгружаются не при запуске сервера, а при первом обращении. +Если ``true``, то каждый словарь создаётся при первом использовании. Если словарь не удалось создать, то вызов функции, использующей словарь, сгенерирует исключение. + +Если ``false``, то все словари создаются при старте сервера, и в случае ошибки сервер завершает работу. + +По умолчанию - ``true``. **Пример** From 0d876de370e72b24e2ceca411b7c58ed94973f40 Mon Sep 17 00:00:00 2001 From: BayoNet Date: Mon, 31 Jul 2017 12:17:48 +0300 Subject: [PATCH 3/5] Default `make html` language changed to russian. --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 95802e63d01..67c6263a5cd 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,7 +15,7 @@ endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = $(SPHINXOPTS) en +ALLSPHINXOPTS = $(SPHINXOPTS) ru # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ru From 215098fe70e864683a9b992c857a28bb5d70db3f Mon Sep 17 00:00:00 2001 From: BayoNet Date: Wed, 16 Aug 2017 11:14:13 +0300 Subject: [PATCH 4/5] Some errors in desctiptions are fixed --- docs/ru/dicts/external_dicts_dict.rst | 2 +- docs/ru/dicts/external_dicts_dict_sources.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ru/dicts/external_dicts_dict.rst b/docs/ru/dicts/external_dicts_dict.rst index b400261f0e5..eab4ef30381 100644 --- a/docs/ru/dicts/external_dicts_dict.rst +++ b/docs/ru/dicts/external_dicts_dict.rst @@ -31,5 +31,5 @@ * name - Идентификатор, под которым словарь будет доступен для использования. Используйте символы ``[a-zA-Z0-9_\-]``. * :ref:`source ` - Источник словаря. * :ref:`layout ` - Размещение словаря в памяти. -* :ref:`structure ` - Ключ словаря. +* :ref:`structure ` - Структура словаря. Ключ и атрибуты, которые можно получить по ключу. * :ref:`lifetime ` - Периодичность обновления словарей. diff --git a/docs/ru/dicts/external_dicts_dict_sources.rst b/docs/ru/dicts/external_dicts_dict_sources.rst index 035287b1a52..d65e59124be 100644 --- a/docs/ru/dicts/external_dicts_dict_sources.rst +++ b/docs/ru/dicts/external_dicts_dict_sources.rst @@ -102,7 +102,7 @@ HTTP(s) -Чтобы ClickHouse смог обратиться к HTTPS-ресурсу, необходимо прописать :ref:`настройки openSSL ` в конфигурации сервера. +Чтобы ClickHouse смог обратиться к HTTPS-ресурсу, необходимо :ref:`настроить openSSL ` в конфигурации сервера. Поля настройки: From 2c5c42a9177278d56bc1cd64c36399999ed314d8 Mon Sep 17 00:00:00 2001 From: BayoNet Date: Thu, 17 Aug 2017 17:37:40 +0300 Subject: [PATCH 5/5] setting of external dictionaty section is described. --- docs/ru/dicts/external_dicts.rst | 11 ++++---- docs/ru/dicts/external_dicts_dict_layout.rst | 4 --- .../ru/dicts/external_dicts_dict_lifetime.rst | 27 ++++++++++++++++++- docs/ru/dicts/external_dicts_dict_sources.rst | 14 ++++++---- 4 files changed, 41 insertions(+), 15 deletions(-) diff --git a/docs/ru/dicts/external_dicts.rst b/docs/ru/dicts/external_dicts.rst index 00374b5a91e..946187dd6f3 100644 --- a/docs/ru/dicts/external_dicts.rst +++ b/docs/ru/dicts/external_dicts.rst @@ -6,12 +6,13 @@ Существует возможность подключать собственные словари из различных источников данных. Источником данных для словаря может быть локальный текстовый/исполняемый файл, HTTP(s) ресурс или другая СУБД. Подробнее смотрите в разделе ":ref:`dicts-external_dicts_dict_sources`". -ClickHouse может полностью или частично хранить словари в оперативной памяти, периодически обновлять их и динамически подгружать отсутствующие значения. +ClickHouse: + + * Полностью или частично хранить словари в оперативной памяти. + * Периодически обновляет их и динамически подгружает отсутствующие значения. Т.е. словари можно подгружать динамически. Конфигурация внешних словарей находится в одном или нескольких файлах. Путь к конфигурации указывается в параметре :ref:`server_settings-dictionaries_config`. -Периодически ClickHouse обновляет конфигурацию словарей и словари. Т.о. словари можно подгружать динамически. - Словари могут загружаться при старте сервера или при первом использовании, в зависимости от настройки :ref:`server_settings-dictionaries_lazy_load`. Конфигурационный файл словарей имеет вид: @@ -19,7 +20,7 @@ ClickHouse может полностью или частично хранить .. code-block:: xml - Необязательный элемент с любым содержимым. Полностью игнорируется. + Необязательный элемент с любым содержимым. Игнорируется сервером ClickHouse. @@ -36,7 +37,7 @@ ClickHouse может полностью или частично хранить Смотрите также ":ref:`ext_dict_functions`" . -.. attention:: Вы можете преобразовать значения по небольшому словарю, описав его в запросе ``SELECT`` (см. функцию ":ref:`other_functions-transform`"). Эта функциональность не связана с внешними словарями. +.. attention:: Вы можете преобразовывать значения по небольшому словарю, описав его в запросе ``SELECT`` (см. функцию ":ref:`other_functions-transform`"). Эта функциональность не связана с внешними словарями. .. toctree:: :glob: diff --git a/docs/ru/dicts/external_dicts_dict_layout.rst b/docs/ru/dicts/external_dicts_dict_layout.rst index 4ee4cc6fe05..41aa1cb867c 100644 --- a/docs/ru/dicts/external_dicts_dict_layout.rst +++ b/docs/ru/dicts/external_dicts_dict_layout.rst @@ -15,10 +15,6 @@ * Вызывать функцию для работы со словарём после ``GROUP BY``. * Помечать извлекаемые атрибуты как инъективные. Атрибут называется инъективным, если разным ключам соответствуют разные значения атрибута. Тогда при использовании в ``GROUP BY`` функции, достающей значение атрибута по ключу, эта функция автоматически выносится из ``GROUP BY``. -ClickHouse периодически обновляет словари. Сначала проверяется время модификации файла/таблицы, затем, если файл/таблица обновились, обновляется словарь. Если словарь хранится в таблице типа MyISAM, то время модификации проверяется запросом ``SHOW TABLE STATUS``. Для таблиц InnoDB нельзя получить время модификации, поэтому словарь обновляется каждый раз. - -Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы - во время обновления используется старая версия словаря. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей. - При ошибках работы со словарями ClickHouse генерирует исключения. Например, в следующих ситуациях: * При обращении к словарю, который не удалось загрузить. diff --git a/docs/ru/dicts/external_dicts_dict_lifetime.rst b/docs/ru/dicts/external_dicts_dict_lifetime.rst index d3de506b800..83871a80a31 100644 --- a/docs/ru/dicts/external_dicts_dict_lifetime.rst +++ b/docs/ru/dicts/external_dicts_dict_lifetime.rst @@ -6,7 +6,7 @@ ClickHouse периодически обновляет словари. Интервал обновления для полностью загружаемых словарей и интервал инвалидации для кэшируемых словарей определяется в теге ```` в секундах. -Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы, во время обновления используется старая версия словаря. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей. +Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы - во время обновления используется старая версия словаря. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей. Пример настройки: @@ -36,3 +36,28 @@ ClickHouse периодически обновляет словари. Инте ... + + +При обновлении словарей сервер ClickHouse применяет различную логику в зависимости от типа :ref:`источника `: + + * У текстового файла проверяется время модификации. Если время изменилось по отношению к запомненному ранее, то словарь обновляется. + * Для таблиц типа MyISAM, время модификации проверяется запросом ``SHOW TABLE STATUS``. + * Словари из других источников по умолчанию обновляются каждый раз. + +Для источников MySQL (InnoDB), ODBC можно настроить запрос, который позволит обновлять словари только в случае их фактического изменения, а не каждый раз. Чтобы это сделать необходимо выполнить следующие условия/действия: + + * В таблице словаря должно быть поле, которое гарантированно изменяется при обновлении данных в источнике. + * В настройках источника указывается запрос, который получает изменяющееся поле. Результат запроса сервер ClickHouse интерпретирует как строку и если эта строка изменилась по отношению к предыдущему состоянию, то словарь обновляется. Запрос следует указывать в поле ```` настроек :ref:`источника `. + +Пример настройки: + +.. code-block:: xml + + + ... + + ... + SELECT update_time FROM dictionary_source where id = 1 + + ... + diff --git a/docs/ru/dicts/external_dicts_dict_sources.rst b/docs/ru/dicts/external_dicts_dict_sources.rst index d65e59124be..251f89adb34 100644 --- a/docs/ru/dicts/external_dicts_dict_sources.rst +++ b/docs/ru/dicts/external_dicts_dict_sources.rst @@ -125,13 +125,15 @@ ODBC DatabaseName TableName
DSN=some_parameters + SQL_REQUEST Поля настройки: -* ``db`` - Имя базы данных. Не указывать, если имя базы задано в параметрах ````. -* ``table`` - Имя таблицы. -* ``connection_string`` - Строка соединения. +* ``db`` - имя базы данных. Не указывать, если имя базы задано в параметрах ````. +* ``table`` - имя таблицы. +* ``connection_string`` - строка соединения. +* ``invalidate_query`` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе :ref:`dicts-external_dicts_dict_lifetime`. Пример подключения PostgreSQL @@ -308,6 +310,7 @@ MySQL conv_main counters
id=10 + SQL_REQUEST @@ -323,7 +326,8 @@ MySQL * ``replica/priority`` - приоритет реплики. При попытке соединения ClickHouse обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет. * ``db`` - имя базы данных. * ``table`` - имя таблицы. -* ``where`` - условие выбора. Может отсутствовать. +* ``where`` - условие выбора. Необязательный параметр. +* ``invalidate_query`` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе :ref:`dicts-external_dicts_dict_lifetime`. .. _dicts-external_dicts_dict_sources-clickhouse: @@ -385,4 +389,4 @@ MongoDB * ``user`` - имя пользователя MongoDB. * ``password`` - пароль пользователя MongoDB. * ``db`` - имя базы данных. -* ``collection`` - имя коллекции. +* ``collection`` - имя коллекции. \ No newline at end of file