ClickHouse/doc/reference/ru/functions/ym_dict_functions.rst

Функции для работы со словарями Яндекс.Метрики
----------------------------------------------
Чтобы указанные ниже функции работали, в конфиге сервера должны быть указаны пути и адреса для получения всех словарей Яндекс.Метрики. Словари загружаются при первом вызове любой из этих функций. Если справочники не удаётся загрузить - будет выкинуто исключение.

О том, как создать справочники, смотрите в разделе "Словари".

Множественные геобазы
~~~~~~~~~~~~~~~~~~~~~
ClickHouse поддерживает работу одновременно с несколькими альтернативными геобазами (иерархиями регионов), для того чтобы можно было поддержать разные точки зрения о принадлежности регионов странам.

В конфиге clickhouse-server указывается файл с иерархией регионов:
``<path_to_regions_hierarchy_file>/opt/geo/regions_hierarchy.txt</path_to_regions_hierarchy_file>``

Кроме указанного файла, рядом ищутся файлы, к имени которых (до расширения) добавлен символ _ и какой угодно суффикс.
Например, также найдётся файл ``/opt/geo/regions_hierarchy_ua.txt``, если такой есть.

``ua`` называется ключом словаря. Для словаря без суффикса, ключ является пустой строкой.

Все словари перезагружаются в рантайме (раз в количество секунд, заданное в конфигурационном параметре builtin_dictionaries_reload_interval, по умолчанию - раз в час), но перечень доступных словарей определяется один раз, при старте сервера.

Во все функции по работе с регионами, в конце добавлен один необязательный аргумент - ключ словаря. Далее он обозначен как geobase.
Пример:
::

  regionToCountry(RegionID) - использует словарь по умолчанию: /opt/geo/regions_hierarchy.txt;
  regionToCountry(RegionID, '') - использует словарь по умолчанию: /opt/geo/regions_hierarchy.txt;
  regionToCountry(RegionID, 'ua') - использует словарь для ключа ua: /opt/geo/regions_hierarchy_ua.txt;

regionToCity(id[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Принимает число типа UInt32 - идентификатор региона из геобазы Яндекса. Если регион является городом или входит в некоторый город, то возвращает идентификатор региона - соответствующего города. Иначе возвращает 0.

regionToArea(id[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Переводит регион в область (тип в геобазе - 5). В остальном, аналогично функции regionToCity.

.. code-block:: sql

  SELECT DISTINCT regionToName(regionToArea(toUInt32(number), 'ua'))
  FROM system.numbers
  LIMIT 15

  ┌─regionToName(regionToArea(toUInt32(number), \'ua\'))─┐
  │                                                      │
  │ Москва и Московская область                          │
  │ Санкт-Петербург и Ленинградская область              │
  │ Белгородская область                                 │
  │ Ивановская область                                   │
  │ Калужская область                                    │
  │ Костромская область                                  │
  │ Курская область                                      │
  │ Липецкая область                                     │
  │ Орловская область                                    │
  │ Рязанская область                                    │
  │ Смоленская область                                   │
  │ Тамбовская область                                   │
  │ Тверская область                                     │
  │ Тульская область                                     │
  └──────────────────────────────────────────────────────┘

regionToDistrict(id[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Переводит регион в федеральный округ (тип в геобазе - 4). В остальном, аналогично функции regionToCity.

.. code-block:: sql

  SELECT DISTINCT regionToName(regionToDistrict(toUInt32(number), 'ua'))
  FROM system.numbers
  LIMIT 15

  ┌─regionToName(regionToDistrict(toUInt32(number), \'ua\'))─┐
  │                                                          │
  │ Центральный федеральный округ                            │
  │ Северо-Западный федеральный округ                        │
  │ Южный федеральный округ                                  │
  │ Северо-Кавказский федеральный округ                      │
  │ Приволжский федеральный округ                            │
  │ Уральский федеральный округ                              │
  │ Сибирский федеральный округ                              │
  │ Дальневосточный федеральный округ                        │
  │ Шотландия                                                │
  │ Фарерские острова                                        │
  │ Фламандский регион                                       │
  │ Брюссельский столичный регион                            │
  │ Валлония                                                 │
  │ Федерация Боснии и Герцеговины                           │
  └──────────────────────────────────────────────────────────┘

regionToCountry(id[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Переводит регион в страну. В остальном, аналогично функции regionToCity.
Пример: ``regionToCountry(toUInt32(213)) = 225`` - преобразовали Москву (213) в Россию (225).

regionToContinent(id[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Переводит регион в континент. В остальном, аналогично функции regionToCity.
Пример: ``regionToContinent(toUInt32(213)) = 10001`` - преобразовали Москву (213) в Евразию (10001).

regionToPopulation(id[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Получает население для региона.
Население может быть прописано в файлах с геобазой. Смотрите в разделе "Встроенные словари".
Если для региона не прописано население, возвращается 0.
В геобазе Яндекса, население может быть прописано для дочерних регионов, но не прописано для родительских.

regionIn(lhs, rhs[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Проверяет принадлежность региона lhs региону rhs. Возвращает число типа UInt8, равное 1, если принадлежит и 0, если не принадлежит.
Отношение рефлексивное - любой регион принадлежит также самому себе.

regionHierarchy(id[, geobase])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Принимает число типа UInt32 - идентификатор региона из геобазы Яндекса. Возвращает массив идентификаторов регионов, состоящий из переданного региона и всех родителей по цепочке.
Пример: ``regionHierarchy(toUInt32(213)) = [213,1,3,225,10001,10000]``.

regionToName(id[, lang])
~~~~~~~~~~~~~~~~~~~~~~~~
Принимает число типа UInt32 - идентификатор региона из геобазы Яндекса. Вторым аргументом может быть передана строка - название языка. Поддерживаются языки ru, en, ua, uk, by, kz, tr. Если второй аргумент отсутствует - используется язык ru. Если язык не поддерживается - кидается исключение. Возвращает строку - название региона на соответствующем языке. Если региона с указанным идентификатором не существует - возвращается пустая строка.

``ua`` и ``uk`` обозначают одно и то же - украинский язык.