` 要素の内容を返します。
属性の値をパースできない場合、または値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1)
```
```response title=Response theme={null}
┌─dictGetDateT⋯_value', 1)─┐
│ 2024-01-15 10:30:00 │
└──────────────────────────┘
```
## dictGetDateTimeOrDefault
導入バージョン: v1.1.0
Dictionary の設定にかかわらず、Dictionary の属性値を `DateTime` データ型に変換します。キーが見つからない場合は、指定したデフォルト値を返します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キーの値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` キーを持つ行がない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、`default_value_expr` パラメータとして渡された値を返します。
属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);
-- for key which does not exist, returns the provided default value
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));
```
```response title=Response theme={null}
┌─dictGetDateT⋯_value', 1)─┐
│ 2024-01-15 10:30:00 │
└──────────────────────────┘
┌─dictGetDateT⋯0:00:00'))──┐
│ 1970-01-01 00:00:00 │
└──────────────────────────┘
```
## dictGetDescendants
導入バージョン: v21.4.0
[`dictGetChildren`](#dictGetChildren) 関数を `level` 回再帰的に適用した場合と同様に、すべての子孫ノードを返します。
この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetDescendants(dict_name, key, level)
```
**引数**
* `dict_name` — Dictionary 名。[`String`](/docs/ja/reference/data-types/string)
* `key` — 確認するキー。[`const String`](/docs/ja/reference/data-types/string)
* `level` — 確認するキーの階層レベル。`level = 0` の場合は、末端まですべての子孫を返します。[`UInt8`](/docs/ja/reference/data-types/int-uint)
**戻り値**
キーの子孫を返します。[`Array(UInt64)`](/docs/ja/reference/data-types/array)
**例**
**Dictionary の第1レベルの子を取得する**
```sql title=Query theme={null}
CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
-- ├── 2 (Level 2 - Node 2)
-- │ ├── 4 (Level 3 - Node 4)
-- │ └── 5 (Level 3 - Node 5)
-- └── 3 (Level 2 - Node 3)
-- └── 6 (Level 3 - Node 6)
SELECT dictGetDescendants('hierarchical_dictionary', 0, 2)
```
```response title=Response theme={null}
┌─dictGetDesce⋯ary', 0, 2)─┐
│ [3,2] │
└──────────────────────────┘
```
## dictGetFloat32
導入バージョン: v1.1.0
Dictionary の属性値を、Dictionary の設定にかかわらず `Float32` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetFloat32(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値を返す式 (辞書の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値をパースできない場合、または値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1)
```
```response title=Response theme={null}
┌─dictGetFloat⋯_value', 1)─┐
│ -123.123 │
└──────────────────────────┘
```
## dictGetFloat32OrDefault
導入バージョン: v1.1.0
Dictionary の設定にかかわらず、Dictionary の属性値を `Float32` 型に変換します。秘密鍵が見つからない場合は、指定したデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。Dictionary キー型の値、またはタプル値を返す式 (Dictionary の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — Dictionary に `id_expr` キーを持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する Dictionary 属性の値を返します。
該当しない場合は、`default_value_expr` パラメータとして渡された値を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 123.45);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);
-- for key which does not exist, returns the provided default value (-1.0)
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);
```
```response title=Response theme={null}
┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│ 123.45 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.)─┐
│ -1 │
└──────────────────────────────────────────────────────────────────────┘
```
## dictGetFloat64
導入バージョン: v1.1.0
Dictionary の属性値を、Dictionary の設定に関係なく `Float64` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetFloat64(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値を返す式 (辞書設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書の属性値を返します。
該当しない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1)
```
```response title=Response theme={null}
┌─dictGetFloat⋯_value', 1)─┐
│ -123.123 │
└──────────────────────────┘
```
## dictGetFloat64OrDefault
導入バージョン: v1.1.0
辞書の設定にかかわらず、辞書属性の値を `Float64` データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返す可能性があります。
**構文**
```sql theme={null}
dictGetFloat64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書名。 [`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。 [`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値を返す式 (辞書の設定に依存) 。 [`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` キーを持つ行が存在しない場合に返される値。 [`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
対応する値がない場合は、`default_value_expr` パラメータとして渡された値を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 987654.123456);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);
-- for key which does not exist, returns the provided default value (nan)
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);
```
```response title=Response theme={null}
┌─dictGetFloat⋯_value', 1)─┐
│ 987654.123456 │
└──────────────────────────┘
┌─dictGetFloat⋯, 999, nan)─┐
│ nan │
└──────────────────────────┘
```
## dictGetHierarchy
導入バージョン: v1.1.0
[階層型Dictionary](/docs/ja/reference/statements/create/dictionary/layouts/hierarchical#hierarchical-dictionaries) 内で、キーのすべての親を含む配列を作成します。
この関数は非決定論的です。同じ引数でも、異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetHierarchy(dict_name, key)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `key` — キー値。[`const String`](/docs/ja/reference/data-types/string)
**戻り値**
キーに対応する親を返します。[`Array(UInt64)`](/docs/ja/reference/data-types/array)
**例**
**キーの階層を取得**
```sql title=Query theme={null}
CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetHierarchy('hierarchical_dictionary', 5)
```
```response title=Response theme={null}
┌─dictGetHiera⋯ionary', 5)─┐
│ [5,2,1] │
└──────────────────────────┘
```
## dictGetIPv4
導入バージョン: v1.1.0
Dictionary の設定に関係なく、Dictionary 属性の値を `IPv4` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetIPv4(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書の名前。 [`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。 [`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。 [`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書設定でその属性に対して指定された `` 要素の内容を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合、例外を送出します。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1)
```
```response title=Response theme={null}
┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1 │
└─────────────────────────────────────┘
```
## dictGetIPv4OrDefault
導入バージョン: v23.1.0
Dictionary の設定にかかわらず、Dictionary の属性値を `IPv4` データ型に変換します。秘密鍵が見つからない場合は、指定したデフォルト値を返します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — Dictionary名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — 秘密鍵値。Dictionary 秘密鍵型の値、またはタプル値を返す式 (Dictionary の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — Dictionary に `id_expr` 秘密鍵を持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応するDictionary属性の値を返します。
対応する値がない場合は、`default_value_expr` パラメータとして渡された値を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);
-- for key which does not exist, returns the provided default value
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));
```
```response title=Response theme={null}
┌─dictGetIPv4('all_types_dict', 'IPv4_value', 1)─┐
│ 192.168.0.1 │
└────────────────────────────────────────────────┘
┌─dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'))─┐
│ 0.0.0.0 │
└──────────────────────────────────────────────────────────────────────────────┘
```
## dictGetIPv6
導入バージョン: v23.1.0
Dictionary の設定にかかわらず、辞書属性の値を `IPv6` データ型に変換します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetIPv6(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書の名前。 [`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。 [`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キーの値。辞書キー型の値またはタプル値を返す式 (辞書の設定に依存) 。 [`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書の設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1)
```
```response title=Response theme={null}
┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334 │
└─────────────────────────────────────┘
```
## dictGetIPv6OrDefault
導入バージョン: v23.1.0
Dictionary 設定にかかわらず、Dictionary 属性の値を `IPv6` データ型に変換します。秘密鍵が見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — Dictionary名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — 秘密鍵値。Dictionary 秘密鍵型の値、またはタプル値 (Dictionary 設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — Dictionary に `id_expr` 秘密鍵を持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応するDictionary属性の値を返します。
該当する値がない場合は、`default_value_expr` パラメータとして渡された値を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);
-- for key which does not exist, returns the provided default value
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);
```
```response title=Response theme={null}
┌─dictGetIPv6('all_types_dict', 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334 │
└────────────────────────────────────────────────┘
┌─dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, CAST('::1', 'IPv6'))─┐
│ ::1 │
└────────────────────────────────────────────────────────────────────────────────┘
```
## dictGetInt16
導入バージョン: v1.1.0
Dictionary の属性値を、Dictionary の設定にかかわらず `Int16` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetInt16(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書の設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書の設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外を発生させます。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1)
```
```response title=Response theme={null}
┌─dictGetInt16⋯_value', 1)─┐
│ -5000 │
└──────────────────────────┘
```
## dictGetInt16OrDefault
導入バージョン: v1.1.0
Dictionary の属性値を、Dictionary の設定にかかわらず `Int16` データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対しても異なる結果を返す可能性があります。
**構文**
```sql theme={null}
dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値を返す式 (辞書の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` キーを持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する Dictionary 属性の値を返します。
対応する値がない場合は、`default_value_expr` パラメータとして渡された値を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);
-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);
```
```response title=Response theme={null}
┌─dictGetInt16⋯_value', 1)─┐
│ -5000 │
└──────────────────────────┘
┌─dictGetInt16⋯', 999, -1)─┐
│ -1 │
└──────────────────────────┘
```
## dictGetInt32
導入バージョン: v1.1.0
辞書設定に関係なく、辞書の属性値を `Int32` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetInt32(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、または Tuple 値を返す式 (辞書の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。対応する値がない場合は、辞書の設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値を解析できない場合、または値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1)
```
```response title=Response theme={null}
┌─dictGetInt32⋯_value', 1)─┐
│ -1000000 │
└──────────────────────────┘
```
## dictGetInt32OrDefault
導入バージョン: v1.1.0
Dictionary の設定にかかわらず、辞書属性の値を `Int32` データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値またはタプル値を返す式 (Dictionary の設定に依存します) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — Dictionary に `id_expr` キーを持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する Dictionary 属性の値を返します。
存在しない場合は、`default_value_expr` パラメータとして渡された値を返します。
属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);
-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);
```
```response title=Response theme={null}
┌─dictGetInt32⋯_value', 1)─┐
│ -1000000 │
└──────────────────────────┘
┌─dictGetInt32⋯', 999, -1)─┐
│ -1 │
└──────────────────────────┘
```
## dictGetInt64
導入バージョン: v1.1.0
Dictionary の設定に関係なく、辞書属性の値を `Int64` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetInt64(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値またはタプル値を返す式 (辞書設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1)
```
```response title=Response theme={null}
┌─dictGetInt64⋯_value', 1)───┐
│ -9223372036854775807 │
└────────────────────────────┘
```
## dictGetInt64OrDefault
導入バージョン: v1.1.0
Dictionary の設定にかかわらず、辞書属性の値を `Int64` データ型に変換します。キーが見つからない場合は、指定したデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値を返す式 (辞書の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` キーを持つ行が含まれていない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、`default_value_expr` パラメーターとして渡された値を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775808);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);
-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);
```
```response title=Response theme={null}
┌─dictGetInt64⋯_value', 1)─┐
│ -9223372036854775808 │
└──────────────────────────┘
┌─dictGetInt64⋯', 999, -1)─┐
│ -1 │
└──────────────────────────┘
```
## dictGetInt8
導入バージョン: v1.1.0
辞書の設定に関係なく、辞書属性の値を `Int8` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetInt8(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書の属性値を返します。
対応する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
属性の値をパースできない場合、または値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1)
```
```response title=Response theme={null}
┌─dictGetInt8(⋯_value', 1)─┐
│ -100 │
└──────────────────────────┘
```
## dictGetInt8OrDefault
導入バージョン: v1.1.0
ディクショナリの設定にかかわらず、ディクショナリ属性の値を `Int8` データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書名。 [`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。 [`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値を返す式 (辞書設定に依存) 。 [`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` キーを持つ行が存在しない場合に返される値。 [`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当しない場合は、`default_value_expr` パラメータとして渡された値を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);
-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);
```
```response title=Response theme={null}
┌─dictGetInt8(⋯_value', 1)─┐
│ -100 │
└──────────────────────────┘
┌─dictGetInt8O⋯', 999, -1)─┐
│ -1 │
└──────────────────────────┘
```
## dictGetKeys
導入バージョン: v25.12.0
属性が指定した値に等しい辞書キーを返します。これは、単一の属性に対する関数 `dictGet` の逆です。
`dictGetKeys` で使用されるクエリごとの逆ルックアップキャッシュのサイズを制限するには、設定 `max_reverse_dictionary_lookup_cache_size_bytes` を使用します。
このキャッシュは、同じクエリ内で辞書を再走査しないよう、各属性値に対応するシリアライズ済みのキーのタプルを格納します。
このキャッシュはクエリをまたいで保持されません。上限に達すると、エントリは LRU に従って追い出されます。
これは、大きな辞書で、入力のカーディナリティが低く、かつワーキングセットがキャッシュに収まる場合に最も効果的です。キャッシュを無効にするには `0` を設定します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetKeys('dict_name', 'attr_name', value_expr)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 照合する属性。[`String`](/docs/ja/reference/data-types/string)
* `value_expr` — 属性と照合する値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression)
**戻り値**
単一キーの Dictionary の場合、属性が `value_expr` と等しいキーの配列を返します。複合キーの Dictionary の場合、属性が `value_expr` と等しいキーのタプルの配列を返します。Dictionary 内に `value_expr` に対応する属性がない場合は、空の配列が返されます。ClickHouse は、属性の値を解析できない場合、またはその値を属性のデータ型に変換できない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE task_priority_source (task_id UInt64, priority_level String) ENGINE = Memory;
INSERT INTO task_priority_source VALUES (1, 'low'), (2, 'high'), (3, 'medium'), (4, 'high');
CREATE DICTIONARY task_id_to_priority_dictionary (task_id UInt64, priority_level String) PRIMARY KEY task_id SOURCE(CLICKHOUSE(TABLE 'task_priority_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 0 MAX 0);
SELECT arraySort(dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high')) AS ids;
```
```response title=Response theme={null}
┌─ids───┐
│ [2,4] │
└───────┘
```
## dictGetOrDefault
導入バージョン: v18.16.0
Dictionary から値を取得します。キーが見つからない場合は、デフォルト値を返します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetOrDefault('dict_name', attr_names, id_expr, default_value)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_names` — Dictionary のカラム名、またはカラム名のタプル。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。単純キーを持つ Dictionary の場合は、`UInt64` 値を返す式です。複合キーを持つ Dictionary の場合は、キー値のタプルを返す式です。複合キーが単一の属性で構成されている場合は、`tuple` でラップせずにその値を直接渡すこともできます。[`UInt64`](/docs/ja/reference/data-types/int-uint) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value` — キーが見つからない場合に返されるデフォルト値。型は属性のデータ型と一致している必要があります。
**戻り値**
キーが見つかった場合は、`id_expr` に対応する Dictionary の属性値を返します。
キーが見つからない場合は、指定した `default_value` を返します。
**例**
**デフォルト値付きで値を取得**
```sql title=Query theme={null}
CREATE TABLE dict_mult_source (id UInt32, c1 UInt32, c2 String) ENGINE = Memory;
INSERT INTO dict_mult_source VALUES (1, 1, '1'), (2, 2, '2'), (3, 3, '3');
CREATE DICTIONARY ext_dict_mult (id UInt32, c1 UInt32, c2 String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT dictGetOrDefault('ext_dict_mult', 'c1', toUInt64(999), 0) AS val
```
```response title=Response theme={null}
0
```
## dictGetOrNull
導入バージョン: v21.4.0
Dictionary から値を取得し、キーが見つからない場合は NULL を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetOrNull('dict_name', 'attr_name', id_expr)
```
**引数**
* `dict_name` — 辞書の名前。文字列リテラル。 - `attr_name` — 取得するカラム名。文字列リテラル。 - `id_expr` — キー値。辞書のキー型の値を返す式。
**戻り値**
キーが見つかった場合は、`id_expr` に対応する辞書属性の値を返します。
キーが見つからない場合は、`NULL` を返します。
**例**
**範囲キー辞書を使用する例**
```sql title=Query theme={null}
CREATE TABLE range_key_dictionary_source_table (key UInt64, start_date Date, end_date Date, value String, value_nullable Nullable(String)) ENGINE = TinyLog();
INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');
CREATE DICTIONARY range_key_dictionary (key UInt64, start_date Date, end_date Date, value String, value_nullable Nullable(String)) PRIMARY KEY key SOURCE(CLICKHOUSE(TABLE 'range_key_dictionary_source_table' DB currentDatabase())) LIFETIME(MIN 1 MAX 1000) LAYOUT(RANGE_HASHED()) RANGE(MIN start_date MAX end_date);
SELECT
(number, toDate('2019-05-20')),
dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
FROM system.numbers LIMIT 5 FORMAT TabSeparated;
```
```response title=Response theme={null}
(0,'2019-05-20') \N
(1,'2019-05-20') First
(2,'2019-05-20') Second
(3,'2019-05-20') Third
(4,'2019-05-20') \N
```
## dictGetRoot
導入バージョン: v26.7.0
[hierarchical dictionary](/docs/ja/reference/statements/create/dictionary/layouts/hierarchical#hierarchical-dictionaries) 内で、秘密鍵の最上位の祖先 (ルート) を返します。
これは、[dictGetHierarchy](#dictGetHierarchy) が返す配列の最後の要素を取得するのと等価な便利な関数です。つまり、`dictGetHierarchy(dict_name, key)[-1]` です。
秘密鍵自体が階層の最上位ノードである場合は、その秘密鍵が返されます。秘密鍵が Dictionary に存在しない場合は、`0` が返されます。
この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetRoot(dict_name, key)
```
**引数**
* `dict_name` — Dictionary名。[`String`](/docs/ja/reference/data-types/string)
* `key` — 秘密鍵値。[`UInt64`](/docs/ja/reference/data-types/int-uint)
**戻り値**
秘密鍵の最上位の祖先 (ルート) を返します。[`UInt64`](/docs/ja/reference/data-types/int-uint)
**例**
**秘密鍵のルートを取得する**
```sql title=Query theme={null}
CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetRoot('hierarchical_dictionary', 5)
```
```response title=Response theme={null}
┌─dictGetRoot(⋯ionary', 5)─┐
│ 1 │
└──────────────────────────┘
```
## dictGetString
導入バージョン: v1.1.0
辞書の設定に関係なく、辞書属性の値を `String` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetString(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetString('all_types_dict', 'String_value', 1)
```
```response title=Response theme={null}
┌─dictGetString(⋯_value', 1)─┐
│ test string │
└────────────────────────────┘
```
## dictGetStringOrDefault
導入バージョン: v1.1.0
Dictionary の設定にかかわらず、辞書 属性 の値を `String` データ型に変換するか、秘密鍵が見つからない場合は指定したデフォルト値を返します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — 秘密鍵として使用する値。辞書秘密鍵型の値またはタプル値を返す式 (辞書設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` 秘密鍵を持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
対応する値がない場合は、`default_value_expr` パラメータとして渡された値を返します。
属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetString('all_types_dict', 'String_value', 1);
-- for key which does not exist, returns the provided default value
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');
```
```response title=Response theme={null}
┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string │
└────────────────────────────────────────────────────┘
┌─dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default')─┐
│ default │
└──────────────────────────────────────────────────────────────────────────┘
```
## dictGetUInt16
導入バージョン: v1.1.0
Dictionary の属性値を、辞書設定に関係なく `UInt16` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUInt16(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1)
```
```response title=Response theme={null}
┌─dictGetUInt1⋯_value', 1)─┐
│ 5000 │
└──────────────────────────┘
```
## dictGetUInt16OrDefault
導入バージョン: v1.1.0
Dictionary の設定にかかわらず、Dictionary 属性の値を `UInt16` データ型に変換します。キーが見つからない場合は、指定したデフォルト値を返します。
この関数は非決定論的です。同じ引数であっても、異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値またはタプル値を返す式 (辞書の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` キーを持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
それ以外の場合は、`default_value_expr` パラメータとして渡された値を返します。
属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外を発生させます。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);
-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);
```
```response title=Response theme={null}
┌─dictGetUInt1⋯_value', 1)─┐
│ 5000 │
└──────────────────────────┘
┌─dictGetUInt1⋯e', 999, 0)─┐
│ 0 │
└──────────────────────────┘
```
## dictGetUInt32
導入バージョン: v1.1.0
辞書の設定にかかわらず、辞書の属性値を`UInt32`データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返す可能性があります。
**構文**
```sql theme={null}
dictGetUInt32(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書設定に応じる) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1)
```
```response title=Response theme={null}
┌─dictGetUInt3⋯_value', 1)─┐
│ 1000000 │
└──────────────────────────┘
```
## dictGetUInt32OrDefault
導入バージョン: v1.1.0
辞書設定にかかわらず、辞書属性の値を `UInt32` データ型に変換します。キーが見つからない場合は、指定したデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — 辞書に `id_expr` キーを持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
対応する値がない場合は、`default_value_expr` パラメータとして渡された値を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);
-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);
```
```response title=Response theme={null}
┌─dictGetUInt3⋯_value', 1)─┐
│ 1000000 │
└──────────────────────────┘
┌─dictGetUInt3⋯e', 999, 0)─┐
│ 0 │
└──────────────────────────┘
```
## dictGetUInt64
導入バージョン: v1.1.0
辞書の設定にかかわらず、辞書属性の値を `UInt64` データ型に変換します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUInt64(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — Dictionary の名前。 [`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。 [`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値を返す式 (辞書設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する Dictionary 属性の値を返します。
対応する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値を解析できない場合、または値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)
```
```response title=Response theme={null}
┌─dictGetUInt6⋯_value', 1)─┐
│ 9223372036854775807 │
└──────────────────────────┘
```
## dictGetUInt64OrDefault
導入バージョン: v1.1.0
Dictionary の属性値を、Dictionary の設定に関係なく `UInt64` データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — 辞書キーの値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — Dictionary に `id_expr` キーを持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する Dictionary 属性の値を返します。
存在しない場合は、`default_value_expr` パラメータとして渡された値を返します。
属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);
-- for key which does not exist, returns the provideddefault value (0)
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);
```
```response title=Response theme={null}
┌─dictGetUInt6⋯_value', 1)─┐
│ 9223372036854775807 │
└──────────────────────────┘
┌─dictGetUInt6⋯e', 999, 0)─┐
│ 0 │
└──────────────────────────┘
```
## dictGetUInt8
導入バージョン: v1.1.0
Dictionary の設定に関係なく、Dictionary 属性の値を `UInt8` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUInt8(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
該当する値がない場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
属性の値をパースできない場合、または値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1)
```
```response title=Response theme={null}
┌─dictGetUInt8⋯_value', 1)─┐
│ 100 │
└──────────────────────────┘
```
## dictGetUInt8OrDefault
導入バージョン: v1.1.0
辞書設定に関係なく、辞書属性の値を`UInt8`データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。Dictionary のキー型の値、またはタプル値を返す式 (dictionary configuration に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — Dictionary に `id_expr` キーを持つ行が存在しない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する Dictionary の属性値を返します。
該当しない場合は、`default_value_expr` パラメーターとして渡された値を返します。
ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);
-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);
```
```response title=Response theme={null}
┌─dictGetUInt8⋯_value', 1)─┐
│ 100 │
└──────────────────────────┘
┌─dictGetUInt8⋯e', 999, 0)─┐
│ 0 │
└──────────────────────────┘
```
## dictGetUUID
導入バージョン: v1.1.0
辞書の設定にかかわらず、辞書属性の値を `UUID` データ型に変換します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUUID(dict_name, attr_name, id_expr)
```
**引数**
* `dict_name` — 辞書の名前。 [`String`](/docs/ja/reference/data-types/string)
* `attr_name` — 辞書のカラム名。 [`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キーの値。辞書キー型の値またはタプル値を返す式 (辞書設定に依存) 。 [`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する辞書属性の値を返します。
それ以外の場合は、辞書設定でその属性に指定された `` 要素の内容を返します。
ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '123e4567-e89b-12d3-a456-426614174000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1)
```
```response title=Response theme={null}
┌─dictGetUUID(⋯_value', 1)─────────────┐
│ 123e4567-e89b-12d3-a456-426614174000 │
└──────────────────────────────────────┘
```
## dictGetUUIDOrDefault
導入バージョン: v1.1.0
Dictionary の設定に関係なく、Dictionary 属性の値を `UUID` データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。
この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `attr_name` — Dictionary のカラム名。[`String`](/docs/ja/reference/data-types/string) または [`Tuple(String)`](/docs/ja/reference/data-types/tuple)
* `id_expr` — キー値。Dictionary キー型の値またはタプル値を返す式 (辞書の設定に依存) 。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
* `default_value_expr` — Dictionary に `id_expr` キーを持つ行が含まれていない場合に返される値。[`Expression`](/docs/ja/reference/data-types/special-data-types/expression) または [`Tuple(T)`](/docs/ja/reference/data-types/tuple)
**戻り値**
`id_expr` に対応する Dictionary 属性の値を返します。
存在しない場合は、`default_value_expr` パラメータとして渡された値を返します。
属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。
**例**
**使用例**
```sql title=Query theme={null}
CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '550e8400-e29b-41d4-a716-446655440000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);
-- for key which does not exist, returns the provided default value
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);
```
```response title=Response theme={null}
┌─dictGetUUID('all_types_dict', 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000 │
└────────────────────────────────────────────────┘
┌─dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, CAST('00000000-0000-0000-0000-000000000000', 'UUID'))─┐
│ 00000000-0000-0000-0000-000000000000 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## dictHas
導入バージョン: v1.1.0
キーがDictionaryに存在するかどうかを判定します。
この関数は非決定論的です。同じ引数に対して異なる結果を返す場合があります。
**構文**
```sql theme={null}
dictHas('dict_name', id_expr)
```
**引数**
* `dict_name` — Dictionary の名前。[`String`](/docs/ja/reference/data-types/string)
* `id_expr` — キー値 [`const String`](/docs/ja/reference/data-types/string)
**戻り値**
キーが存在する場合は `1`、存在しない場合は `0` を返します。[`UInt8`](/docs/ja/reference/data-types/int-uint)
**例**
**Dictionary にキーが存在するか確認する**
```sql title=Query theme={null}
CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
-- ├── 2 (Level 2 - Node 2)
-- │ ├── 4 (Level 3 - Node 4)
-- │ └── 5 (Level 3 - Node 5)
-- └── 3 (Level 2 - Node 3)
-- └── 6 (Level 3 - Node 6)
SELECT dictHas('hierarchical_dictionary', 2);
SELECT dictHas('hierarchical_dictionary', 7);
```
```response title=Response theme={null}
┌─dictHas('hie⋯ionary', 2)─┐
│ 1 │
└──────────────────────────┘
┌─dictHas('hie⋯ionary', 7)─┐
│ 0 │
└──────────────────────────┘
```
## dictIsIn
導入バージョン: v1.1.0
Dictionary 内の階層チェーン全体をたどって、キーの祖先かどうかを確認します。
この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。
**構文**
```sql theme={null}
dictIsIn(dict_name, child_id_expr, ancestor_id_expr)
```
**引数**
* `dict_name` — 辞書名。[`String`](/docs/ja/reference/data-types/string)
* `child_id_expr` — 確認するキー。[`String`](/docs/ja/reference/data-types/string)
* `ancestor_id_expr` — `child_id_expr` キーの祖先と見なされるキー。[`const String`](/docs/ja/reference/data-types/string)
**戻り値**
`child_id_expr` が `ancestor_id_expr` の子でない場合は `0`、`child_id_expr` が `ancestor_id_expr` の子である場合、または `child_id_expr` が `ancestor_id_expr` 自身である場合は `1` を返します。[`UInt8`](/docs/ja/reference/data-types/int-uint)
**例**
**階層関係を確認する**
```sql title=Query theme={null}
CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- valid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 6, 3);
-- invalid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 3, 5);
```
```response title=Response theme={null}
┌─dictIsIn('hi⋯ary', 6, 3)─┐
│ 1 │
└──────────────────────────┘
┌─dictIsIn('hi⋯ary', 3, 5)─┐
│ 0 │
└──────────────────────────┘
```