ClickHouse/docs/ru/functions/ym_dict_functions.md
2018-04-28 10:58:16 +03:00

119 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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

<a name="ym_dict_functions"></a>
# Функции для работы со словарями Яндекс.Метрики
Чтобы указанные ниже функции работали, в конфиге сервера должны быть указаны пути и адреса для получения всех словарей Яндекс.Метрики. Словари загружаются при первом вызове любой из этих функций. Если справочники не удаётся загрузить - будет выкинуто исключение.
О том, как создать справочники, смотрите в разделе "Словари".
## Множественные геобазы
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.
Пример:
```text
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.
```sql
SELECT DISTINCT regionToName(regionToArea(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
```
```text
┌─regionToName(regionToArea(toUInt32(number), \'ua\'))─┐
│ │
│ Москва и Московская область │
│ Санкт-Петербург и Ленинградская область │
│ Белгородская область │
│ Ивановская область │
│ Калужская область │
│ Костромская область │
│ Курская область │
│ Липецкая область │
│ Орловская область │
│ Рязанская область │
│ Смоленская область │
│ Тамбовская область │
│ Тверская область │
│ Тульская область │
└──────────────────────────────────────────────────────┘
```
### regionToDistrict(id\[, geobase\])
Переводит регион в федеральный округ (тип в геобазе - 4). В остальном, аналогично функции regionToCity.
```sql
SELECT DISTINCT regionToName(regionToDistrict(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
```
```text
┌─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` обозначают одно и то же - украинский язык.