` 요소의 내용을 반환합니다.
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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `DateTime` 데이터 타입으로 변환하거나, 키를 찾지 못한 경우 지정된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `key` — 확인할 키입니다. [`const String`](/docs/ko/reference/data-types/string)
* `level` — 계층 수준입니다. `level = 0`이면 최하위까지 모든 하위 항목을 반환합니다. [`UInt8`](/docs/ko/reference/data-types/int-uint)
**반환 값**
해당 키의 하위 항목을 반환합니다. [`Array(UInt64)`](/docs/ko/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);
-- 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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Float32` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetFloat32(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며(딕셔너리 구성에 따라 다름), [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Float32` 데이터 타입으로 변환하며, 키를 찾지 못한 경우에는 지정된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 때 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Float64` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetFloat64(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
[계층형 딕셔너리(hierarchical dictionary)](/docs/ko/reference/statements/create/dictionary/layouts/hierarchical#hierarchical-dictionaries)에서 지정한 키의 모든 부모를 포함하는 배열을 생성합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetHierarchy(dict_name, key)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `key` — 키 값입니다. [`const String`](/docs/ko/reference/data-types/string)
**반환 값**
해당 키의 상위 항목을 반환합니다. [`Array(UInt64)`](/docs/ko/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
딕셔너리 구성과 무관하게 딕셔너리 속성 값을 `IPv4` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetIPv4(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `IPv4` 데이터 타입으로 변환하며, 키를 찾을 수 없으면 지정된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `IPv6` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetIPv6(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `IPv6` 데이터 타입으로 변환하며, 키를 찾지 못하면 제공된 기본값을 반환합니다.
이 함수는 비결정적입니다. 같은 인수에 대해서도 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
해당 값이 없으면 `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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Int16` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetInt16(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Int16` 데이터 타입으로 변환하며, 키를 찾지 못한 경우에는 지정된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
그렇지 않으면 `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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Int32` 데이터 타입으로 변환하며, 키를 찾지 못하면 지정된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 때 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Int64` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetInt64(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Int64` 데이터 타입으로 변환하며, 키를 찾지 못하면 제공된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리의 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 때 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 일치 여부를 확인할 속성입니다. [`String`](/docs/ko/reference/data-types/string)
* `value_expr` — 속성과 비교할 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression)
**반환 값**
단일 키 딕셔너리의 경우 속성이 `value_expr`와 같은 키의 배열입니다. 다중 키 딕셔너리의 경우 속성이 `value_expr`와 같은 키 튜플의 배열입니다. 딕셔너리에 `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
딕셔너리에서 값을 조회하며, 키를 찾지 못하면 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetOrDefault('dict_name', attr_names, id_expr, default_value)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_names` — 딕셔너리의 컬럼 이름 또는 컬럼 이름의 튜플입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 단순 키를 사용하는 딕셔너리에서는 `UInt64` 값을 반환하는 표현식입니다. 복합 키를 사용하는 딕셔너리에서는 키 값의 튜플을 반환하는 표현식입니다. 복합 키가 단일 속성으로만 구성된 경우 `tuple`로 감싸지 않고 해당 값을 직접 전달할 수 있습니다. [`UInt64`](/docs/ko/reference/data-types/int-uint) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value` — 키를 찾지 못했을 때 반환할 기본값입니다. 타입은 속성의 데이터 타입과 일치해야 합니다.
**반환 값**
키를 찾으면 `id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
키를 찾지 못하면 제공된 `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
딕셔너리에서 값을 조회하며, 키를 찾지 못하면 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
[계층형 딕셔너리](/docs/ko/reference/statements/create/dictionary/layouts/hierarchical#hierarchical-dictionaries)에서 키의 최상위 조상(루트)을 반환합니다.
이는 [dictGetHierarchy](#dictGetHierarchy)가 반환하는 배열의 마지막 요소를 가져오는 간편한 표현입니다. 즉, `dictGetHierarchy(dict_name, key)[-1]`입니다.
키 자체가 계층 구조의 최상위 노드이면 해당 키를 반환합니다. 키가 딕셔너리에 없으면 `0`을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetRoot(dict_name, key)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `key` — 키 값입니다. [`UInt64`](/docs/ko/reference/data-types/int-uint)
**반환 값**
키의 최상위 조상(루트)을 반환합니다. [`UInt64`](/docs/ko/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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `String` 데이터 타입으로 변환합니다. 키를 찾을 수 없으면 지정된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 때 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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에 도입됨
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `UInt16` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetUInt16(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `UInt16` 데이터 타입으로 변환하며, 키를 찾을 수 없으면 지정한 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_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);
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)
```
```response title=Response theme={null}
┌─dictGetUInt6⋯_value', 1)─┐
│ 9223372036854775807 │
└──────────────────────────┘
```
## dictGetUInt64OrDefault
도입 버전: v1.1.0
딕셔너리 구성에 관계없이 딕셔너리 속성 값을 `UInt64` 데이터 타입으로 변환하며, 키를 찾지 못한 경우 제공된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `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
딕셔너리 구성과 상관없이 딕셔너리 속성 값을 `UInt8` 데이터 타입으로 변환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetUInt8(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `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/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/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
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `UUID` 데이터 타입으로 변환하며, 키를 찾을 수 없으면 지정된 기본값을 반환합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/docs/ko/reference/data-types/string) 또는 [`Tuple(String)`](/docs/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/docs/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/docs/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `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
딕셔너리에 키가 있는지 확인합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictHas('dict_name', id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `id_expr` — 키 값 [`const String`](/docs/ko/reference/data-types/string)
**반환 값**
키가 존재하면 `1`을 반환하고, 그렇지 않으면 `0`을 반환합니다. [`UInt8`](/docs/ko/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);
-- 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
딕셔너리에서 계층 체인 전체를 따라 키의 상위 항목을 확인합니다.
이 함수는 비결정적입니다. 동일한 인수에 대해서도 서로 다른 결과를 반환할 수 있습니다.
**구문**
```sql theme={null}
dictIsIn(dict_name, child_id_expr, ancestor_id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/docs/ko/reference/data-types/string)
* `child_id_expr` — 확인할 키입니다. [`String`](/docs/ko/reference/data-types/string)
* `ancestor_id_expr` — `child_id_expr` 키의 상위 조상으로 간주되는 키입니다. [`const String`](/docs/ko/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/ko/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 │
└──────────────────────────┘
```