注意
为了使以下函数正常工作，服务器配置必须指定获取所有嵌入式字典的路径和地址。这些字典在首次调用任何这些函数时加载。如果无法加载参考列表，则会抛出异常。
因此，本节中显示的示例在 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 配置参数所定义，或者默认情况下每小时一次）。但是，可用字典的列表在服务器启动时定义一次。
所有用于处理区域的函数在末尾都有一个可选参数 – 字典键。它被称为地理数据库。
示例
regionToCountry(RegionID) – Uses the default dictionary: /opt/geo/regions_hierarchy.txt
regionToCountry(RegionID, '') – Uses the default dictionary: /opt/geo/regions_hierarchy.txt
regionToCountry(RegionID, 'ua') – Uses the dictionary for the 'ua' key: /opt/geo/regions_hierarchy_ua.txt
regionToName
接受区域 ID 和地理数据库，并返回相应语言中区域名称的字符串。如果指定 ID 的区域不存在，则返回一个空字符串。
语法
regionToName(id\[, lang\])
参数
返回值
- 相应语言中区域的名称，由
geobase 指定。 String。
- 否则，返回一个空字符串。
示例
查询
SELECT regionToName(number::UInt32,'en') FROM numbers(0,5);
结果
┌─regionToName(CAST(number, 'UInt32'), 'en')─┐
│ │
│ World │
│ USA │
│ Colorado │
│ Boulder County │
└────────────────────────────────────────────┘
regionToCity
接受来自地理数据库的区域 ID。如果该区域是城市或城市的一部分，则返回适当城市的区域 ID。否则，返回 0。
语法
regionToCity(id [, geobase])
参数
返回值
- 适当城市的区域 ID（如果存在）。 UInt32。
- 如果没有，则返回 0。
示例
查询
SELECT regionToName(number::UInt32, 'en'), regionToCity(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
结果
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToCity(CAST(number, 'UInt32')), 'en')─┐
│ │ 0 │ │
│ World │ 0 │ │
│ USA │ 0 │ │
│ Colorado │ 0 │ │
│ Boulder County │ 0 │ │
│ Boulder │ 5 │ Boulder │
│ China │ 0 │ │
│ Sichuan │ 0 │ │
│ Chengdu │ 8 │ Chengdu │
│ America │ 0 │ │
│ North America │ 0 │ │
│ Eurasia │ 0 │ │
│ Asia │ 0 │ │
└────────────────────────────────────────────┴────┴──────────────────────────────────────────────────────────┘
regionToArea
将区域转换为区域（地理数据库中的类型 5）。在其他方面，此函数与 'regionToCity' 相同。
语法
regionToArea(id [, geobase])
参数
返回值
- 适当区域的区域 ID（如果存在）。 UInt32。
- 如果没有，则返回 0。
示例
查询
SELECT DISTINCT regionToName(regionToArea(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
结果
┌─regionToName(regionToArea(toUInt32(number), \'ua\'))─┐
│ │
│ Moscow and Moscow region │
│ St. Petersburg and Leningrad region │
│ Belgorod region │
│ Ivanovsk region │
│ Kaluga region │
│ Kostroma region │
│ Kursk region │
│ Lipetsk region │
│ Orlov region │
│ Ryazan region │
│ Smolensk region │
│ Tambov region │
│ Tver region │
│ Tula region │
└──────────────────────────────────────────────────────┘
regionToDistrict
将区域转换为联邦区（地理数据库中的类型 4）。在其他方面，此函数与 'regionToCity' 相同。
语法
regionToDistrict(id [, geobase])
参数
返回值
- 适当城市的区域 ID（如果存在）。 UInt32。
- 如果没有，则返回 0。
示例
查询
SELECT DISTINCT regionToName(regionToDistrict(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
结果
┌─regionToName(regionToDistrict(toUInt32(number), \'ua\'))─┐
│ │
│ Central federal district │
│ Northwest federal district │
│ South federal district │
│ North Caucases federal district │
│ Privolga federal district │
│ Ural federal district │
│ Siberian federal district │
│ Far East federal district │
│ Scotland │
│ Faroe Islands │
│ Flemish region │
│ Brussels capital region │
│ Wallonia │
│ Federation of Bosnia and Herzegovina │
└──────────────────────────────────────────────────────────┘
regionToCountry
将区域转换为国家/地区（地理数据库中的类型 3）。在其他方面，此函数与 'regionToCity' 相同。
语法
regionToCountry(id [, geobase])
参数
返回值
- 适当国家的区域 ID（如果存在）。 UInt32。
- 如果没有，则返回 0。
示例
查询
SELECT regionToName(number::UInt32, 'en'), regionToCountry(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
结果
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToCountry(CAST(number, 'UInt32')), 'en')─┐
│ │ 0 │ │
│ World │ 0 │ │
│ USA │ 2 │ USA │
│ Colorado │ 2 │ USA │
│ Boulder County │ 2 │ USA │
│ Boulder │ 2 │ USA │
│ China │ 6 │ China │
│ Sichuan │ 6 │ China │
│ Chengdu │ 6 │ China │
│ America │ 0 │ │
│ North America │ 0 │ │
│ Eurasia │ 0 │ │
│ Asia │ 0 │ │
└────────────────────────────────────────────┴────┴─────────────────────────────────────────────────────────────┘
regionToContinent
将区域转换为大陆（地理数据库中的类型 1）。在其他方面，此函数与 'regionToCity' 相同。
语法
regionToContinent(id [, geobase])
参数
返回值
- 适当大陆的区域 ID（如果存在）。 UInt32。
- 如果没有，则返回 0。
示例
查询
SELECT regionToName(number::UInt32, 'en'), regionToContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
结果
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToContinent(CAST(number, 'UInt32')), 'en')─┐
│ │ 0 │ │
│ World │ 0 │ │
│ USA │ 10 │ North America │
│ Colorado │ 10 │ North America │
│ Boulder County │ 10 │ North America │
│ Boulder │ 10 │ North America │
│ China │ 12 │ Asia │
│ Sichuan │ 12 │ Asia │
│ Chengdu │ 12 │ Asia │
│ America │ 9 │ America │
│ North America │ 10 │ North America │
│ Eurasia │ 11 │ Eurasia │
│ Asia │ 12 │ Asia │
└────────────────────────────────────────────┴────┴───────────────────────────────────────────────────────────────┘
regionToTopContinent
查找区域层次结构中的最高大陆。
语法
regionToTopContinent(id[, geobase])
参数
返回值
- 顶级大陆的标识符（沿区域层次结构向上爬时，后者）。UInt32。
- 如果没有，则返回 0。
示例
查询
SELECT regionToName(number::UInt32, 'en'), regionToTopContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
结果
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─id─┬─regionToName(regionToTopContinent(CAST(number, 'UInt32')), 'en')─┐
│ │ 0 │ │
│ World │ 0 │ │
│ USA │ 9 │ America │
│ Colorado │ 9 │ America │
│ Boulder County │ 9 │ America │
│ Boulder │ 9 │ America │
│ China │ 11 │ Eurasia │
│ Sichuan │ 11 │ Eurasia │
│ Chengdu │ 11 │ Eurasia │
│ America │ 9 │ America │
│ North America │ 9 │ America │
│ Eurasia │ 11 │ Eurasia │
│ Asia │ 11 │ Eurasia │
└────────────────────────────────────────────┴────┴──────────────────────────────────────────────────────────────────┘
regionToPopulation
获取区域的人口。人口可以在包含地理数据库的文件中记录。请参阅 “字典” 部分。如果未记录区域的人口，则返回 0。在地理数据库中，人口可能记录在子区域中，但不在父区域中。
语法
regionToPopulation(id[, geobase])
参数
返回值
示例
查询
SELECT regionToName(number::UInt32, 'en'), regionToPopulation(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
结果
┌─regionToName(CAST(number, 'UInt32'), 'en')─┬─population─┐
│ │ 0 │
│ World │ 4294967295 │
│ USA │ 330000000 │
│ Colorado │ 5700000 │
│ Boulder County │ 330000 │
│ Boulder │ 100000 │
│ China │ 1500000000 │
│ Sichuan │ 83000000 │
│ Chengdu │ 20000000 │
│ America │ 1000000000 │
│ North America │ 600000000 │
│ Eurasia │ 4294967295 │
│ Asia │ 4294967295 │
└────────────────────────────────────────────┴────────────┘
regionIn
检查 lhs 区域是否属于 rhs 区域。如果属于，则返回等于 1 的 UInt8 数字；如果不属于，则返回 0。
语法
regionIn(lhs, rhs\[, geobase\])
参数
返回值
- 如果属于，则返回 1。 UInt8。
- 如果不属于，则返回 0。
实现细节
关系是自反的 – 任何区域也属于自身。
示例
查询
SELECT regionToName(n1.number::UInt32, 'en') || (regionIn(n1.number::UInt32, n2.number::UInt32) ? ' is in ' : ' is not in ') || regionToName(n2.number::UInt32, 'en') FROM numbers(1,2) AS n1 CROSS JOIN numbers(1,5) AS n2;
结果
World is in World
World is not in USA
World is not in Colorado
World is not in Boulder County
World is not in Boulder
USA is in World
USA is in USA
USA is not in Colorado
USA is not in Boulder County
USA is not in Boulder
regionHierarchy
接受一个 UInt32 数字 – 来自地理数据库的区域 ID。返回一个区域 ID 数组，包含传递的区域以及链中所有父区域。
语法
regionHierarchy(id\[, geobase\])
参数
返回值
示例
查询
SELECT regionHierarchy(number::UInt32) AS arr, arrayMap(id -> regionToName(id, 'en'), arr) FROM numbers(5);
结果
┌─arr────────────┬─arrayMap(lambda(tuple(id), regionToName(id, 'en')), regionHierarchy(CAST(number, 'UInt32')))─┐
│ [] │ [] │
│ [1] │ ['World'] │
│ [2,10,9,1] │ ['USA','North America','America','World'] │
│ [3,2,10,9,1] │ ['Colorado','USA','North America','America','World'] │
│ [4,3,2,10,9,1] │ ['Boulder County','Colorado','USA','North America','America','World'] │
└────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘
