사전 함수

사전 함수 (Functions for Working with Dictionaries)

외부 사전(dictionary)에서 키로 값을 조회하고, 계층 관계를 다루는 함수 모음이에요. dictGet 계열 함수로 키에 해당하는 속성 값을 가져올 수 있어요.

출처: 문서

본문

DDL 쿼리로 만든 사전의 경우 dict_name 매개변수를 <database>.<dict_name>처럼 완전히 지정해야 해요. 그 외에는 현재 데이터베이스가 사용돼요.

사전 연결 및 구성에 대한 정보는 Dictionaries를 참고하세요.

사전 함수에 키 전달하기 (Passing keys to dictionary functions)

dictGet, dictGetOrDefault, dictGetOrNull, dictHas 같은 함수의 키 인자(id_expr)는 사전의 키에 따라 달라져요:

  • 단순 키(UInt64) 사전의 경우 키 값을 직접 전달해요:
SELECT dictGet('simple_key_dictionary', 'attr_name', toUInt64(1));
  • 복합(복잡) 키로 두 개 이상 속성을 가진 사전의 경우 키 값을 튜플로 전달해요:
SELECT dictGet('complex_key_dictionary', 'attr_name', ('value_for_field1', 42));
  • 복합 키가 단일 속성으로 구성되면 키 값을 tuple로 감싸지 않고 직접 전달할 수 있어요. 다음 두 가지 모두 유효하고 동등해요:
SELECT dictGet('complex_key_dictionary', 'attr_name', 'key');
SELECT dictGet('complex_key_dictionary', 'attr_name', tuple('key'));

이것은 키가 단일 속성인 ip_trie 사전에도 적용돼요. 조회할 IP 주소를 직접 전달할 수 있어요:

SELECT dictGet('ip_trie_dictionary', 'attr_name', toIPv4('202.79.32.10'));

dictGet

사전에서 값을 가져와요. 이 함수는 비결정적이에요: 같은 인자에 대해 다른 결과를 반환할 수 있어요.

구문 (Syntax)

dictGet('dict_name', attr_names, id_expr)

인자 (Arguments)

  • dict_name — 사전 이름. String
  • attr_names — 사전의 컬럼 이름, 또는 컬럼 이름의 튜플. String 또는 Tuple(String)
  • id_expr — 키 값. 단순 키 사전은 UInt64 값을 반환하는 표현식. 복합 키 사전은 키 값의 튜플을 반환하는 표현식. 복합 키가 단일 속성이면 그 값을 tuple로 감싸지 않고 직접 전달할 수 있어요. UInt64 또는 Tuple(T)

반환 값 (Returned value)

키가 발견되면 id_expr에 해당하는 사전 속성 값. 키가 없으면 사전 구성에서 해당 속성에 지정된 <null_value> 요소의 내용을 반환해요.

dictGetAll

정규 표현식 트리 사전에서 각 키와 일치한 모든 노드의 속성 값을 가져와요. T 대신 Array(T) 타입의 값을 반환한다는 점 외에는 dictGet과 유사하게 동작해요.

이 함수는 비결정적이에요.

구문 (Syntax)

dictGetAll(dict_name, attr_names, id_expr[, limit])

반환 값 (Returned value)

attr_names가 지정한 각 속성에 대해 id_expr에 해당하는 사전 속성 값의 배열. 사전에 id_expr에 해당하는 키가 없으면 빈 배열을 반환해요. Array(T)

dictGetChildren

키의 첫 번째 수준 자식(first-level children)을 인덱스 배열로 반환해요. dictGetHierarchy의 역변환이에요.

구문 (Syntax)

dictGetChildren(dict_name, key)

반환 값 (Returned value)

키의 첫 번째 수준 자손. Array(UInt64)

dictGetDate

사전 구성과 관계없이 사전 속성 값을 Date 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetDate(dict_name, attr_name, id_expr)

dictGetDateOrDefault

사전 구성과 관계없이 사전 속성 값을 Date 데이터 타입으로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetDateOrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetDateTime

사전 구성과 관계없이 사전 속성 값을 DateTime 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetDateTime(dict_name, attr_name, id_expr)

dictGetDateTimeOrDefault

사전 구성과 관계없이 사전 속성 값을 DateTime 데이터 타입으로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetDescendants

키의 자손(descendants)을 반환해요. level = 0이면 끝까지 모든 자손을 반환해요.

구문 (Syntax)

dictGetDescendants(dict_name, key, level)

반환 값 (Returned value)

키의 자손. Array(UInt64)

dictGetFloat32

사전 구성과 관계없이 사전 속성 값을 Float32 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetFloat32(dict_name, attr_name, id_expr)

dictGetFloat32OrDefault

사전 구성과 관계없이 Float32로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetFloat64

사전 구성과 관계없이 사전 속성 값을 Float64 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetFloat64(dict_name, attr_name, id_expr)

dictGetFloat64OrDefault

사전 구성과 관계없이 Float64로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetFloat64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetHierarchy

계층 사전에서 키의 모든 부모를 담은 배열을 만들어요.

구문 (Syntax)

dictGetHierarchy(dict_name, key)

반환 값 (Returned value)

키의 부모들. Array(UInt64)

dictGetIPv4

사전 구성과 관계없이 사전 속성 값을 IPv4 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetIPv4(dict_name, attr_name, id_expr)

dictGetIPv4OrDefault

사전 구성과 관계없이 IPv4로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetIPv6

사전 구성과 관계없이 사전 속성 값을 IPv6 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetIPv6(dict_name, attr_name, id_expr)

dictGetIPv6OrDefault

사전 구성과 관계없이 IPv6로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetInt8 / dictGetInt16 / dictGetInt32 / dictGetInt64

사전 구성과 관계없이 사전 속성 값을 각각 Int8 / Int16 / Int32 / Int64 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetInt8(dict_name, attr_name, id_expr)
dictGetInt16(dict_name, attr_name, id_expr)
dictGetInt32(dict_name, attr_name, id_expr)
dictGetInt64(dict_name, attr_name, id_expr)

dictGetInt8OrDefault / dictGetInt16OrDefault / dictGetInt32OrDefault / dictGetInt64OrDefault

사전 구성과 관계없이 정수 타입으로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)
dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetKeys

속성이 value_expr과 같은 키 배열을 반환해요. 단일 키 사전이면 키 배열, 다중 키 사전이면 키의 튜플 배열을 반환해요.

구문 (Syntax)

dictGetKeys(dict_name, attr_name, value_expr)

반환 값 (Returned value)

단일 키 사전: 속성이 value_expr과 같은 키 배열. 다중 키 사전: 속성이 value_expr과 같은 키의 튜플 배열. 사전에 value_expr에 해당하는 속성이 없으면 빈 배열.

dictGetOrDefault

키가 발견되면 id_expr에 해당하는 사전 속성 값을 반환하고, 키가 없으면 제공된 default_value를 반환해요.

구문 (Syntax)

dictGetOrDefault(dict_name, attr_names, id_expr, default_value_expr)

반환 값 (Returned value)

키가 발견되면 id_expr에 해당하는 사전 속성 값, 키가 없으면 제공된 default_value.

dictGetOrNull

키가 발견되면 id_expr에 해당하는 사전 속성 값을 반환하고, 키가 없으면 NULL을 반환해요.

구문 (Syntax)

dictGetOrNull(dict_name, attr_names, id_expr)

반환 값 (Returned value)

키가 발견되면 id_expr에 해당하는 사전 속성 값, 키가 없으면 NULL.

dictGetRoot

키의 가장 최상위 조상(루트)을 반환해요.

구문 (Syntax)

dictGetRoot(dict_name, key)

반환 값 (Returned value)

키의 루트. UInt64

dictGetString

사전 구성과 관계없이 사전 속성 값을 String 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetString(dict_name, attr_name, id_expr)

dictGetStringOrDefault

사전 구성과 관계없이 String로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetUInt8 / dictGetUInt16 / dictGetUInt32 / dictGetUInt64

사전 구성과 관계없이 사전 속성 값을 각각 UInt8 / UInt16 / UInt32 / UInt64 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetUInt8(dict_name, attr_name, id_expr)
dictGetUInt16(dict_name, attr_name, id_expr)
dictGetUInt32(dict_name, attr_name, id_expr)
dictGetUInt64(dict_name, attr_name, id_expr)

dictGetUInt8OrDefault / dictGetUInt16OrDefault / dictGetUInt32OrDefault / dictGetUInt64OrDefault

사전 구성과 관계없이 부호 없는 정수 타입으로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)
dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)
dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)
dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictGetUUID

사전 구성과 관계없이 사전 속성 값을 UUID 데이터 타입으로 변환해요.

구문 (Syntax)

dictGetUUID(dict_name, attr_name, id_expr)

dictGetUUIDOrDefault

사전 구성과 관계없이 UUID로 변환하거나, 키가 없으면 제공된 기본값을 반환해요.

구문 (Syntax)

dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)

dictHas

사전에 키가 존재하는지 확인해요.

구문 (Syntax)

dictHas('dict_name', id_expr)

반환 값 (Returned value)

키가 존재하면 1, 그 외에는 0. UInt8

dictIsIn

child_id_expr가 ancestor_id_expr의 자식인지, 즉 계층 관계인지 확인해요.

구문 (Syntax)

dictIsIn('dict_name', child_id_expr, ancestor_id_expr)

반환 값 (Returned value)

child_id_expr가 ancestor_id_expr의 자식이 아니면 0, 자식이거나 child_id_expr가 ancestor_id_expr 자신이면 1. UInt8

더 알아보기 (Learn more)