用于处理字典的函数

注意

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

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

示例字典

本节中的示例使用以下字典。您可以将它们创建在 ClickHouse 中以运行下面描述的函数的示例。

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

-- Create table with all the required data types
CREATE TABLE all_types_test (
    `id` UInt32,
    
    -- String type
    `String_value` String,
    
    -- Unsigned integer types
    `UInt8_value` UInt8,
    `UInt16_value` UInt16,
    `UInt32_value` UInt32,
    `UInt64_value` UInt64,
    
    -- Signed integer types
    `Int8_value` Int8,
    `Int16_value` Int16,
    `Int32_value` Int32,
    `Int64_value` Int64,
    
    -- Floating point types
    `Float32_value` Float32,
    `Float64_value` Float64,
    
    -- Date/time types
    `Date_value` Date,
    `DateTime_value` DateTime,
    
    -- Network types
    `IPv4_value` IPv4,
    `IPv6_value` IPv6,
    
    -- UUID type
    `UUID_value` UUID
) ENGINE = MergeTree() 
ORDER BY id;

-- Insert test data
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
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 的示例字典

创建表以存储正则表达式树字典的数据

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

示例

使用示例

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

    -- This will match ALL applicable patterns
    dictGetAll('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS all_matches,

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

示例

使用示例

-- for key which exists
SELECT dictGetDate('all_types_dict', 'Date_value', 1);

-- for key which does not exist, returns the provided default value
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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);

-- for key which does not exist, returns the provided default value
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)

示例

获取字典的第一级子项

-- consider the following hierarchical dictionary:
-- 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)

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

示例

使用示例

-- for key which exists
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);

-- for key which does not exist, returns the provided default value (-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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);

-- for key which does not exist, returns the provided default value (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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);

-- for key which does not exist, returns the provided default value
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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);

-- for key which does not exist, returns the provided default value
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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);

-- for key which does not exist, returns the provided default value (-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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);

-- for key which does not exist, returns the provided default value (-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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);

-- for key which does not exist, returns the provided default value (-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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);

-- for key which does not exist, returns the provided default value (-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')  First
(2,'2019-05-20')  Second
(3,'2019-05-20')  Third
(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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetString('all_types_dict', 'String_value', 1);

-- for key which does not exist, returns the provided default value
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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);

-- for key which does not exist, returns the provided default value (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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);

-- for key which does not exist, returns the provided default value (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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);

-- for key which does not exist, returns the provideddefault value (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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);

-- for key which does not exist, returns the provided default value (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 无法解析属性的值或该值与属性数据类型不匹配，则 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 无法解析属性的值或该值与属性数据类型不匹配，则 ClickHouse 会抛出异常。

示例

使用示例

-- for key which exists
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);

-- for key which does not exist, returns the provided default value
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 — 键值 const String

返回值

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

示例

检查字典中键的存在性

-- consider the following hierarchical dictionary:
-- 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)

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

示例

检查层次关系

-- valid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 6, 3)

-- invalid hierarchy
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