Functions for Working with External Dictionaries¶
For information on connecting and configuring external dictionaries, see External dictionaries.
dictGet¶
Retrieves a value from an external dictionary.
dictGet('dict_name', 'attr_name', id_expr) dictGetOrDefault('dict_name', 'attr_name', id_expr, default_value_expr)
Parameters
dict_name
— Name of the dictionary. String literal.attr_name
— Name of the column of the dictionary. String literal.id_expr
— Key value. Expression returning a UInt64 or Tuple-type value depending on the dictionary configuration.default_value_expr
— Value returned if the dictionary doesn't contain a row with theid_expr
key. Expression returning the value in the data type configured for theattr_name
attribute.
Returned value
- If ClickHouse parses the attribute successfully in the attribute's data type, functions return the value of the dictionary attribute that corresponds to
id_expr
. -
If there is no the key, corresponding to
id_expr
, in the dictionary, then:dictGet
returns the content of the<null_value>
element specified for the attribute in the dictionary configuration.dictGetOrDefault
returns the value passed as thedefault_value_expr
parameter.
ClickHouse throws an exception if it cannot parse the value of the attribute or the value doesn't match the attribute data type.
Example
Create a text file ext-dict-text.csv
containing the following:
1,1 2,2
The first column is id
, the second column is c1
.
Configure the external dictionary:
<yandex> <dictionary> <name>ext-dict-test</name> <source> <file> <path>/path-to/ext-dict-test.csv</path> <format>CSV</format> </file> </source> <layout> <flat /> </layout> <structure> <id> <name>id</name> </id> <attribute> <name>c1</name> <type>UInt32</type> <null_value></null_value> </attribute> </structure> <lifetime>0</lifetime> </dictionary> </yandex>
Perform the query:
SELECT dictGetOrDefault('ext-dict-test', 'c1', number + 1, toUInt32(number * 10)) AS val, toTypeName(val) AS type FROM system.numbers LIMIT 3
┌─val─┬─type───┐ │ 1 │ UInt32 │ │ 2 │ UInt32 │ │ 20 │ UInt32 │ └─────┴────────┘
See Also
dictHas¶
Checks whether a key is present in a dictionary.
dictHas('dict_name', id_expr)
Parameters
dict_name
— Name of the dictionary. String literal.id_expr
— Key value. Expression returning a UInt64-type value.
Returned value
- 0, if there is no key.
- 1, if there is a key.
Type: UInt8
.
dictGetHierarchy¶
For the hierarchical dictionary, returns an array of dictionary keys starting from the passed id_expr
and continuing along the chain of parent elements.
dictGetHierarchy('dict_name', id_expr)
Parameters
dict_name
— Name of the dictionary. String literal.id_expr
— Key value. Expression returning a UInt64-type value.
Returned value
Hierarchy of dictionary keys.
Type: Array(UInt64).
dictIsIn¶
Checks the ancestor of a key through the whole hierarchical chain in the dictionary.
dictIsIn('dict_name', child_id_expr, ancestor_id_expr)
Parameters
dict_name
— Name of the dictionary. String literal.child_id_expr
— Key to be checked. Expression returning a UInt64-type value.ancestor_id_expr
— Alleged ancestor of thechild_id_expr
key. Expression returning a UInt64-type value.
Returned value
- 0, if
child_id_expr
is not a child ofancestor_id_expr
. - 1, if
child_id_expr
is a child ofancestor_id_expr
or ifchild_id_expr
is anancestor_id_expr
.
Type: UInt8
.
Other functions¶
ClickHouse supports specialized functions that convert dictionary attribute values to a specific data type regardless of the dictionary configuration.
Functions:
dictGetInt8
,dictGetInt16
,dictGetInt32
,dictGetInt64
dictGetUInt8
,dictGetUInt16
,dictGetUInt32
,dictGetUInt64
dictGetFloat32
,dictGetFloat64
dictGetDate
dictGetDateTime
dictGetUUID
dictGetString
All these functions have the OrDefault
modification. For example, dictGetDateOrDefault
.
Syntax:
dictGet[Type]('dict_name', 'attr_name', id_expr) dictGet[Type]OrDefault('dict_name', 'attr_name', id_expr, default_value_expr)
Parameters
dict_name
— Name of the dictionary. String literal.attr_name
— Name of the column of the dictionary. String literal.id_expr
— Key value. Expression returning a UInt64-type value.default_value_expr
— Value which is returned if the dictionary doesn't contain a row with theid_expr
key. Expression returning a value in the data type configured for theattr_name
attribute.
Returned value
- If ClickHouse parses the attribute successfully in the attribute's data type, functions return the value of the dictionary attribute that corresponds to
id_expr
. -
If there is no requested
id_expr
in the dictionary then:dictGet[Type]
returns the content of the<null_value>
element specified for the attribute in the dictionary configuration.dictGet[Type]OrDefault
returns the value passed as thedefault_value_expr
parameter.
ClickHouse throws an exception if it cannot parse the value of the attribute or the value doesn't match the attribute data type.