ClickHouse/docs/ru/query_language/dicts/internal_dicts.md

# Встроенные словари {#internal_dicts}

ClickHouse содержит встроенную возможность работы с геобазой.

Это позволяет:

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

Все функции поддерживают «транслокальность», то есть возможность использовать одновременно разные точки зрения на принадлежность регионов. Подробнее смотрите в разделе «Функции для работы со словарями Яндекс.Метрики».

В пакете по умолчанию, встроенные словари выключены.
Для включения, раскомментируйте параметры `path_to_regions_hierarchy_file` и `path_to_regions_names_files` в конфигурационном файле сервера.

Геобаза загружается из текстовых файлов.

Положите файлы `regions_hierarchy*.txt` в директорию `path_to_regions_hierarchy_file`. Этот конфигурационный параметр должен содержать путь к файлу `regions_hierarchy.txt` (иерархия регионов по умолчанию), а другие файлы (`regions_hierarchy_ua.txt`) должны находиться рядом в той же директории.

Положите файлы `regions_names_*.txt` в директорию `path_to_regions_names_files`.

Также вы можете создать эти файлы самостоятельно. Формат файлов такой:

`regions_hierarchy*.txt`: TabSeparated (без заголовка), столбцы:

- идентификатор региона (`UInt32`);
- идентификатор родительского региона (`UInt32`);
- тип региона (`UInt8`): 1 - континент, 3 - страна, 4 - федеральный округ, 5 - область, 6 - город; остальные типы не имеют значения;
- население (`UInt32`) - не обязательный столбец.

`regions_names_*.txt`: TabSeparated (без заголовка), столбцы:

- идентификатор региона (`UInt32`);
- имя региона (`String`) - не может содержать табы или переводы строк, даже экранированные.

Для хранения в оперативке используется плоский массив. Поэтому, идентификаторы не должны быть больше миллиона.

Словари могут обновляться без перезапуска сервера. Но набор доступных словарей не обновляется.
Для обновления проверяется время модификации файлов; если файл изменился, то словарь будет обновлён.
Периодичность проверки настраивается конфигурационным параметром `builtin_dictionaries_reload_interval`.
Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы - во время обновления запросы используют старую версию словарей. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей.

Рекомендуется периодически обновлять словари с геобазой. При обновлении, генерируйте новые файлы, записывая их в отдельное место, а только когда всё готово - переименовывайте в файлы, которые использует сервер.

Также имеются функции для работы с идентификаторами операционных систем и поисковых систем Яндекс.Метрики, пользоваться которыми не нужно.

[Оригинальная статья](https://clickhouse.tech/docs/ru/query_language/dicts/internal_dicts/) <!--hide-->
-												Restore some old manual anchors in docs (#9803)

* Simplify 404 page

* add es array_functions.md

* restore some old manual anchors

* update sitemaps

* trigger checks

* restore more old manual anchors

* refactor test.md + temporary disable failure again

* fix mistype
											
										
										
											2020-03-22 09:14:59 +00:00
+								# Встроенные словари {#internal_dicts}
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
 								ClickHouse содержит встроенную возможность работы с геобазой.
 								Это позволяет:
-												Replacing 'RestructuredText' sources with the 'Markdown' ones.

											
										
										
											2017-10-25 05:27:09 +00:00
-												WIP on docs translation/normalization tools (#9783)


											
										
										
											2020-03-20 18:20:59 +00:00
+								- для идентификатора региона получить его имя на нужном языке;
 								- по идентификатору региона получить идентификатор города, области, федерального округа, страны, континента;
 								- проверить, что один регион входит в другой;
 								- получить цепочку родительских регионов.
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
-												WIP on docs translation/normalization tools (#9783)


											
										
										
											2020-03-20 18:20:59 +00:00
+								Все функции поддерживают «транслокальность», то есть возможность использовать одновременно разные точки зрения на принадлежность регионов. Подробнее смотрите в разделе «Функции для работы со словарями Яндекс.Метрики».
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
 								В пакете по умолчанию, встроенные словари выключены.
-												Replacing 'RestructuredText' sources with the 'Markdown' ones.

											
										
										
											2017-10-25 05:27:09 +00:00
+								Для включения, раскомментируйте параметры `path_to_regions_hierarchy_file` и `path_to_regions_names_files` в конфигурационном файле сервера.
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
 								Геобаза загружается из текстовых файлов.
-												Multiple formatting and links fixes.

											
										
										
											2018-04-28 07:58:16 +00:00
+								Положите файлы `regions_hierarchy*.txt` в директорию `path_to_regions_hierarchy_file`. Этот конфигурационный параметр должен содержать путь к файлу `regions_hierarchy.txt` (иерархия регионов по умолчанию), а другие файлы (`regions_hierarchy_ua.txt`) должны находиться рядом в той же директории.
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
-												Multiple formatting and links fixes.

											
										
										
											2018-04-28 07:58:16 +00:00
+								Положите файлы `regions_names_*.txt` в директорию `path_to_regions_names_files`.
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
 								Также вы можете создать эти файлы самостоятельно. Формат файлов такой:
-												Replacing 'RestructuredText' sources with the 'Markdown' ones.

											
										
										
											2017-10-25 05:27:09 +00:00
+								`regions_hierarchy*.txt`: TabSeparated (без заголовка), столбцы:
-												WIP on docs translation/normalization tools (#9783)


											
										
										
											2020-03-20 18:20:59 +00:00
+								- идентификатор региона (`UInt32`);
 								- идентификатор родительского региона (`UInt32`);
 								- тип региона (`UInt8`): 1 - континент, 3 - страна, 4 - федеральный округ, 5 - область, 6 - город; остальные типы не имеют значения;
 								- население (`UInt32`) - не обязательный столбец.
-												Replacing 'RestructuredText' sources with the 'Markdown' ones.

											
										
										
											2017-10-25 05:27:09 +00:00
 								`regions_names_*.txt`: TabSeparated (без заголовка), столбцы:
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
-												WIP on docs translation/normalization tools (#9783)


											
										
										
											2020-03-20 18:20:59 +00:00
+								- идентификатор региона (`UInt32`);
 								- имя региона (`String`) - не может содержать табы или переводы строк, даже экранированные.
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
 								Для хранения в оперативке используется плоский массив. Поэтому, идентификаторы не должны быть больше миллиона.
 								Словари могут обновляться без перезапуска сервера. Но набор доступных словарей не обновляется.
 								Для обновления проверяется время модификации файлов; если файл изменился, то словарь будет обновлён.
-												Multiple formatting and links fixes.

											
										
										
											2018-04-28 07:58:16 +00:00
+								Периодичность проверки настраивается конфигурационным параметром `builtin_dictionaries_reload_interval`.
-												Added documentation in RST format. (ReadTheDocs ready)

											
										
										
											2017-03-12 17:58:51 +00:00
+								Обновление словарей (кроме загрузки при первом использовании) не блокирует запросы - во время обновления запросы используют старую версию словарей. Если при обновлении возникнет ошибка, то ошибка пишется в лог сервера, а запросы продолжат использовать старую версию словарей.
 								Рекомендуется периодически обновлять словари с геобазой. При обновлении, генерируйте новые файлы, записывая их в отдельное место, а только когда всё готово - переименовывайте в файлы, которые использует сервер.
 								Также имеются функции для работы с идентификаторами операционных систем и поисковых систем Яндекс.Метрики, пользоваться которыми не нужно.
-												WIP on docs/website (#3383)

* CLICKHOUSE-4063: less manual html @ index.md

* CLICKHOUSE-4063: recommend markdown="1" in README.md

* CLICKHOUSE-4003: manually purge custom.css for now

* CLICKHOUSE-4064: expand <details> before any print (including to pdf)

* CLICKHOUSE-3927: rearrange interfaces/formats.md a bit

* CLICKHOUSE-3306: add few http headers

* Remove copy-paste introduced in #3392

* Hopefully better chinese fonts #3392

* get rid of tabs @ custom.css

* Apply comments and patch from #3384

* Add jdbc.md to ToC and some translation, though it still looks badly incomplete

* minor punctuation

* Add some backlinks to official website from mirrors that just blindly take markdown sources

* Do not make fonts extra light

* find . -name '*.md' -type f | xargs -I{} perl -pi -e 's//g' {}

* find . -name '*.md' -type f | xargs -I{} perl -pi -e 's/ sql/g' {}

* Remove outdated stuff from roadmap.md

* Not so light font on front page too

* Refactor Chinese formats.md to match recent changes in other languages

											
										
										
											2018-10-16 10:47:17 +00:00
-												Domain change in docs

											
										
										
											2020-01-30 10:34:55 +00:00
+								[Оригинальная статья](https://clickhouse.tech/docs/ru/query_language/dicts/internal_dicts/) <!--hide-->