Функции для работы с встроенными словарями
Для корректной работы приведенных ниже функций конфигурация сервера должна указывать пути и адреса для получения всех встроенных словарей. Словари загружаются при первом вызове любой из этих функций. Если референсные списки не могут быть загружены, выбрасывается исключение.
Таким образом, примеры, приведенные в этом разделе, вызовут исключение в ClickHouse Fiddle и в быстром релизе и продуктивных развертываниях по умолчанию, если сначала не настроены.
Для получения информации о создании референсных списков, см. раздел "Словари".
Несколько геобаз
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, или раз в час по умолчанию). Тем не менее, список доступных словарей определяется один раз, когда сервер запускается.
Все функции для работы с регионами имеют необязательный аргумент в конце — ключ словаря. Он называется геобазой.
Пример:
regionToName
Принимает ID региона и геобазу и возвращает строку с названием региона на соответствующем языке. Если регион с указанным ID не существует, возвращается пустая строка.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- Название региона на соответствующем языке, указанном
geobase. String. - В противном случае — пустая строка.
Пример
Запрос:
Результат:
regionToCity
Принимает ID региона из геобазы. Если этот регион является городом или частью города, возвращает ID региона для соответствующего города. В противном случае возвращает 0.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- ID региона для соответствующего города, если он существует. UInt32.
- 0, если его нет.
Пример
Запрос:
Результат:
regionToArea
Преобразует регион в область (тип 5 в геобазе). Во всем остальном эта функция такая же, как 'regionToCity'.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- ID региона для соответствующей области, если он существует. UInt32.
- 0, если его нет.
Пример
Запрос:
Результат:
regionToDistrict
Преобразует регион в федеральный округ (тип 4 в геобазе). Во всем остальном эта функция такая же, как 'regionToCity'.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- ID региона для соответствующего округа, если он существует. UInt32.
- 0, если его нет.
Пример
Запрос:
Результат:
regionToCountry
Преобразует регион в страну (тип 3 в геобазе). Во всем остальном эта функция такая же, как 'regionToCity'.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- ID региона для соответствующей страны, если он существует. UInt32.
- 0, если его нет.
Пример
Запрос:
Результат:
regionToContinent
Преобразует регион в континент (тип 1 в геобазе). Во всем остальном эта функция такая же, как 'regionToCity'.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- ID региона для соответствующего континента, если он существует. UInt32.
- 0, если его нет.
Пример
Запрос:
Результат:
regionToTopContinent
Находит самый высокий континент в иерархии для региона.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- Идентификатор континента верхнего уровня (последнего, когда вы поднимаетесь по иерархии регионов). UInt32.
- 0, если его нет.
Пример
Запрос:
Результат:
regionToPopulation
Получает население для региона. Население может быть зафиксировано в файлах с геобазой. См. раздел "Словари". Если население не зафиксировано для региона, возвращает 0. В геобазе население может быть зафиксировано для дочерних регионов, но не для родительских регионов.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- Население для региона. UInt32.
- 0, если его нет.
Пример
Запрос:
Результат:
regionIn
Проверяет, принадлежит ли lhs регион к rhs региону. Возвращает число UInt8, равное 1, если принадлежит, или 0, если не принадлежит.
Синтаксис
Параметры
lhs— ID региона lhs из геобазы. UInt32.rhs— ID региона rhs из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
- 1, если принадлежит. UInt8.
- 0, если не принадлежит.
Детали реализации
Отношение является рефлексивным — любой регион также принадлежит самому себе.
Пример
Запрос:
Результат:
regionHierarchy
Принимает число UInt32 — ID региона из геобазы. Возвращает массив ID регионов, состоящий из переданного региона и всех предков вдоль цепочки.
Синтаксис
Параметры
id— ID региона из геобазы. UInt32.geobase— Ключ словаря. См. Несколько геобаз. String. Необязательный.
Возвращаемое значение
Пример
Запрос:
Результат: