跳到主要内容
跳到主要内容

用于处理字典的函数

备注

对于使用 DDL 查询 创建的字典，dict_name 参数必须完全指定，如 <database>.<dict_name>。否则，将使用当前数据库。

有关连接和配置字典的信息，请参见 Dictionaries。

dictGet, dictGetOrDefault, dictGetOrNull​

从字典中检索值。

参数

  • dict_name — 字典的名称。字符串文字。
  • attr_names — 字典的列名，字符串文字，或列名的元组，Tuple(字符串文字。
  • id_expr — 键值。表达式，返回字典键类型的值或根据字典配置返回的 Tuple 类型值。
  • default_value_expr — 如果字典中不包含具有 id_expr 键的行则返回的值。表达式 或 Tuple(表达式)，返回与 attr_names 属性配置的数据类型相对应的值（或值）。

返回的值

  • 如果 ClickHouse 成功解析了属性的 属性数据类型，则函数返回与 id_expr 对应的字典属性值。

  • 如果字典中没有与 id_expr 对应的键，则：

    • dictGet 返回在字典配置中为该属性指定的 <null_value> 元素的内容。
    • dictGetOrDefault 返回作为 default_value_expr 参数传递的值。
    • dictGetOrNull 在未找到键的情况下返回 NULL。

如果 ClickHouse 无法解析属性的值或值与属性数据类型不匹配，它将抛出异常。

简单键字典示例

创建一个文本文件 ext-dict-test.csv，内容如下：

第一列为 id，第二列为 c1。

配置字典：

执行查询：

复杂键字典示例

创建一个文本文件 ext-dict-mult.csv，内容如下：

第一列为 id，第二列为 c1，第三列为 c2。

配置字典：

执行查询：

范围键字典示例

输入表：

创建字典：

执行查询：

结果：

另见

dictHas​

检查字典中是否存在某个键。

参数

  • dict_name — 字典的名称。字符串文字。
  • id_expr — 键值。表达式，返回字典键类型的值或根据字典配置返回的 Tuple 类型值。

返回的值

  • 0，表示没有该键。UInt8。
  • 1，表示存在该键。UInt8。

dictGetHierarchy​

创建一个数组，包含在 层次字典 中某个键的所有父项。

语法

参数

返回的值

dictIsIn​

检查某个键在字典中的整个层次链中是否为某个祖先。

参数

  • dict_name — 字典的名称。字符串文字。
  • child_id_expr — 要检查的键。表达式，返回一个 UInt64 类型的值。
  • ancestor_id_expr — child_id_expr 键的假定祖先。表达式，返回一个 UInt64 类型的值。

返回的值

  • 0，如果 child_id_expr 不是 ancestor_id_expr 的子项。UInt8。
  • 1，如果 child_id_expr 是 ancestor_id_expr 的子项，或者如果 child_id_expr 是 ancestor_id_expr。UInt8。

dictGetChildren​

返回第一层子项，作为索引数组。这是对 dictGetHierarchy 的逆转换。

语法

参数

返回值

示例

考虑层次字典：

第一层子项：

dictGetDescendant​

返回所有后代，就像对 dictGetChildren 函数应用 level 次递归一样。

语法

参数

  • dict_name — 字典的名称。字符串文字。
  • key — 键值。表达式，返回一个 UInt64 类型的值。
  • level — 层次级别。如果 level = 0 返回所有后代到最后。UInt8。

返回值

示例

考虑层次字典：

所有后代：

第一层后代：

dictGetAll​

检索与正则表达式树字典（regular expression tree dictionary）中每个键匹配的节点的所有属性值。

除了返回 Array(T) 类型而非 T 外，此函数的行为与 dictGet 类似。

语法

参数

  • dict_name — 字典的名称。字符串文字。
  • attr_names — 字典的列名，字符串文字，或列名的元组，Tuple(字符串文字)。
  • id_expr — 键值。表达式，返回字典键类型值的数组或根据字典配置返回的 Tuple 类型值。
  • limit - 返回的每个值数组的最大长度。在截断时，子节点优先于父节点，除此之外正则表达式树字典的定义列表顺序得到尊重。如果未指定，数组长度不受限制。

返回的值

  • 如果 ClickHouse 在字典中按定义解析属性的数据类型，则返回与 id_expr 对应的字典属性值数组。

  • 如果在字典中没有与 id_expr 对应的键，则返回一个空数组。

如果 ClickHouse 无法解析属性的值或值与属性数据类型不匹配，它将抛出异常。

示例

考虑以下正则表达式树字典：

获取所有匹配值：

获取最多 2 个匹配值：

其他函数​

ClickHouse 支持专门的函数，无论字典配置如何，都将字典属性值转换为特定数据类型。

函数包括：

  • dictGetInt8, dictGetInt16, dictGetInt32, dictGetInt64
  • dictGetUInt8, dictGetUInt16, dictGetUInt32, dictGetUInt64
  • dictGetFloat32, dictGetFloat64
  • dictGetDate
  • dictGetDateTime
  • dictGetUUID
  • dictGetString
  • dictGetIPv4, dictGetIPv6

所有这些函数都有 OrDefault 修改。例如，dictGetDateOrDefault。

语法：

参数

  • dict_name — 字典的名称。字符串文字。
  • attr_name — 字典的列名。字符串文字。
  • id_expr — 键值。表达式，返回一个 UInt64 或 Tuple 类型的值，具体取决于字典配置。
  • default_value_expr — 如果字典中不包含具有 id_expr 键的行则返回的值。表达式，返回与 attr_name 属性配置的数据类型相对应的值。

返回的值

  • 如果 ClickHouse 在 属性的数据类型 中成功解析属性，则函数返回与 id_expr 对应的字典属性值。

  • 如果在字典中没有请求的 id_expr，那么：

    • dictGet[Type] 返回在字典配置中为该属性指定的 <null_value> 元素的内容。
    • dictGet[Type]OrDefault 返回作为 default_value_expr 参数传递的值。

如果 ClickHouse 无法解析属性的值或值与属性数据类型不匹配，它将抛出异常。