` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
해당 값이 없으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 해당 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값을 반환
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`](/ko/reference/data-types/string)
* `key` — 확인할 키입니다. [`const String`](/ko/reference/data-types/string)
* `level` — 계층 수준입니다. `level = 0`이면 최하위까지 모든 하위 항목을 반환합니다. [`UInt8`](/ko/reference/data-types/int-uint)
**반환 값**
해당 키의 하위 항목을 반환합니다. [`Array(UInt64)`](/ko/reference/data-types/array)
**예시**
**딕셔너리의 직계 하위 항목 가져오기**
```sql title=Query theme={null}
-- 다음 계층형 딕셔너리를 고려하십시오:
-- 0 (루트)
-- └── 1 (수준 1 - 노드 1)
-- ├── 2 (수준 2 - 노드 2)
-- │ ├── 4 (수준 3 - 노드 4)
-- │ └── 5 (수준 3 - 노드 5)
-- └── 3 (수준 2 - 노드 3)
-- └── 6 (수준 3 - 노드 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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며(딕셔너리 구성에 따라 다름), [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)입니다.
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당하는 값이 없으면 딕셔너리 구성에서 해당 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 때 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(-1.0)을 반환
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);
```
```response title=Response theme={null}
┌─dictGetFloat⋯_value', 1)─┐
│ 123.45 │
└──────────────────────────┘
┌─dictGetFloat⋯e', 999, -1)─┐
│ -1 │
└───────────────────────────┘
```
## dictGetFloat64
도입 버전: v1.1.0
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Float64` 데이터 타입으로 변환합니다.
**구문**
```sql theme={null}
dictGetFloat64(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
그렇지 않으면 딕셔너리 구성에서 해당 속성에 대해 지정된 `` 요소의 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(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)](/ko/reference/statements/create/dictionary/layouts/hierarchical#hierarchical-dictionaries)에서 지정한 키의 모든 부모를 포함하는 배열을 생성합니다.
**구문**
```sql theme={null}
dictGetHierarchy(dict_name, key)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/ko/reference/data-types/string)
* `key` — 키 값입니다. [`const String`](/ko/reference/data-types/string)
**반환 값**
해당 키의 상위 항목을 반환합니다. [`Array(UInt64)`](/ko/reference/data-types/array)
**예시**
**키의 계층 구조 가져오기**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
그렇지 않으면 딕셔너리 구성에서 해당 속성에 대해 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);
-- 존재하지 않는 키의 경우, 제공된 기본값을 반환
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));
```
```response title=Response theme={null}
┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1 │
└─────────────────────────────────────┘
┌─dictGetIPv4OrDefa⋯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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당 값이 없으면 딕셔너리 구성에서 그 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
해당 값이 없으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);
-- 존재하지 않는 키의 경우, 제공된 기본값을 반환
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);
```
```response title=Response theme={null}
┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334 │
└─────────────────────────────────────┘
┌─dictGetIPv6OrDefa⋯:1'::IPv6)─┐
│ ::1 │
└──────────────────────────────┘
```
## dictGetInt16
도입 버전: v1.1.0
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `Int16` 데이터 타입으로 변환합니다.
**구문**
```sql theme={null}
dictGetInt16(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
그렇지 않으면 딕셔너리 구성에서 해당 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(-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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당 값이 없으면 딕셔너리 구성에서 그 속성에 대해 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 때 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(-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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당 값이 없으면 딕셔너리 구성에서 해당 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(-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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
그렇지 않으면 딕셔너리 구성에서 해당 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 때 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(-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`](/ko/reference/data-types/string)
* `attr_name` — 일치 여부를 확인할 속성입니다. [`String`](/ko/reference/data-types/string)
* `value_expr` — 속성과 비교할 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression)
**반환 값**
단일 키 딕셔너리의 경우 속성이 `value_expr`와 같은 키의 배열입니다. 다중 키 딕셔너리의 경우 속성이 `value_expr`와 같은 키 튜플의 배열입니다. 딕셔너리에 `value_expr`에 해당하는 속성이 없으면 빈 배열이 반환됩니다. ClickHouse는 속성 값을 파싱할 수 없거나 해당 값을 속성 데이터 타입으로 변환할 수 없으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
SELECT dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high') AS ids;
```
```response title=Response theme={null}
┌─ids───┐
│ [4,2] │
└───────┘
```
## dictGetOrDefault
도입 버전: v18.16.0
딕셔너리에서 값을 조회하며, 키를 찾지 못하면 기본값을 반환합니다.
**구문**
```sql theme={null}
dictGetOrDefault('dict_name', attr_names, id_expr, default_value)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/ko/reference/data-types/string)
* `attr_names` — 딕셔너리의 컬럼 이름 또는 컬럼 이름의 튜플입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. UInt64/Tuple(T)를 반환하는 표현식입니다. [`UInt64`](/ko/reference/data-types/int-uint) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value` — 키를 찾지 못했을 때 반환할 기본값입니다. 타입은 속성의 데이터 타입과 일치해야 합니다.
**반환 값**
키를 찾으면 `id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
키를 찾지 못하면 제공된 `default_value`를 반환합니다.
**예시**
**기본값을 사용해 값 가져오기**
```sql title=Query theme={null}
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}
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
```
## dictGetString
도입 버전: v1.1.0
딕셔너리의 구성과 관계없이 딕셔너리 속성 값을 `String` 데이터 타입으로 변환합니다.
**구문**
```sql theme={null}
dictGetString(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 Tuple 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당 값이 없으면 딕셔너리 구성에서 그 속성에 대해 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetString('all_types_dict', 'String_value', 1);
-- 존재하지 않는 키의 경우, 제공된 기본값을 반환
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');
```
```response title=Response theme={null}
┌─dictGetString(⋯_value', 1)─┐
│ test string │
└────────────────────────────┘
┌─dictGetStringO⋯ 999, 'default')─┐
│ default │
└─────────────────────────────────┘
```
## dictGetUInt16
v1.1.0에 도입됨
딕셔너리 구성과 관계없이 딕셔너리 속성 값을 `UInt16` 데이터 타입으로 변환합니다.
**구문**
```sql theme={null}
dictGetUInt16(dict_name, attr_name, id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당하는 값이 없으면 딕셔너리 구성에서 해당 속성에 대해 지정한 `` 요소의 내용을 반환합니다.
속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 ClickHouse는 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당 값이 없으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 키가 존재하는 경우
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);
-- 키가 존재하지 않는 경우, 지정된 기본값(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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당하는 값이 없으면 딕셔너리 구성에서 해당 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하며,
해당 값이 없으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 키가 존재하는 경우
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);
-- 키가 존재하지 않는 경우, 지정된 기본값(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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라집니다). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성의 값을 반환합니다.
그렇지 않으면 딕셔너리 구성에서 해당 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리의 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식이며, 딕셔너리 구성에 따라 달라집니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당하는 값이 없으면 딕셔너리 구성에서 해당 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 다름). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
속성 값을 파싱할 수 없거나 값이 속성 데이터 타입과 일치하지 않으면 ClickHouse는 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);
-- 존재하지 않는 키의 경우, 지정된 기본값(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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼의 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입의 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환합니다.
해당하는 값이 없으면 딕셔너리 구성에서 그 속성에 지정된 `` 요소의 내용을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 값이 속성의 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
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`](/ko/reference/data-types/string)
* `attr_name` — 딕셔너리 컬럼 이름입니다. [`String`](/ko/reference/data-types/string) 또는 [`Tuple(String)`](/ko/reference/data-types/tuple)
* `id_expr` — 키 값입니다. 딕셔너리 키 타입 값 또는 튜플 값을 반환하는 표현식입니다(딕셔너리 구성에 따라 달라짐). [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
* `default_value_expr` — 딕셔너리에 `id_expr` 키를 가진 행이 없을 경우 반환되는 값입니다. [`Expression`](/ko/reference/data-types/special-data-types/expression) 또는 [`Tuple(T)`](/ko/reference/data-types/tuple)
**반환 값**
`id_expr`에 해당하는 딕셔너리 속성 값을 반환하고,
그렇지 않으면 `default_value_expr` 매개변수로 전달된 값을 반환합니다.
ClickHouse는 속성 값을 파싱할 수 없거나 해당 값이 속성 데이터 타입과 일치하지 않으면 예외를 발생시킵니다.
**예시**
**사용 예시**
```sql title=Query theme={null}
-- 존재하는 키의 경우
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);
-- 존재하지 않는 키의 경우, 제공된 기본값을 반환
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);
```
```response title=Response theme={null}
┌─dictGetUUID('all_t⋯ 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000 │
└──────────────────────────────────────┘
┌─dictGetUUIDOrDefa⋯000000000000'::UUID)─┐
│ 00000000-0000-0000-0000-000000000000 │
└────────────────────────────────────────┘
```
## dictHas
도입 버전: v1.1.0
딕셔너리에 키가 있는지 확인합니다.
**구문**
```sql theme={null}
dictHas('dict_name', id_expr)
```
**인수**
* `dict_name` — 딕셔너리 이름입니다. [`String`](/ko/reference/data-types/string)
* `id_expr` — 키 값 [`const String`](/ko/reference/data-types/string)
**반환 값**
키가 존재하면 `1`을 반환하고, 그렇지 않으면 `0`을 반환합니다. [`UInt8`](/ko/reference/data-types/int-uint)
**예시**
**딕셔너리에 키가 존재하는지 확인**
```sql title=Query theme={null}
-- 다음 계층적 딕셔너리를 고려하십시오:
-- 0 (루트)
-- └── 1 (수준 1 - 노드 1)
-- ├── 2 (수준 2 - 노드 2)
-- │ ├── 4 (수준 3 - 노드 4)
-- │ └── 5 (수준 3 - 노드 5)
-- └── 3 (수준 2 - 노드 3)
-- └── 6 (수준 3 - 노드 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`](/ko/reference/data-types/string)
* `child_id_expr` — 확인할 키입니다. [`String`](/ko/reference/data-types/string)
* `ancestor_id_expr` — `child_id_expr` 키의 상위 조상으로 간주되는 키입니다. [`const String`](/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`](/ko/reference/data-types/int-uint)
**예시**
**계층 관계 확인**
```sql title=Query theme={null}
-- 유효한 계층 구조
SELECT dictIsIn('hierarchical_dictionary', 6, 3)
-- 유효하지 않은 계층 구조
SELECT dictIsIn('hierarchical_dictionary', 3, 5)
```
```response title=Response theme={null}
┌─dictIsIn('hi⋯ary', 6, 3)─┐
│ 1 │
└──────────────────────────┘
┌─dictIsIn('hi⋯ary', 3, 5)─┐
│ 0 │
└──────────────────────────┘
```