跳转到主要内容
对于使用 DDL 语句 创建的字典，必须完整指定 dict_name 参数，例如 <database>.<dict_name>。否则，将使用当前数据库。
有关如何连接和配置字典的信息，请参见 字典。

​
示例字典

本节中的示例会用到以下字典。你可以在 ClickHouse 中创建这些字典， 以运行下文所述函数的示例。 
-- 创建包含所有必需数据类型的表
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);
创建一个表，用于存储正则表达式树字典的数据：
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'
);
创建正则表达式树字典：
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（根）
-- └── 1（第 1 层 - 节点 1）
--     ├── 2（第 2 层 - 节点 2）
--     │   ├── 4（第 3 层 - 节点 4）
--     │   └── 5（第 3 层 - 节点 5）
--     └── 3（第 2 层 - 节点 3）
--         └── 6（第 3 层 - 节点 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.0 从字典中获取值。 语法 
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> 元素内容。 示例 获取单个属性
Query
SELECT dictGet('ext_dict_test', 'c1', toUInt64(1)) AS val
Response
1
多个属性
Query
SELECT
    dictGet('ext_dict_mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;
Response
┌─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.0 将字典属性值转换为 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 无法解析该属性的值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
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;
Response
┌─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.0 返回一个包含第一层子项索引的数组。它与 dictGetHierarchy 互为逆变换。 语法 
dictGetChildren(dict_name, key)
参数 返回值 返回该键的一级子节点。Array(UInt64) 示例 获取字典的一级子节点
Query
SELECT dictGetChildren('hierarchical_dictionary', 2);
Response
┌─dictGetChild⋯ionary', 2)─┐
│ [4,5]                    │
└──────────────────────────┘

​
dictGetDate

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
SELECT dictGetDate('all_types_dict', 'Date_value', 1)
Response
┌─dictGetDate(⋯_value', 1)─┐
│               2020-01-01 │
└──────────────────────────┘

​
dictGetDateOrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析该属性的值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetDate('all_types_dict', 'Date_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'));
Response
┌─dictGetDate(⋯_value', 1)─┐
│               2024-01-15 │
└──────────────────────────┘
┌─dictGetDateO⋯70-01-01'))─┐
│               1970-01-01 │
└──────────────────────────┘

​
dictGetDateTime

引入版本：v1.1.0 无论字典配置如何，都将字典属性的值转换为 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 无法解析属性值，或者该值与属性数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1)
Response
┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘

​
dictGetDateTimeOrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
-- 对于存在的键
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));
Response
┌─dictGetDateT⋯_value', 1)─┐
│      2024-01-15 10:30:00 │
└──────────────────────────┘
┌─dictGetDateT⋯0:00:00'))──┐
│      1970-01-01 00:00:00 │
└──────────────────────────┘

​
dictGetDescendants

引入版本：v21.4.0 返回所有后代节点，相当于将 dictGetChildren 函数递归应用 level 次。 语法 
dictGetDescendants(dict_name, key, level)
参数
  • dict_name — 字典名称。String
  • key — 要检查的键。const String
  • level — 要检查的层级。层级级别。若 level = 0，则返回其所有后代，直到末级。UInt8
返回值 返回该键的后代。Array(UInt64) 示例 获取字典的子节点
Query
-- 考虑以下层级字典：
-- 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)
Response
┌─dictGetDesce⋯ary', 0, 2)─┐
│ [3,2]                    │
└──────────────────────────┘

​
dictGetFloat32

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 会抛出异常。
示例 用法示例
Query
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1)
Response
┌─dictGetFloat⋯_value', 1)─┐
│               -123.123   │
└──────────────────────────┘

​
dictGetFloat32OrDefault

Introduced in: v1.1.0 将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
-- 对于存在的键
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);

-- 对于不存在的键，返回提供的默认值 (-1.0)
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);
Response
┌─dictGetFloat⋯_value', 1)─┐
│                   123.45 │
└──────────────────────────┘
┌─dictGetFloat⋯e', 999, -1)─┐
│                       -1  │
└───────────────────────────┘

​
dictGetFloat64

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1)
Response
┌─dictGetFloat⋯_value', 1)─┐
│                 -123.123 │
└──────────────────────────┘

​
dictGetFloat64OrDefault

引入版本：v1.1.0 将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);

-- 对于不存在的键，返回提供的默认值 (nan)
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);
Response
┌─dictGetFloat⋯_value', 1)─┐
│            987654.123456 │
└──────────────────────────┘
┌─dictGetFloat⋯, 999, nan)─┐
│                      nan │
└──────────────────────────┘

​
dictGetHierarchy

引入版本：v1.1.0 创建一个数组，其中包含层级字典中指定键的所有父级。 语法 
dictGetHierarchy(dict_name, key)
参数 返回值 返回该键的父级项。Array(UInt64) 示例 获取某个键的层级关系
Query
SELECT dictGetHierarchy('hierarchical_dictionary', 5)
Response
┌─dictGetHiera⋯ionary', 5)─┐
│ [5,2,1]                  │
└──────────────────────────┘

​
dictGetIPv4

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1)
Response
┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1                         │
└─────────────────────────────────────┘

​
dictGetIPv4OrDefault

引入版本：v23.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));
Response
┌─dictGetIPv4('all_⋯ 'IPv4_value', 1)─┐
│ 192.168.0.1                         │
└─────────────────────────────────────┘
┌─dictGetIPv4OrDefa⋯0.0.0.0'))─┐
│ 0.0.0.0                      │
└──────────────────────────────┘

​
dictGetIPv6

引入版本：v23.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1)
Response
┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334        │
└─────────────────────────────────────┘

​
dictGetIPv6OrDefault

于 v23.1.0 中引入 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);
Response
┌─dictGetIPv6('all_⋯ 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334        │
└─────────────────────────────────────┘
┌─dictGetIPv6OrDefa⋯:1'::IPv6)─┐
│ ::1                          │
└──────────────────────────────┘

​
dictGetInt16

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1)
Response
┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘

​
dictGetInt16OrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
-- 对于存在的键
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);

-- 对于不存在的键，返回提供的默认值 (-1)
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);
Response
┌─dictGetInt16⋯_value', 1)─┐
│                    -5000 │
└──────────────────────────┘
┌─dictGetInt16⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

​
dictGetInt32

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1)
Response
┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘

​
dictGetInt32OrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);

-- 对于不存在的键，返回提供的默认值 (-1)
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);
Response
┌─dictGetInt32⋯_value', 1)─┐
│                -1000000  │
└──────────────────────────┘
┌─dictGetInt32⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

​
dictGetInt64

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1)
Response
┌─dictGetInt64⋯_value', 1)───┐
│       -9223372036854775807 │
└────────────────────────────┘

​
dictGetInt64OrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 键存在时
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);

-- 键不存在时，返回指定的默认值 (-1)
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);
Response
┌─dictGetInt64⋯_value', 1)─┐
│     -9223372036854775808 │
└──────────────────────────┘
┌─dictGetInt64⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

​
dictGetInt8

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 Int8 数据类型。 语法 
dictGetInt8(dict_name, attr_name, id_expr)
参数 返回值 返回与 id_expr 对应的字典属性值， 否则返回字典配置中为该属性指定的 <null_value> 元素内容。
如果 ClickHouse 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1)
Response
┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘

​
dictGetInt8OrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
-- 对于存在的键
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);

-- 对于不存在的键，返回提供的默认值 (-1)
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);
Response
┌─dictGetInt8(⋯_value', 1)─┐
│                     -100 │
└──────────────────────────┘
┌─dictGetInt8O⋯', 999, -1)─┐
│                       -1 │
└──────────────────────────┘

​
dictGetKeys

引入版本：v25.12.0 返回属性等于指定值的字典键。它是函数 dictGet 在单个属性上的逆操作。 使用设置 max_reverse_dictionary_lookup_cache_size_bytes 来限制 dictGetKeys 使用的单次查询反向查找缓存大小。 该缓存会为每个属性值存储序列化后的键 Tuple，以避免在同一查询中重复扫描字典。 该缓存不会在查询之间持久保留。达到限制后，条目会按 LRU 策略被逐出。 当字典较大、输入的基数较低且工作集能够放入缓存时，这种方式效果最佳。设为 0 可禁用缓存。 语法 
dictGetKeys('dict_name', 'attr_name', value_expr)
参数
  • dict_name — 字典名称。String
  • attr_name — 要匹配的属性。String
  • value_expr — 与该属性进行匹配的值。Expression
返回值 对于单键字典：返回属性值等于 value_expr 的键数组。对于多键字典：返回属性值等于 value_expr 的键 Tuple 数组。如果字典中不存在与 value_expr 对应的属性值，则返回空数组。如果 ClickHouse 无法解析属性值，或者该值无法转换为该属性的数据类型，则会抛出异常。 示例 示例用法
Query
SELECT dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high') AS ids;
Response
┌─ids───┐
│ [4,2] │
└───────┘

​
dictGetOrDefault

引入版本：v18.16.0 从字典中获取值；如果未找到键，则返回默认值。 语法 
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。 示例 获取带默认值的值
Query
SELECT dictGetOrDefault('ext_dict_mult', 'c1', toUInt64(999), 0) AS val
Response
0

​
dictGetOrNull

引入版本：v21.4.0 从字典中获取值；如果找不到键，则返回 NULL。 语法 
dictGetOrNull('dict_name', 'attr_name', id_expr)
参数
  • dict_name — 字典名称。String 字面量。 - attr_name — 要获取的列名。String 字面量。 - id_expr — 键值。返回字典键类型值的表达式。
返回值 如果找到该键，则返回与 id_expr 对应的字典属性值。 如果未找到该键，则返回 NULL。 示例 使用范围键字典的示例
Query
SELECT
    (number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
FROM system.numbers LIMIT 5 FORMAT TabSeparated;
Response
(0,'2019-05-20')  \N
(1,'2019-05-20')  First
(2,'2019-05-20')  Second
(3,'2019-05-20')  Third
(4,'2019-05-20')  \N

​
dictGetString

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 String 数据类型。 语法 
dictGetString(dict_name, attr_name, id_expr)
参数
  • dict_name — 字典名称。String
  • attr_name — 字典的列名。String 或 Tuple(String)
  • id_expr — 键值。返回字典键类型值或 Tuple 值 (取决于字典配置) 的表达式。Expression 或 Tuple(T)
返回值 返回与 id_expr 对应的字典属性值， 否则返回字典配置中为该属性指定的 <null_value> 元素内容。
如果无法解析该属性的值，或者该值与属性的数据类型不匹配，ClickHouse 会抛出异常。
示例 用法示例
Query
SELECT dictGetString('all_types_dict', 'String_value', 1)
Response
┌─dictGetString(⋯_value', 1)─┐
│ test string                │
└────────────────────────────┘

​
dictGetStringOrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性的值转换为 String 数据类型；如果未找到键，则返回提供的默认值。 语法 
dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)
参数
  • dict_name — 字典名称。String
  • attr_name — 字典列名。String 或 Tuple(String)
  • id_expr — 键值。返回字典键类型值或 Tuple 值 (取决于字典配置) 的表达式。Expression 或 Tuple(T)
  • default_value_expr — 如果字典中不包含键为 id_expr 的行时返回的值。Expression 或 Tuple(T)
返回值 返回与 id_expr 对应的字典属性值， 否则返回作为 default_value_expr 参数传入的值。
如果 ClickHouse 无法解析属性值，或该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetString('all_types_dict', 'String_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');
Response
┌─dictGetString(⋯_value', 1)─┐
│ test string                │
└────────────────────────────┘
┌─dictGetStringO⋯ 999, 'default')─┐
│ default                         │
└─────────────────────────────────┘

​
dictGetUInt16

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1)
Response
┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘

​
dictGetUInt16OrDefault

引入于：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性数据类型不匹配，则会抛出异常。
示例 用法示例
Query
-- 对于存在的键
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);

-- 对于不存在的键，返回提供的默认值 (0)
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);
Response
┌─dictGetUInt1⋯_value', 1)─┐
│                     5000 │
└──────────────────────────┘
┌─dictGetUInt1⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

​
dictGetUInt32

引入版本：v1.1.0 将字典属性值转换为 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 无法解析该属性的值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1)
Response
┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘

​
dictGetUInt32OrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);

-- 对于不存在的键，返回提供的默认值 (0)
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);
Response
┌─dictGetUInt3⋯_value', 1)─┐
│                  1000000 │
└──────────────────────────┘
┌─dictGetUInt3⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

​
dictGetUInt64

在 v1.1.0 中引入 无论字典配置如何，都会将字典属性值转换为 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 会抛出异常。
示例 使用示例
Query
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)
Response
┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘

​
dictGetUInt64OrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);

-- 对于不存在的键，返回提供的默认值 (0)
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);
Response
┌─dictGetUInt6⋯_value', 1)─┐
│      9223372036854775807 │
└──────────────────────────┘
┌─dictGetUInt6⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

​
dictGetUInt8

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1)
Response
┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘

​
dictGetUInt8OrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 用法示例
Query
-- 对于存在的键
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);

-- 对于不存在的键，返回提供的默认值 (0)
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);
Response
┌─dictGetUInt8⋯_value', 1)─┐
│                      100 │
└──────────────────────────┘
┌─dictGetUInt8⋯e', 999, 0)─┐
│                        0 │
└──────────────────────────┘

​
dictGetUUID

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 UUID 数据类型。 语法 
dictGetUUID(dict_name, attr_name, id_expr)
参数 返回值 返回与 id_expr 对应的字典属性值， 否则返回字典配置中为该属性指定的 <null_value> 元素内容。
如果 ClickHouse 无法解析该属性的值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1)
Response
┌─dictGetUUID(⋯_value', 1)─────────────┐
│ 123e4567-e89b-12d3-a456-426614174000 │
└──────────────────────────────────────┘

​
dictGetUUIDOrDefault

引入版本：v1.1.0 无论字典配置如何，都会将字典属性值转换为 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 无法解析属性值，或者该值与属性的数据类型不匹配，则会抛出异常。
示例 使用示例
Query
-- 对于存在的键
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);

-- 对于不存在的键，返回提供的默认值
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);
Response
┌─dictGetUUID('all_t⋯ 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000 │
└──────────────────────────────────────┘
┌─dictGetUUIDOrDefa⋯000000000000'::UUID)─┐
│ 00000000-0000-0000-0000-000000000000   │
└────────────────────────────────────────┘

​
dictHas

引入于：v1.1.0 检查字典中是否存在某个键。 语法 
dictHas('dict_name', id_expr)
参数 返回值 如果键存在，则返回 1；否则返回 0。UInt8 示例 检查字典中是否存在某个键
Query
-- 考虑以下层级字典：
-- 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);
Response
┌─dictHas('hie⋯ionary', 2)─┐
│                        1 │
└──────────────────────────┘
┌─dictHas('hie⋯ionary', 7)─┐
│                        0 │
└──────────────────────────┘

​
dictIsIn

在 v1.1.0 中引入 检查字典中某个键在整个层级链中的祖先节点。 语法 
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 示例 检查层级关系
Query
-- 有效的层级关系
SELECT dictIsIn('hierarchical_dictionary', 6, 3)

-- 无效的层级关系
SELECT dictIsIn('hierarchical_dictionary', 3, 5)
Response
┌─dictIsIn('hi⋯ary', 6, 3)─┐
│                        1 │
└──────────────────────────┘
┌─dictIsIn('hi⋯ary', 3, 5)─┐
│                        0 │
└──────────────────────────┘
最后修改于 2026年6月10日