用于处理字典的函数

注意

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

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

dictGet、dictGetOrDefault、dictGetOrNull

从字典中检索值。

dictGet('dict_name', attr_names, id_expr)
dictGetOrDefault('dict_name', attr_names, id_expr, default_value_expr)
dictGetOrNull('dict_name', attr_name, id_expr)

参数

dict_name — 字典名称。字符串字面量。
attr_names — 字典列的名称（字符串字面量），或由列名组成的元组 Tuple（字符串字面量）。
id_expr — 键值。Expression 返回与字典键类型相同的值，或返回 Tuple 类型的值，视字典配置而定。
default_value_expr — 当字典中不包含具有 id_expr 键的行时返回的值。Expression 或 Tuple(Expression)，返回值（或一组值）的数据类型与为 attr_names 属性配置的数据类型一致。

返回值

如果 ClickHouse 能按该属性的数据类型成功解析该属性，这些函数会返回与 id_expr 对应的字典属性值。
如果在字典中找不到与 id_expr 对应的键，则：
- dictGet 返回字典配置中为该属性指定的 <null_value> 元素的内容。
- dictGetOrDefault 返回作为 default_value_expr 参数传入的值。
- dictGetOrNull 在字典中未找到键时返回 NULL。

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

简单键字典示例

创建一个文本文件 ext-dict-test.csv,包含以下内容:

1,1
2,2

第一列是 id,第二列是 c1。

配置字典：

<clickhouse>
    <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>
</clickhouse>

执行查询：

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 │
└─────┴────────┘

复合键字典示例

创建一个文本文件 ext-dict-mult.csv,包含以下内容:

1,1,'1'
2,2,'2'
3,3,'3'

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

配置字典：

<clickhouse>
    <dictionary>
        <name>ext-dict-mult</name>
        <source>
            <file>
                <path>/path-to/ext-dict-mult.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>
            <attribute>
                <name>c2</name>
                <type>String</type>
                <null_value></null_value>
            </attribute>
        </structure>
        <lifetime>0</lifetime>
    </dictionary>
</clickhouse>

执行查询：

SELECT
    dictGet('ext-dict-mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

┌─val─────┬─type──────────────────┐
│ (1,'1') │ Tuple(UInt8, String)  │
│ (2,'2') │ Tuple(UInt8, String)  │
│ (3,'3') │ Tuple(UInt8, String)  │
└─────────┴───────────────────────┘

范围键字典示例

输入表：

CREATE TABLE range_key_dictionary_source_table
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
ENGINE = TinyLog();

INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');

创建字典：

CREATE DICTIONARY range_key_dictionary
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
PRIMARY KEY key
SOURCE(CLICKHOUSE(HOST 'localhost' PORT tcpPort() TABLE 'range_key_dictionary_source_table'))
LIFETIME(MIN 1 MAX 1000)
LAYOUT(RANGE_HASHED())
RANGE(MIN start_date MAX end_date);

执行查询：

SELECT
    (number, toDate('2019-05-20')),
    dictHas('range_key_dictionary', number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value_nullable', number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', ('value', 'value_nullable'), number, toDate('2019-05-20'))
FROM system.numbers LIMIT 5 FORMAT TabSeparated;

结果：

(0,'2019-05-20')        0       \N      \N      (NULL,NULL)
(1,'2019-05-20')        1       First   First   ('First','First')
(2,'2019-05-20')        1       Second  \N      ('Second',NULL)
(3,'2019-05-20')        1       Third   Third   ('Third','Third')
(4,'2019-05-20')        0       \N      \N      (NULL,NULL)

另请参阅

字典（Dictionaries）

dictHas

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

dictHas('dict_name', id_expr)

参数

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

返回值

键不存在时为 0。UInt8。
键存在时为 1。UInt8。

dictGetHierarchy

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

语法

dictGetHierarchy('dict_name', key)

参数

dict_name — 字典名。String literal。
key — 键值。返回 UInt64 类型值的表达式。

返回值

该键对应的父键。Array(UInt64)。

dictIsIn

在字典的完整层级链中检查某个键的祖先。

dictIsIn('dict_name', child_id_expr, ancestor_id_expr)

参数

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 的逆向变换。

语法

dictGetChildren(dict_name, key)

参数

dict_name — 字典名称。字符串字面量。
key — 键值。表达式，返回 UInt64 类型的值。

返回值

该键的第一层子节点。Array(UInt64)。

示例

考虑如下层级字典：

┌─id─┬─parent_id─┐
│  1 │         0 │
│  2 │         1 │
│  3 │         1 │
│  4 │         2 │
└────┴───────────┘

一级子节点：

SELECT dictGetChildren('hierarchy_flat_dictionary', number) FROM system.numbers LIMIT 4;

┌─dictGetChildren('hierarchy_flat_dictionary', number)─┐
│ [1]                                                  │
│ [2,3]                                                │
│ [4]                                                  │
│ []                                                   │
└──────────────────────────────────────────────────────┘

dictGetDescendant

返回所有后代，相当于对 dictGetChildren 函数递归调用 level 次的结果。

语法

dictGetDescendants(dict_name, key, level)

参数

dict_name — 字典名称。字符串字面量。
key — 键值。表达式，返回 UInt64 类型的值。
level — 层级。如果 level = 0，则返回该键直到最底层的所有后代。UInt8。

返回值

指定键的所有后代。Array(UInt64)。

示例

考虑如下层级字典：

┌─id─┬─parent_id─┐
│  1 │         0 │
│  2 │         1 │
│  3 │         1 │
│  4 │         2 │
└────┴───────────┘

所有子节点：

SELECT dictGetDescendants('hierarchy_flat_dictionary', number) FROM system.numbers LIMIT 4;

┌─dictGetDescendants('hierarchy_flat_dictionary', number)─┐
│ [1,2,3,4]                                               │
│ [2,3,4]                                                 │
│ [4]                                                     │
│ []                                                      │
└─────────────────────────────────────────────────────────┘

第一层子节点：

SELECT dictGetDescendants('hierarchy_flat_dictionary', number, 1) FROM system.numbers LIMIT 4;

┌─dictGetDescendants('hierarchy_flat_dictionary', number, 1)─┐
│ [1]                                                        │
│ [2,3]                                                      │
│ [4]                                                        │
│ []                                                         │
└────────────────────────────────────────────────────────────┘

dictGetAll

对于每个键，从正则表达式树字典中获取与之匹配的所有节点的属性值。

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

语法

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

参数

dict_name — 字典名称。String literal。
attr_names — 字典中列的名称，String literal，或列名的元组，Tuple（String literal）。
id_expr — 键的值。Expression，返回字典键类型值的数组，或者根据字典配置返回 Tuple 类型的值。
limit - 每个返回数组中值的最大数量。发生截断时，子节点优先于父节点；在其他情况下，会遵循为 regexp 树字典定义的列表顺序。如果未指定，则数组长度不受限制。

返回值

如果 ClickHouse 能够按照字典中为该属性定义的数据类型成功解析该属性，则返回一个数组，数组中包含字典属性值，这些值对应于由 attr_names 指定的每个属性的 id_expr。
如果字典中没有与 id_expr 对应的键，则返回空数组。

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

示例

考虑以下 regexp 树字典：

CREATE DICTIONARY regexp_dict
(
    regexp String,
    tag String
)
PRIMARY KEY(regexp)
SOURCE(YAMLRegExpTree(PATH '/var/lib/clickhouse/user_files/regexp_tree.yaml'))
LAYOUT(regexp_tree)
...

# /var/lib/clickhouse/user_files/regexp_tree.yaml \{#varlibclickhouseuser_filesregexp_treeyaml}
- regexp: 'foo'
  tag: 'foo_attr'
- regexp: 'bar'
  tag: 'bar_attr'
- regexp: 'baz'
  tag: 'baz_attr'

获取所有匹配值：

SELECT dictGetAll('regexp_dict', 'tag', 'foobarbaz');

┌─dictGetAll('regexp_dict', 'tag', 'foobarbaz')─┐
│ ['foo_attr','bar_attr','baz_attr']            │
└───────────────────────────────────────────────┘

获取最多 2 个匹配的值：

SELECT dictGetAll('regexp_dict', 'tag', 'foobarbaz', 2);

┌─dictGetAll('regexp_dict', 'tag', 'foobarbaz', 2)─┐
│ ['foo_attr','bar_attr']                          │
└──────────────────────────────────────────────────┘

dictGetKeys

返回其属性等于指定值的字典键。对于单个属性，这是 dictGet 的逆向操作。

语法

dictGetKeys('dict_name', 'attr_name', value_expr);

参数

dict_name — 字典名称。字符串字面量。
attr_name — 字典属性列名称。字符串字面量。
value_expr — 用于与属性进行匹配的值。表达式，必须可以转换为该属性的数据类型。

返回值

对于单键字典：返回属性等于 value_expr 的键组成的数组。Array(T)，其中 T 为字典键的数据类型。
对于多键字典：返回属性等于 value_expr 的键元组数组。Array(Tuple(T1, T2, ...))，其中每个 Tuple 按顺序包含字典的键列。
如果在字典中找不到与 value_expr 对应的属性值，则返回空数组。

如果 ClickHouse 无法解析属性的值，或者该值无法转换为属性的数据类型，则会抛出异常。

示例

考虑以下字典：

 ┌─id─┬─level──┐
 │  1 │ low    │
 │  2 │ high   │
 │  3 │ medium │
 │  4 │ high   │
 └────┴────────┘

现在来获取所有级别为 high 的 ID：

SELECT dictGetKeys('levels', 'level', 'high') AS ids;

 ┌─ids───┐
 │ [4,2] │
 └───────┘

注意

使用 max_reverse_dictionary_lookup_cache_size_bytes 设置来限制 dictGetKeys 在每个查询中使用的反向查找缓存大小。该缓存为每个属性值存储序列化的键元组，以避免在同一查询内重复扫描字典。缓存不会在查询之间持久化。当达到限制时，条目将按 LRU 策略进行淘汰。对于大型字典、输入基数较低且工作集可以被缓存完全容纳的场景，此设置最为有效。将其设置为 0 可禁用缓存。

另外，如果 attr_name 列的所有唯一值都可以被缓存完全容纳，那么在大多数情况下，函数的执行时间应当与输入行数呈线性关系，只需额外进行少量的字典扫描。

其他函数

ClickHouse 支持一些专用函数，这些函数可以在不受字典配置影响的情况下，将字典属性值转换为特定数据类型。

函数：

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

所有这些函数都有带 OrDefault 后缀的变体。例如，dictGetDateOrDefault。

语法：

dictGet[Type]('dict_name', 'attr_name', id_expr)
dictGet[Type]OrDefault('dict_name', 'attr_name', id_expr, default_value_expr)

参数

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 无法解析该属性的值，或该值与属性的数据类型不匹配，则会抛出异常。

示例字典

本节中的示例使用以下字典。您可以在 ClickHouse 中创建这些字典，以便运行后文所述函数的示例。

用于 dictGet<T> 和 dictGet<T>OrDefault 函数的示例字典

-- 创建包含所有所需数据类型的表
CREATE TABLE all_types_test (
    `id` UInt32,
    
    -- String 类型
    `String_value` String,
    
    -- 无符号整数类型
    `UInt8_value` UInt8,
    `UInt16_value` UInt16,
    `UInt32_value` UInt32,
    `UInt64_value` UInt64,
    
    -- 有符号整数类型
    `Int8_value` Int8,
    `Int16_value` Int16,
    `Int32_value` Int32,
    `Int64_value` Int64,
    
    -- 浮点类型
    `Float32_value` Float32,
    `Float64_value` Float64,
    
    -- 日期/时间类型
    `Date_value` Date,
    `DateTime_value` DateTime,
    
    -- 网络类型
    `IPv4_value` IPv4,
    `IPv6_value` IPv6,
    
    -- UUID 类型
    `UUID_value` UUID
) ENGINE = MergeTree() 
ORDER BY id;

-- 插入测试数据
INSERT INTO all_types_test VALUES
(
    1,                              -- id
    'ClickHouse',                   -- String
    100,                            -- UInt8
    5000,                           -- UInt16
    1000000,                        -- UInt32
    9223372036854775807,            -- UInt64
    -100,                           -- Int8
    -5000,                          -- Int16
    -1000000,                       -- Int32
    -9223372036854775808,           -- Int64
    123.45,                         -- Float32
    987654.123456,                  -- Float64
    '2024-01-15',                   -- Date
    '2024-01-15 10:30:00',          -- DateTime
    '192.168.1.1',                  -- IPv4
    '2001:db8::1',                  -- IPv6
    '550e8400-e29b-41d4-a716-446655440000' -- UUID
)

-- 创建字典
CREATE DICTIONARY all_types_dict
(
    id UInt32,
    String_value String,
    UInt8_value UInt8,
    UInt16_value UInt16,
    UInt32_value UInt32,
    UInt64_value UInt64,
    Int8_value Int8,
    Int16_value Int16,
    Int32_value Int32,
    Int64_value Int64,
    Float32_value Float32,
    Float64_value Float64,
    Date_value Date,
    DateTime_value DateTime,
    IPv4_value IPv4,
    IPv6_value IPv6,
    UUID_value UUID
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'all_types_test' DB 'default'))
LAYOUT(HASHED())
LIFETIME(MIN 300 MAX 600);

用于 dictGetAll 的示例字典

创建一个表来存储 regexp tree 字典的数据：

CREATE TABLE regexp_os(
    id UInt64,
    parent_id UInt64,
    regexp String,
    keys Array(String),
    values Array(String)
)
ENGINE = Memory;

向表中插入数据：

INSERT INTO regexp_os 
SELECT *
FROM s3(
    'https://datasets-documentation.s3.eu-west-3.amazonaws.com/' ||
    'user_agent_regex/regexp_os.csv'
);

创建 regexp tree 字典：

CREATE DICTIONARY regexp_tree
(
    regexp String,
    os_replacement String DEFAULT 'Other',
    os_v1_replacement String DEFAULT '0',
    os_v2_replacement String DEFAULT '0',
    os_v3_replacement String DEFAULT '0',
    os_v4_replacement String DEFAULT '0'
)
PRIMARY KEY regexp
SOURCE(CLICKHOUSE(TABLE 'regexp_os'))
LIFETIME(MIN 0 MAX 0)
LAYOUT(REGEXP_TREE);

范围键字典示例

创建输入表：

CREATE TABLE range_key_dictionary_source_table
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
ENGINE = TinyLog();

向输入表中插入数据：

INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');

创建字典：

CREATE DICTIONARY range_key_dictionary
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
PRIMARY KEY key
SOURCE(CLICKHOUSE(HOST 'localhost' PORT tcpPort() TABLE 'range_key_dictionary_source_table'))
LIFETIME(MIN 1 MAX 1000)
LAYOUT(RANGE_HASHED())
RANGE(MIN start_date MAX end_date);

复合键字典示例

创建源表：

CREATE TABLE dict_mult_source
(
id UInt32,
c1 UInt32,
c2 String
) ENGINE = Memory;

向源表中插入数据：

INSERT INTO dict_mult_source VALUES
(1, 1, '1'),
(2, 2, '2'),
(3, 3, '3');

创建字典：

CREATE DICTIONARY ext_dict_mult
(
    id UInt32,
    c1 UInt32,
    c2 String
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'dict_mult_source' DB 'default'))
LAYOUT(FLAT())
LIFETIME(MIN 0 MAX 0);

层级字典示例

创建源表：

CREATE TABLE hierarchy_source
(
  id UInt64,
  parent_id UInt64,
  name String
) ENGINE = Memory;

向源表中插入数据：

INSERT INTO hierarchy_source VALUES
(0, 0, 'Root'),
(1, 0, 'Level 1 - Node 1'),
(2, 1, 'Level 2 - Node 2'),
(3, 1, 'Level 2 - Node 3'),
(4, 2, 'Level 3 - Node 4'),
(5, 2, 'Level 3 - Node 5'),
(6, 3, 'Level 3 - Node 6');

-- 0（Root）
-- └── 1（Level 1 - Node 1）
--     ├── 2（Level 2 - Node 2）
--     │   ├── 4（Level 3 - Node 4）
--     │   └── 5（Level 3 - Node 5）
--     └── 3（Level 2 - Node 3）
--         └── 6（Level 3 - Node 6）

创建字典：

CREATE DICTIONARY hierarchical_dictionary
(
    id UInt64,
    parent_id UInt64 HIERARCHICAL,
    name String
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'hierarchy_source' DB 'default'))
LAYOUT(HASHED())
LIFETIME(MIN 300 MAX 600);

dictGet

首次引入于：v18.16

从字典中检索值。

语法

dictGet('dict_name', attr_names, id_expr)

参数

dict_name — 字典名称。String
attr_names — 字典中列的名称，或列名的元组。String 或 Tuple(String)
id_expr — 键值。返回 UInt64/Tuple(T) 的表达式。UInt64 或 Tuple(T)

返回值

如果找到该键，则返回与 id_expr 对应的字典属性值。如果未找到该键，则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

示例

获取单个属性

SELECT dictGet('ext_dict_test', 'c1', toUInt64(1)) AS val

多个属性

SELECT
    dictGet('ext_dict_mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

┌─val─────┬─type───────────┐
│ (1,'1') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
│ (2,'2') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
│ (3,'3') │ Tuple(        ↴│
│         │↳    c1 UInt32,↴│
│         │↳    c2 String) │
└─────────┴────────────────┘

dictGetAll

引入版本：v23.5

将字典属性值转换为 All 数据类型，而不受字典配置影响。

语法

dictGetAll(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列名。String 或 Tuple(String)
id_expr — 键值。一个返回字典键类型的值或元组类型值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回字典中与 id_expr 对应的属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT
    'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36' AS user_agent,

    -- 这将匹配所有适用的模式
    dictGetAll('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS all_matches,

    -- 这仅返回第一个匹配项
    dictGet('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS first_match;

┌─user_agent─────────────────────────────────────────────────────┬─all_matches─────────────────────────────┬─first_match─┐
│ Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36 │ ['Android','Android','Android','Linux'] │ Android     │
└────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴─────────────┘

dictGetChildren

引入版本：v21.4

返回一个由索引组成的数组，表示第一层级的子节点。它是 dictGetHierarchy 的逆向变换。

语法

dictGetChildren(dict_name, key)

参数

dict_name — 字典名称。String
key — 要检查的键。const String

返回值

返回该键的第一层子节点。Array(UInt64)

示例

获取字典的第一层子节点

SELECT dictGetChildren('hierarchical_dictionary', 2);

┌─dictGetChild⋯ionary', 2)─┐
│ [4,5]                    │
└──────────────────────────┘

dictGetDate

自 v1.1 起引入

将字典的属性值转换为 Date 数据类型，而不受字典配置的限制。

语法

dictGetDate(dict_name, attr_name, id_expr)

参数

dict_name — 字典的名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。一个返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性的值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT dictGetDate('all_types_dict', 'Date_value', 1)

┌─dictGetDate(⋯_value', 1)─┐
│               2020-01-01 │
└──────────────────────────┘

dictGetDateOrDefault

自 v1.1 起引入

将字典属性值转换为 Date 数据类型（不受字典配置影响），如果未找到键，则返回提供的默认值。

语法

dictGetDateOrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含以 id_expr 为键的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 对于存在的键
SELECT dictGetDate('all_types_dict', 'Date_value', 1);

-- 对于不存在的键,返回提供的默认值
SELECT dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'));

┌─dictGetDate(⋯_value', 1)─┐
│               2024-01-15 │
└──────────────────────────┘
┌─dictGetDateO⋯70-01-01'))─┐
│               1970-01-01 │
└──────────────────────────┘

dictGetDateTime

自 v1.1 起引入

将字典属性值转换为 DateTime 数据类型，而不考虑字典的配置。

语法

dictGetDateTime(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。一个返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1)

┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘

dictGetDateTimeOrDefault

自 v1.1 引入

将字典属性值转换为 DateTime 数据类型，而不受字典配置方式的影响；如果未找到该键，则返回提供的默认值。

语法

dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值（或值集合）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 对于存在的键
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);

-- 对于不存在的键,返回提供的默认值
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));

┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘
┌─dictGetDateT⋯0:00:00'))──┐
│      1970-01-01 00:00:00 │
└──────────────────────────┘

dictGetDescendants

自 v21.4 起引入

返回通过递归调用 dictGetChildren 函数 level 次所得到的全部后代。

语法

dictGetDescendants(dict_name, key, level)

参数

dict_name — 字典名称。String
key — 要检查的键。const String
level — 要检查的层级。层级深度。如果 level = 0，则返回该键到最底层的所有后代。UInt8

返回值

返回该键的所有后代。Array(UInt64)

示例

获取字典的第一层子节点

-- 考虑以下层级字典：
-- 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)

┌─dictGetDesce⋯ary', 0, 2)─┐
│ [3,2]                    │
└──────────────────────────┘

dictGetFloat32

自 v1.1 起引入

将字典中属性的值转换为 Float32 数据类型，而不受字典配置的影响。

语法

dictGetFloat32(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

用法示例

SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1)

┌─dictGetFloat⋯_value', 1)─┐
│               -123.123   │
└──────────────────────────┘

dictGetFloat32OrDefault

引入于：v1.1

将字典属性值转换为 Float32 数据类型，而不受字典配置影响；如果未找到键，则返回提供的默认值。

语法

dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列名。String 或 Tuple(String)
id_expr — 键值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 查询存在的键
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);

-- 查询不存在的键时,返回提供的默认值 (-1.0)
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);

┌─dictGetFloat⋯_value', 1)─┐
│                   123.45 │
└──────────────────────────┘
┌─dictGetFloat⋯e', 999, -1)─┐
│                       -1  │
└───────────────────────────┘

dictGetFloat64

自 v1.1 引入

将字典属性值转换为 Float64 数据类型，无论字典如何配置。

语法

dictGetFloat64(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中的列名。String 或 Tuple(String)
id_expr — 键值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

用法示例

SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1)

┌─dictGetFloat⋯_value', 1)─┐
│                 -123.123 │
└──────────────────────────┘

dictGetFloat64OrDefault

自 v1.1 版本引入

将字典属性值转换为 Float64 数据类型，而不受字典配置的影响；如果未找到对应键，则返回提供的默认值。

语法

dictGetFloat64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列名。String 或 Tuple(String)
id_expr — 键值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 对于存在的键
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);

-- 对于不存在的键，返回提供的默认值 (nan)
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);

┌─dictGetFloat⋯_value', 1)─┐
│            987654.123456 │
└──────────────────────────┘
┌─dictGetFloat⋯, 999, nan)─┐
│                      nan │
└──────────────────────────┘

dictGetHierarchy

引入版本：v1.1

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

语法

dictGetHierarchy(dict_name, key)

参数

dict_name — 字典名称。String
key — 键。const String

返回值

返回该键对应的父级项。Array(UInt64)

示例

获取某个键的层级结构

SELECT dictGetHierarchy('hierarchical_dictionary', 5)

┌─dictGetHiera⋯ionary', 5)─┐
│ [5,2,1]                  │
└──────────────────────────┘

dictGetIPv4

引入版本：v1.1

无论字典如何配置，都将字典属性值转换为 IPv4 数据类型。

语法

dictGetIPv4(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列名。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素内容。

注意

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

示例

使用示例

SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1)

┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1                         │
└─────────────────────────────────────┘

dictGetIPv4OrDefault

引入版本：v23.1

将字典属性的值转换为 IPv4 数据类型，而不受字典配置影响；如果未找到该键，则返回提供的默认值。

语法

dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典的名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

使用示例

-- 对于存在的键
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));

┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1                         │
└─────────────────────────────────────┘
┌─dictGetIPv4OrDefa⋯0.0.0.0'))─┐
│ 0.0.0.0                      │
└──────────────────────────────┘

dictGetIPv6

引入于：v23.1

将字典属性值转换为 IPv6 数据类型，而不受字典配置的影响。

语法

dictGetIPv6(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。一个返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素中的内容。

注意

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

示例

使用示例

SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1)

┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334        │
└─────────────────────────────────────┘

dictGetIPv6OrDefault

引入于：v23.1

将字典属性值转换为 IPv6 数据类型（无论字典如何配置），或者在未找到键时返回提供的默认值。

语法

dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列（属性）的名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不存在具有 id_expr 键的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

使用示例

-- 对于存在的键
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);

-- 对于不存在的键,返回提供的默认值
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);

┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334        │
└─────────────────────────────────────┘
┌─dictGetIPv6OrDefa⋯:1'::IPv6)─┐
│ ::1                          │
└──────────────────────────────┘

dictGetInt16

引入版本：v1.1

将字典的属性值转换为 Int16 数据类型，与字典的配置无关。

语法

dictGetInt16(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典的列名。String 或 Tuple(String)
id_expr — 键值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性的值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

用法示例

SELECT dictGetInt16('all_types_dict', 'Int16_value', 1)

┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘

dictGetInt16OrDefault

引入版本：v1.1

无论字典如何配置，都将字典属性值转换为 Int16 数据类型；如果未找到该键，则返回提供的默认值。

语法

dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列（属性）的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含以 id_expr 为键的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回 default_value_expr 参数中传入的值。

注意

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

示例

用法示例

-- 查询存在的键
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);

-- 查询不存在的键时，返回提供的默认值 (-1)
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);

┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘
┌─dictGetInt16⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetInt32

引入于：v1.1

将字典属性值转换为 Int32 数据类型，忽略字典自身的配置。

语法

dictGetInt32(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列的名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT dictGetInt32('all_types_dict', 'Int32_value', 1)

┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘

dictGetInt32OrDefault

引入于：v1.1

将字典属性值转换为 Int32 类型，而不考虑字典的配置；如果未找到该键，则返回提供的默认值。

语法

dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列名。String 或 Tuple(String)
id_expr — 键值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含具有 id_expr 键的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 查询存在的键
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);

-- 查询不存在的键时，返回提供的默认值 (-1)
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);

┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘
┌─dictGetInt32⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetInt64

自 v1.1 起引入

将字典属性值转换为 Int64 数据类型，无论字典配置如何。

语法

dictGetInt64(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性的值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT dictGetInt64('all_types_dict', 'Int64_value', 1)

┌─dictGetInt64⋯_value', 1)───┐
│       -9223372036854775807 │
└────────────────────────────┘

dictGetInt64OrDefault

引入于：v1.1

将字典属性值转换为 Int64 数据类型，不受字典配置影响；如果未找到键，则返回指定的默认值。

语法

dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回 default_value_expr 参数中传入的值。

注意

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

示例

使用示例

-- 查询存在的键
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);

-- 查询不存在的键时,返回提供的默认值 (-1)
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);

┌─dictGetInt64⋯_value', 1)─┐
│     -9223372036854775808 │
└──────────────────────────┘
┌─dictGetInt64⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetInt8

引入版本：v1.1

将字典的属性值转换为 Int8 数据类型，忽略字典本身的配置。

语法

dictGetInt8(dict_name, attr_name, id_expr)

参数

dict_name — 字典的名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。一个返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

用法示例

SELECT dictGetInt8('all_types_dict', 'Int8_value', 1)

┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘

dictGetInt8OrDefault

引入自：v1.1

将字典中属性的值转换为 Int8 数据类型（不受字典配置影响），如果未找到键，则返回提供的默认值。

语法

dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回传入 default_value_expr 参数的值。

注意

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

示例

用法示例

-- 查询存在的键
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);

-- 查询不存在的键时，返回提供的默认值 (-1)
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);

┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘
┌─dictGetInt8O⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

dictGetKeys

引入版本：v25.12

返回属性等于指定值的字典键。这可以看作是针对单个属性时函数 dictGet 的反向操作。

使用设置项 max_reverse_dictionary_lookup_cache_size_bytes 来限制 dictGetKeys 在每个查询中用于反向查找的缓存大小。该缓存为每个属性值存储序列化的键元组，以避免在同一查询中多次扫描字典。该缓存不会在不同查询之间持久化。当达到限制时，会按 LRU 策略淘汰条目。在字典较大且输入基数较低、工作集能够装入缓存的情况下效果最佳。将其设置为 0 可禁用缓存。

语法

dictGetKeys('dict_name', 'attr_name', value_expr)

参数

dict_name — 字典名称。String
attr_name — 要匹配的属性名。String
value_expr — 用于与属性匹配的值表达式。Expression

返回值

对于单键字典：返回一个数组，包含所有属性值等于 value_expr 的键。对于多键字典：返回一个数组，包含所有属性值等于 value_expr 的键元组。如果字典中不存在属性值为 value_expr 的条目，则返回空数组。如果 ClickHouse 无法解析该属性的值，或者该值无法转换为该属性的数据类型，则会抛出异常。

示例

用法示例

SELECT dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high') AS ids;

┌─-ids──┐
│ [4,2] │
└───────┘

dictGetOrDefault

引入版本：v18.16

从字典中获取值，如果未找到键则返回默认值。

语法

dictGetOrDefault('dict_name', attr_names, id_expr, default_value)

参数

dict_name — 字典名称。String
attr_names — 字典中列的名称，或列名的元组。String 或 Tuple(String)
id_expr — 键值。返回 UInt64/Tuple(T) 的表达式。UInt64 或 Tuple(T)
default_value — 当未找到键时要返回的默认值。类型必须与属性的数据类型一致。

返回值

如果找到了键，则返回与 id_expr 对应的字典属性值。如果未找到键，则返回提供的 default_value。

示例

获取带默认值的值

SELECT dictGetOrDefault('ext_dict_mult', 'c1', toUInt64(999), 0) AS val

dictGetOrNull

引入版本：v21.4

从字典中获取值，如果未找到对应键则返回 NULL。

语法

dictGetOrNull('dict_name', 'attr_name', id_expr)

参数

dict_name — 字典名称。字符串字面量。 - attr_name — 要检索的列名。字符串字面量。 - id_expr — 键的值。返回字典键类型值的表达式。

返回值

如果找到键，则返回与 id_expr 对应的字典属性值。如果未找到键，则返回 NULL。

示例

使用范围键字典的示例

SELECT
    (number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
FROM system.numbers LIMIT 5 FORMAT TabSeparated;

(0,'2019-05-20')  \N
(1,'2019-05-20')  第一
(2,'2019-05-20')  第二
(3,'2019-05-20')  第三
(4,'2019-05-20')  \N

dictGetString

引入版本：v1.1

将字典属性值转换为 String 数据类型，无论字典如何配置。

语法

dictGetString(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素内容。

注意

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

示例

用法示例

SELECT dictGetString('all_types_dict', 'String_value', 1)

┌─dictGetString(⋯_value', 1)─┐
│ test string                │
└────────────────────────────┘

dictGetStringOrDefault

自 v1.1 引入

将字典属性值转换为 String 数据类型，而不受字典配置影响；如果未找到键，则返回提供的默认值。

语法

dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的默认值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 对于存在的键
SELECT dictGetString('all_types_dict', 'String_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');

┌─dictGetString(⋯_value', 1)─┐
│ test string                │
└────────────────────────────┘
┌─dictGetStringO⋯ 999, 'default')─┐
│ default                         │
└─────────────────────────────────┘

dictGetUInt16

自 v1.1 版本引入

将字典属性值转换为 UInt16 数据类型，而不考虑字典配置。

语法

dictGetUInt16(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值；如果没有对应项，则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1)

┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘

dictGetUInt16OrDefault

引入于：v1.1

将字典属性值转换为 UInt16 数据类型，而不论字典配置如何；如果未找到该键，则返回提供的默认值。

语法

dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列名。String 或 Tuple(String)
id_expr — 键值表达式。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

使用示例

-- 查询存在的键
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);

-- 查询不存在的键时,返回提供的默认值 (0)
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);

┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘
┌─dictGetUInt1⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUInt32

引入于：v1.1

将字典属性值转换为 UInt32 数据类型，不受字典配置影响。

语法

dictGetUInt32(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素内容。

注意

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

示例

用法示例

SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1)

┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘

dictGetUInt32OrDefault

引入版本：v1.1

将字典属性值转换为 UInt32 数据类型，无论字典如何配置；如果未找到该键，则返回指定的默认值。

语法

dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典列名。String 或 Tuple(String)
id_expr — 键值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

使用示例

-- 查询存在的键
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);

-- 查询不存在的键时,返回提供的默认值 (0)
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);

┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘
┌─dictGetUInt3⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUInt64

自 v1.1 起提供

将字典的属性值转换为 UInt64 数据类型，而不受字典配置的影响。

语法

dictGetUInt64(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。一个返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)

┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘

dictGetUInt64OrDefault

自 v1.1 引入

将字典的属性值转换为 UInt64 数据类型，而不受字典配置影响；如果未找到键，则返回提供的默认值。

语法

dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典的名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性的值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 查询存在的键
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);

-- 查询不存在的键时，返回提供的默认值 (0)
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);

┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘
┌─dictGetUInt6⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUInt8

引入版本：v1.1

将字典属性值转换为 UInt8 数据类型，无论字典如何配置。

语法

dictGetUInt8(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中属性（列）的名称。String 或 Tuple(String)
id_expr — 键的值。一个返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值；否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

用法示例

SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1)

┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘

dictGetUInt8OrDefault

自 v1.1 引入

将字典属性值转换为 UInt8 数据类型，而不受字典配置的限制；如果未找到键，则返回提供的默认值。

语法

dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典的名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。返回字典键类型值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

使用示例

-- 查询存在的键
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);

-- 查询不存在的键时,返回提供的默认值 (0)
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);

┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘
┌─dictGetUInt8⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

dictGetUUID

自 v1.1 起提供

将字典属性值转换为 UUID 数据类型，而不受字典配置的影响。

语法

dictGetUUID(dict_name, attr_name, id_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键的值。返回字典键类型的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回在字典配置中为该属性指定的 <null_value> 元素的内容。

注意

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

示例

使用示例

SELECT dictGetUUID('all_types_dict', 'UUID_value', 1)

┌─dictGetUUID(⋯_value', 1)─────────────┐
│ 123e4567-e89b-12d3-a456-426614174000 │
└──────────────────────────────────────┘

dictGetUUIDOrDefault

自 v1.1 引入

将字典属性值转换为 UUID 数据类型，而不受字典配置影响；如果未找到键，则返回提供的默认值。

语法

dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)

参数

dict_name — 字典名称。String
attr_name — 字典中列的名称。String 或 Tuple(String)
id_expr — 键值。返回与字典键类型相同的值或元组值的表达式（取决于字典配置）。Expression 或 Tuple(T)
default_value_expr — 当字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)

返回值

返回与 id_expr 对应的字典属性值，否则返回作为 default_value_expr 参数传入的值。

注意

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

示例

用法示例

-- 对于存在的键
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);

-- 对于不存在的键,返回提供的默认值
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);

┌─dictGetUUID('all_t⋯ 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000 │
└──────────────────────────────────────┘
┌─dictGetUUIDOrDefa⋯000000000000'::UUID)─┐
│ 00000000-0000-0000-0000-000000000000   │
└────────────────────────────────────────┘

dictHas

引入版本：v1.1

检查指定键是否存在于字典中。

语法

dictHas('dict_name', id_expr)

参数

dict_name — 字典名称。String
id_expr — 键值（key）。const String

返回值

如果键存在则返回 1，否则返回 0。UInt8

示例

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

-- 考虑以下层级字典：
-- 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);

┌─dictHas('hie⋯ionary', 2)─┐
│                        1 │
└──────────────────────────┘
┌─dictHas('hie⋯ionary', 7)─┐
│                        0 │
└──────────────────────────┘

dictIsIn

引入版本：v1.1

检查字典中某个键在整个层级链上的祖先。

语法

dictIsIn(dict_name, child_id_expr, ancestor_id_expr)

参数

dict_name — 字典名称。String
child_id_expr — 要检查的键。String
ancestor_id_expr — child_id_expr 键的假定祖先。const String

返回值

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

示例

检查层级关系

-- 有效层级
SELECT dictIsIn('hierarchical_dictionary', 6, 3)

-- 无效层级
SELECT dictIsIn('hierarchical_dictionary', 3, 5)

┌─dictIsIn('hi⋯ary', 6, 3)─┐
│                        1 │
└──────────────────────────┘
┌─dictIsIn('hi⋯ary', 3, 5)─┐
│                        0 │
└──────────────────────────┘

dictGet、dictGetOrDefault、dictGetOrNull​

dictHas​

dictGetHierarchy​

dictIsIn​

dictGetChildren​

dictGetDescendant​

dictGetAll​

dictGetKeys​

其他函数​

示例字典​

dictGet​

dictGetAll​

dictGetChildren​

dictGetDate​

dictGetDateOrDefault​

dictGetDateTime​

dictGetDateTimeOrDefault​

dictGetDescendants​

dictGetFloat32​

dictGetFloat32OrDefault​

dictGetFloat64​

dictGetFloat64OrDefault​

dictGetHierarchy​

dictGetIPv4​

dictGetIPv4OrDefault​

dictGetIPv6​

dictGetIPv6OrDefault​

dictGetInt16​

dictGetInt16OrDefault​

dictGetInt32​

dictGetInt32OrDefault​

dictGetInt64​

dictGetInt64OrDefault​

dictGetInt8​

dictGetInt8OrDefault​

dictGetKeys​

dictGetOrDefault​

dictGetOrNull​

dictGetString​

dictGetStringOrDefault​

dictGetUInt16​

dictGetUInt16OrDefault​

dictGetUInt32​

dictGetUInt32OrDefault​

dictGetUInt64​

dictGetUInt64OrDefault​

dictGetUInt8​

dictGetUInt8OrDefault​

dictGetUUID​

dictGetUUIDOrDefault​

dictHas​

dictIsIn​

dictGet、dictGetOrDefault、dictGetOrNull

dictHas

dictGetHierarchy

dictIsIn

dictGetChildren

dictGetDescendant

dictGetAll

dictGetKeys

其他函数

示例字典

dictGet

dictGetAll

dictGetChildren

dictGetDate

dictGetDateOrDefault

dictGetDateTime

dictGetDateTimeOrDefault

dictGetDescendants

dictGetFloat32

dictGetFloat32OrDefault

dictGetFloat64

dictGetFloat64OrDefault

dictGetHierarchy

dictGetIPv4

dictGetIPv4OrDefault

dictGetIPv6

dictGetIPv6OrDefault

dictGetInt16

dictGetInt16OrDefault

dictGetInt32

dictGetInt32OrDefault

dictGetInt64

dictGetInt64OrDefault

dictGetInt8

dictGetInt8OrDefault

dictGetKeys

dictGetOrDefault

dictGetOrNull

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn