> ## 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.
> 埋め込み Dictionary を操作する関数のドキュメント
# 埋め込み Dictionary を操作する関数
以下の関数を動作させるには、すべての埋め込み Dictionary を取得するためのパスとアドレスをサーバー設定で指定しておく必要があります。これらの Dictionary は、これらの関数のいずれかが最初に呼び出されたときに読み込まれます。参照リストを読み込めない場合は、例外が発生します。
そのため、このセクションの例は、事前に設定しない限り、デフォルトでは [ClickHouse Fiddle](https://fiddle.clickhouse.com/) とクイックリリース環境および本番環境のデプロイメントで例外を発生させます。
参照リストの作成方法については、[「Dictionaries」](/ja/reference/statements/create/dictionary/embedded) セクションを参照してください。
## 複数のジオベース
ClickHouse は、特定の地域がどの国に属するかについてのさまざまな見方に対応するため、複数の代替 geobase (地域階層) を同時に扱うことをサポートしています。
`clickhouse-server` の設定では、地域階層のファイルを指定します。
`/opt/geo/regions_hierarchy.txt`
このファイルに加えて、同じ場所にあり、ファイル名に `_` 記号と任意の接尾辞が付いたファイル (拡張子の前) も検索されます。
たとえば、`/opt/geo/regions_hierarchy_ua.txt` というファイルが存在すれば、それも検出されます。ここで `ua` は辞書キーと呼ばれます。接尾辞のない Dictionary では、キーは空文字列です。
すべての Dictionary は実行時に再読み込みされます ([`builtin_dictionaries_reload_interval`](/ja/reference/settings/server-settings/settings#builtin_dictionaries_reload_interval) 設定パラメータで定義された一定秒数ごと、またはデフォルトでは 1 時間ごと) 。ただし、利用可能な Dictionary の一覧は、サーバーの起動時に一度だけ定義されます。
地域を扱うすべての関数には、末尾に省略可能な引数として辞書キーを指定できます。これを geobase と呼びます。
例:
```sql theme={null}
regionToCountry(RegionID) – デフォルトのDictionaryを使用: /opt/geo/regions_hierarchy.txt
regionToCountry(RegionID, '') – デフォルトのDictionaryを使用: /opt/geo/regions_hierarchy.txt
regionToCountry(RegionID, 'ua') – 'ua' キーのDictionaryを使用: /opt/geo/regions_hierarchy_ua.txt
```
### regionToName
Region ID と geobase を受け取り、対応する言語で地域名を表す文字列を返します。指定した ID の地域が存在しない場合は、空文字列が返されます。
**構文**
```sql theme={null}
regionToName(id\[, lang\])
```
**パラメータ**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases)を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* `geobase` で指定された言語に対応する地域名。[String](/ja/reference/data-types/string)。
* それ以外の場合は空文字列。
**例**
```sql title="Query" theme={null}
SELECT regionToName(number::UInt32,'en') FROM numbers(0,5);
```
```text title="Response" theme={null}
┌─regionToName(CAST(number, 'UInt32'), 'en')─┐
│ │
│ World │
│ USA │
│ Colorado │
│ Boulder County │
└────────────────────────────────────────────┘
```
### regionToCity
geobase の地域IDを受け取ります。この地域が都市または都市の一部である場合は、対応する都市の地域IDを返します。それ以外の場合は 0 を返します。
**構文**
```sql theme={null}
regionToCity(id [, geobase])
```
**パラメータ**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases)を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 該当する都市が存在する場合は、その都市の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* 存在しない場合は 0。
**例**
```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToCity(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```
```response title="Response" theme={null}
┌─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
region を area (geobase の type 5) に変換します。その他の点については、この関数は ['regionToCity'](#regiontocity) と同じです。
**構文**
```sql theme={null}
regionToArea(id [, geobase])
```
**パラメータ**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases) を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 該当する地域が存在する場合は、その Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* 存在しない場合は 0。
**例**
```sql title="Query" theme={null}
SELECT DISTINCT regionToName(regionToArea(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
```
```text title="Response" theme={null}
┌─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
リージョンを連邦管区 (geobase の type 4) に変換します。その他の点では、この関数は 'regionToCity' と同じです。
**構文**
```sql theme={null}
regionToDistrict(id [, geobase])
```
**パラメータ**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases) を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 該当する都市が存在する場合は、その都市の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* 存在しない場合は 0。
**例**
```sql title="Query" theme={null}
SELECT DISTINCT regionToName(regionToDistrict(toUInt32(number), 'ua'))
FROM system.numbers
LIMIT 15
```
```text title="Response" theme={null}
┌─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
region を国 (geobase の type 3) に変換します。その他の点については、この関数は 'regionToCity' と同じです。
**構文**
```sql theme={null}
regionToCountry(id [, geobase])
```
**パラメーター**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases)を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 存在する場合は、該当する国の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* 存在しない場合は 0。
**例**
```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToCountry(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```
```text title="Response" theme={null}
┌─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
リージョンを大陸 (geobase の type 1) に変換します。それ以外は、この関数は 'regionToCity' と同じです。
**構文**
```sql theme={null}
regionToContinent(id [, geobase])
```
**パラメータ**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases) を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 該当する大陸が存在する場合は、その Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* 存在しない場合は 0。
**例**
```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```
```text title="Response" theme={null}
┌─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
指定した地域が属する階層の中で最上位の大陸を返します。
**構文**
```sql theme={null}
regionToTopContinent(id[, geobase])
```
**パラメータ**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases) を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 地域階層をさかのぼったときの、最上位の大陸の識別子。[UInt32](/ja/reference/data-types/int-uint)。
* 存在しない場合は 0。
**例**
```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToTopContinent(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```
```text title="Response" theme={null}
┌─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
地域の人口を取得します。人口は geobase を含むファイルに記録できます。["Dictionaries"](/ja/reference/statements/create/dictionary/embedded) のセクションを参照してください。地域の人口が記録されていない場合は、0 を返します。geobase では、子地域には人口が記録されていても、親地域には記録されていないことがあります。
**Syntax**
```sql theme={null}
regionToPopulation(id[, geobase])
```
**パラメータ**
* `id` — geobase の Region ID。 [UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。 [複数のジオベース](#multiple-geobases) を参照してください。 [String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* そのリージョンの人口。 [UInt32](/ja/reference/data-types/int-uint)。
* 該当するものがない場合は 0。
**例**
```sql title="Query" theme={null}
SELECT regionToName(number::UInt32, 'en'), regionToPopulation(number::UInt32) AS id, regionToName(id, 'en') FROM numbers(13);
```
```text title="Response" theme={null}
┌─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、属さない場合は 0 を返します。返り値は UInt8 です。
**構文**
```sql theme={null}
regionIn(lhs, rhs\[, geobase\])
```
**パラメータ**
* `lhs` — geobase 内の lhs の地域 ID。[UInt32](/ja/reference/data-types/int-uint)。
* `rhs` — geobase 内の rhs の地域 ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases)を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 属する場合は 1。[UInt8](/ja/reference/data-types/int-uint)。
* 属さない場合は 0。
**実装の詳細**
この関係は反射的です。つまり、どの地域もそれ自身に属します。
**例**
```sql title="Query" theme={null}
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;
```
```text title="Response" theme={null}
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 の数値 (geobase の地域 ID) を受け取ります。指定した地域と、その階層上のすべての親地域を含む地域 ID の配列を返します。
**構文**
```sql theme={null}
regionHierarchy(id\[, geobase\])
```
**パラメータ**
* `id` — geobase の Region ID。[UInt32](/ja/reference/data-types/int-uint)。
* `geobase` — 辞書キー。[複数のジオベース](#multiple-geobases)を参照してください。[String](/ja/reference/data-types/string)。省略可能です。
**戻り値**
* 指定したリージョンと、その親を階層に沿ってすべて含む Region ID の Array。[Array](/ja/reference/data-types/array)([UInt32](/ja/reference/data-types/int-uint))。
**例**
```sql title="Query" theme={null}
SELECT regionHierarchy(number::UInt32) AS arr, arrayMap(id -> regionToName(id, 'en'), arr) FROM numbers(5);
```
```text title="Response" theme={null}
┌─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'] │
└────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘
```
{/*AUTOGENERATED_START*/}