> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse 内置的 geobase 字典

# 嵌入式（geobase）字典

<CloudNotSupportedBadge />

<Note>
  本页不适用于 [ClickHouse Cloud](https://clickhouse.com/cloud)。本文档介绍的功能不适用于 ClickHouse Cloud 服务。
  更多信息，请参阅 ClickHouse 的 [Cloud Compatibility](/zh/products/cloud/guides/cloud-compatibility) 指南。
</Note>

ClickHouse 内置了用于处理 geobase 的功能。

这使你能够：

* 使用区域 ID 获取其在指定语言中的名称。
* 使用区域 ID 获取城市、地区、联邦区、国家或洲的 ID。
* 检查一个区域是否属于另一个区域。
* 获取父级区域链。

所有函数都支持“translocality”，即能够同时采用不同的区域归属视角。更多信息，请参见“用于处理网站分析字典的函数”一节。

默认安装包中禁用了内部字典。
要启用它们，请在服务器配置文件中取消注释参数 `path_to_regions_hierarchy_file` 和 `path_to_regions_names_files`。

geobase 从文本文件加载。

将 `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 (无表头) ，列：

* 区域 ID (`UInt32`)
* 父区域 ID (`UInt32`)
* 区域类型 (`UInt8`)：1 - 洲，3 - 国家，4 - 联邦区，5 - 区域，6 - 城市；其他类型没有值
* 人口 (`UInt32`) — 可选列

`regions_names_*.txt`：TabSeparated (无表头) ，列：

* 区域 ID (`UInt32`)
* 区域名称 (`String`) — 不能包含制表符或换行符，即使是转义后的也不行。

在 RAM 中使用扁平数组存储。因此，ID 不应大于一百万。

字典可以在不重启服务器的情况下更新。但是，可用字典的集合不会更新。
更新时会检查文件的修改时间。如果文件已更改，则会更新字典。
检查更改的时间间隔由 `builtin_dictionaries_reload_interval` 参数配置。
字典更新 (首次使用时的加载除外) 不会阻塞查询。更新期间，查询会使用字典的旧版本。如果更新过程中发生错误，错误会写入服务器日志，查询将继续使用字典的旧版本。

我们建议定期使用 geobase 更新字典。在更新期间，生成新文件并将其写入单独的位置。一切准备就绪后，将它们重命名为服务器使用的文件。

还有一些用于处理 OS 标识符和搜索引擎的函数，但不应使用它们。