用于处理字典的函数

注意

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

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

示例字典

本节中的示例使用以下字典。您可以在 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​

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

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