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

字典操作的函数

备注

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

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

dictGet, dictGetOrDefault, dictGetOrNull​

从字典中检索值。

参数

  • dict_name — 字典名称。 字符串文字。
  • attr_names — 字典的列名，字符串文字，或列名元组，元组(字符串文字)。
  • id_expr — 键值。 表达式，返回字典键类型的值或 元组 类型的值，具体取决于字典配置。
  • default_value_expr — 如果字典中不包含具有 id_expr 键的行，则返回的值。 表达式 或 元组(表达式)，返回的数据类型为 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 — 键值。 表达式，返回字典键类型的值或 元组 类型的值，具体取决于字典配置。

返回值

  • 如果没有该键，则返回 0。 UInt8。
  • 如果存在该键，则返回 1。 UInt8。

dictGetHierarchy​

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

语法

参数

返回值

dictIsIn​

通过字典中的整个层次链检查某个键是否是另一个键的子节点。

参数

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

返回值

  • 如果 child_id_expr 不是 ancestor_id_expr 的子节点，则返回 0。 UInt8。
  • 如果 child_id_expr 是 ancestor_id_expr 的子节点或者 child_id_expr 是 ancestor_id_expr，则返回 1。 UInt8。

dictGetChildren​

返回第一层子节点，作为索引数组。它是 dictGetHierarchy 的逆转。

语法

参数

返回值

示例

考虑以下层次字典：

第一层子节点：

dictGetDescendant​

返回所有后代，就像 dictGetChildren 函数被递归调用 level 次。

语法

参数

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

返回值

示例

考虑以下层次字典：

所有后代：

第一层后代：

dictGetAll​

检索与每个键匹配的所有节点的属性值，在 正则表达式树字典 中。

除了返回类型为 Array(T) 的值而不是 T 之外，该函数的行为与 dictGet 类似。

语法

参数

  • dict_name — 字典名称。 字符串文字。
  • attr_names — 字典的列名，字符串文字，或列名元组，元组(字符串文字)。
  • id_expr — 键值。 表达式，返回字典键类型的数组值或 元组-类型值，具体取决于字典配置。
  • limit - 每个返回的值数组的最大长度。当截断时，子节点优先于父节点，此外还遵循为正则表达式树字典定义的列表顺序。如果未指定，数组长度则无限制。

返回值

  • 如果 ClickHouse 在字典中成功解析了属性的值，符合属性的数据类型，则会返回与每个由 attr_names 指定的属性对应的字典属性值的数组。

  • 如果字典中没有与 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 或 元组 类型的值，具体取决于字典配置。
  • default_value_expr — 如果字典中不包含具有 id_expr 键的行，则返回的值。 表达式，返回 attr_name 属性配置的数据类型的值。

返回值

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

  • 如果字典中没有请求的 id_expr，则：

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

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