嵌入式字典函数
注意
为了使以下函数能够工作，服务器配置必须指定用于获取所有嵌入式字典的路径和地址。字典在首次调用这些函数中的任何一个时加载。如果无法加载参考列表，则会抛出异常。
因此，默认情况下，除非首先配置，否则本节中显示的示例将在 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])
参数
返回值
- 区域的人口。 UInt32。
- 0，如果不存在。
示例
查询
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'] │
└────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘