使用嵌入式字典的函数
注意
为了使以下函数正常工作，服务器配置必须指定获取所有嵌入式字典的路径和地址。这些字典在第一次调用任何这些函数时加载。如果无法加载参考列表，则会抛出异常。
因此，本节中显示的示例在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'] │
└────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘