Dictionary を操作する関数 - ClickHouse Documentation

DDLクエリで作成された辞書では、dict_name parameter は <database>.<dict_name> のように完全修飾で指定する必要があります。そうしないと、現在の database が使用されます。

辞書の接続方法と設定については、Dictionaries を参照してください。

辞書の例

このセクションの例では、以下の Dictionary を使用します。以下で説明する関数の例を実行するには、これらを ClickHouse に作成してください。

dictGet<T> 関数および dictGet<T>OrDefault 関数用の Dictionary の例

-- 必要なすべてのデータ型を持つテーブルを作成
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
)

-- 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 用の Dictionary の例

regexp tree Dictionary 用のデータを格納するテーブルを作成します。

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 Dictionary を作成します。

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、dictGetOrDefault、dictGetOrNull、dictHas などの関数のキー引数 (id_expr) は、辞書のキーの種類によって異なります:

単純キー (UInt64) を持つ辞書の場合は、キー値を直接渡します:

SELECT dictGet('simple_key_dictionary', 'attr_name', toUInt64(1));

属性が 2 つ以上ある複合 (complex) キーの辞書では、キーの値をタプルで渡します:

SELECT dictGet('complex_key_dictionary', 'attr_name', ('value_for_field1', 42));

複合キーが単一の属性のみで構成されている場合、キー値は tuple でラップせずにそのまま直接渡せます。以下はいずれも有効で、同等です:

SELECT dictGet('complex_key_dictionary', 'attr_name', 'key');
SELECT dictGet('complex_key_dictionary', 'attr_name', tuple('key'));

これは、キーが 1 つの属性からなる ip_trie 辞書にも当てはまります。検索対象の IP アドレスは直接渡すことができます:

SELECT dictGet('ip_trie_dictionary', 'attr_name', toIPv4('202.79.32.10'));

dictGet

導入バージョン: v18.16.0 Dictionary から値を取得します。

この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。

構文

dictGet('dict_name', attr_names, id_expr)

引数

dict_name — Dictionary の名前。String
attr_names — Dictionary のカラム名、またはカラム名のタプル。String または Tuple(String)
id_expr — 秘密鍵の値。単純な秘密鍵を持つ Dictionary の場合は、UInt64 値を返す式です。複合秘密鍵を持つ Dictionary の場合は、秘密鍵の値のタプルを返す式です。複合秘密鍵が単一の属性のみで構成されている場合は、その値を tuple で囲まずに直接渡すこともできます。UInt64 または Tuple(T)

戻り値 秘密鍵が見つかった場合は、id_expr に対応する Dictionary 属性の値を返します。秘密鍵が見つからない場合は、Dictionary 設定でその属性に指定された <null_value> 要素の内容を返します。例 単一の属性を取得する

Query

CREATE TABLE ext_dict_test_source (id UInt32, c1 UInt32, c2 String) ENGINE = Memory;
INSERT INTO ext_dict_test_source VALUES (1, 1, '1'), (2, 2, '2'), (3, 3, '3');
CREATE DICTIONARY ext_dict_test (id UInt32, c1 UInt32, c2 String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'ext_dict_test_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT dictGet('ext_dict_test', 'c1', toUInt64(1)) AS val

Response

複数属性

Query

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(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT
    dictGet('ext_dict_mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

Response

┌─val─────┬─type───────────┐
├─c1─┬─c2─┼────────────────┤
│  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 正規表現ツリー辞書で、各キーに一致したすべてのノードの属性値を取得します。 T ではなく Array(T) 型の値を返す点を除き、この関数の動作は dictGet と同様です。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

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

引数

dict_name — Dictionary の名前。 String
attr_names — Dictionary のカラム名、またはカラム名のタプル。 String または Tuple(String)
id_expr — キー値。辞書キー型の値またはタプル値を返す式 (Dictionary の設定に依存) 。 Expression または Tuple(T)
limit — 任意。返される各値配列の最大長。切り詰める場合は、親ノードよりも子ノードが優先され、それ以外では regexp tree Dictionary で定義されたリスト順が尊重されます。指定しない場合、配列長は無制限です。 UInt*

戻り値 attr_names で指定された各属性について、id_expr に対応する Dictionary 属性の値の配列を返します。 Dictionary に id_expr に対応するキーがない場合は、空の配列を返します。

ClickHouse は、属性の値をパースできない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

Array(T) 例 使用例

Query

CREATE TABLE regexp_os (id UInt64, parent_id UInt64, regexp String, keys Array(String), values Array(String)) ENGINE = Memory;
INSERT INTO regexp_os VALUES
    (1, 0, 'Linux',      ['os_replacement'], ['Linux']),
    (2, 1, 'Android',    ['os_replacement'], ['Android']),
    (3, 2, 'Android 1',  ['os_replacement'], ['Android']),
    (4, 3, 'Android 12', ['os_replacement'], ['Android']);
CREATE DICTIONARY regexp_tree (regexp String, os_replacement String DEFAULT 'Other') PRIMARY KEY regexp SOURCE(CLICKHOUSE(TABLE 'regexp_os' DB currentDatabase())) LIFETIME(MIN 0 MAX 0) LAYOUT(REGEXP_TREE);
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;

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 第1階層の子を索引の配列として返します。これは dictGetHierarchy の逆変換にあたります。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetChildren(dict_name, key)

引数

dict_name — 辞書名。String
key — 確認対象のキー。const String

戻り値 キーの第1レベルの子要素を返します。Array(UInt64) 例 辞書の第1レベルの子要素を取得する

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetChildren('hierarchical_dictionary', 2);

Response

┌─dictGetChildren('hierarchical_dictionary', 2)─┐
│ [4,5]                                         │
└───────────────────────────────────────────────┘

dictGetDate

導入バージョン: v1.1.0 Dictionaryの属性値を、Dictionaryの設定にかかわらず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

CREATE TABLE all_types_test (id UInt32, Date_value Date) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2020-01-01');
CREATE DICTIONARY all_types_dict (id UInt32, Date_value Date) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetDate('all_types_dict', 'Date_value', 1)

Response

┌─dictGetDate('all_types_dict', 'Date_value', 1)─┐
│                                     2020-01-01 │
└────────────────────────────────────────────────┘

dictGetDateOrDefault

導入バージョン: v1.1.0 Dictionary の設定にかかわらず、辞書 attribute の値を Date データ型に変換し、秘密鍵が見つからない場合は指定したデフォルト値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetDateOrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary の名前。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値またはタプル値を返す式 (Dictionary の設定に依存) 。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が含まれていない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応する Dictionary 属性の値を返します。それ以外の場合は、default_value_expr パラメータとして渡された値を返します。

ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Date_value Date) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15');
CREATE DICTIONARY all_types_dict (id UInt32, Date_value Date) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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'));

Response

┌─dictGetDate('all_types_dict', 'Date_value', 1)─┐
│                                     2024-01-15 │
└────────────────────────────────────────────────┘
┌─dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-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

CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1)

Response

┌─dictGetDateTime('all_types_dict', 'DateTime_value', 1)─┐
│                                    2024-01-15 10:30:00 │
└────────────────────────────────────────────────────────┘

dictGetDateTimeOrDefault

導入バージョン: v1.1.0 Dictionary の設定にかかわらず、Dictionary の属性値を 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

CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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'));

Response

┌─dictGetDateTime('all_types_dict', 'DateTime_value', 1)─┐
│                                    2024-01-15 10:30:00 │
└────────────────────────────────────────────────────────┘
┌─dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'))─┐
│                                                                                  1970-01-01 00:00:00 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictGetDescendants

導入バージョン: v21.4.0 dictGetChildren 関数を level 回再帰的に適用した場合と同様に、すべての子孫ノードを返します。

この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。

構文

dictGetDescendants(dict_name, key, level)

引数

dict_name — Dictionary 名。String
key — 確認するキー。const String
level — 確認するキーの階層レベル。level = 0 の場合は、末端まですべての子孫を返します。UInt8

戻り値 キーの子孫を返します。Array(UInt64) 例 Dictionary の第1レベルの子を取得する

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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)

Response

┌─dictGetDescendants('hierarchical_dictionary', 0, 2)─┐
│ [3,2]                                               │
└─────────────────────────────────────────────────────┘

dictGetFloat32

導入バージョン: v1.1.0 Dictionary の属性値を、Dictionary の設定にかかわらず Float32 データ型に変換します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetFloat32(dict_name, attr_name, id_expr)

引数

dict_name — 辞書の名前。String
attr_name — 辞書のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値、またはタプル値を返す式 (辞書の設定に依存) 。Expression または Tuple(T)

ClickHouse は、属性の値をパースできない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1)

Response

┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                             -123.123 │
└──────────────────────────────────────────────────────┘

dictGetFloat32OrDefault

導入バージョン: v1.1.0 Dictionary の設定にかかわらず、Dictionary の属性値を Float32 型に変換します。秘密鍵が見つからない場合は、指定したデフォルト値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary の名前。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — キー値。Dictionary キー型の値、またはタプル値を返す式 (Dictionary の設定に依存) 。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応する Dictionary 属性の値を返します。該当しない場合は、default_value_expr パラメータとして渡された値を返します。

ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 123.45);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                               123.45 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.)─┐
│                                                                   -1 │
└──────────────────────────────────────────────────────────────────────┘

dictGetFloat64

導入バージョン: v1.1.0 Dictionary の属性値を、Dictionary の設定に関係なく 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

CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1)

Response

┌─dictGetFloat64('all_types_dict', 'Float64_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

CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 987654.123456);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetFloat64('all_types_dict', 'Float64_value', 1)─┐
│                                        987654.123456 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan)─┐
│                                                                  nan │
└──────────────────────────────────────────────────────────────────────┘

dictGetHierarchy

導入バージョン: v1.1.0 階層型Dictionary 内で、キーのすべての親を含む配列を作成します。

この関数は非決定論的です。同じ引数でも、異なる結果を返すことがあります。

構文

dictGetHierarchy(dict_name, key)

引数

dict_name — Dictionary の名前。String
key — キー値。const String

戻り値 キーに対応する親を返します。Array(UInt64) 例 キーの階層を取得

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetHierarchy('hierarchical_dictionary', 5)

Response

┌─dictGetHierarchy('hierarchical_dictionary', 5)─┐
│ [5,2,1]                                        │
└────────────────────────────────────────────────┘

dictGetIPv4

導入バージョン: v1.1.0 Dictionary の設定に関係なく、Dictionary 属性の値を 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

CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1)

Response

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

dictGetIPv4OrDefault

導入バージョン: v23.1.0 Dictionary の設定にかかわらず、Dictionary の属性値を IPv4 データ型に変換します。秘密鍵が見つからない場合は、指定したデフォルト値を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary名。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — 秘密鍵値。Dictionary 秘密鍵型の値、またはタプル値を返す式 (Dictionary の設定に依存) 。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr 秘密鍵を持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応するDictionary属性の値を返します。対応する値がない場合は、default_value_expr パラメータとして渡された値を返します。

ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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'));

Response

┌─dictGetIPv4('all_types_dict', 'IPv4_value', 1)─┐
│ 192.168.0.1                                    │
└────────────────────────────────────────────────┘
┌─dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'))─┐
│ 0.0.0.0                                                                      │
└──────────────────────────────────────────────────────────────────────────────┘

dictGetIPv6

導入バージョン: v23.1.0 Dictionary の設定にかかわらず、辞書属性の値を 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

CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1)

Response

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

dictGetIPv6OrDefault

導入バージョン: v23.1.0 Dictionary 設定にかかわらず、Dictionary 属性の値を IPv6 データ型に変換します。秘密鍵が見つからない場合は、指定されたデフォルト値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary名。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — 秘密鍵値。Dictionary 秘密鍵型の値、またはタプル値 (Dictionary 設定に依存) を返す式。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr 秘密鍵を持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応するDictionary属性の値を返します。該当する値がない場合は、default_value_expr パラメータとして渡された値を返します。

ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetIPv6('all_types_dict', 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334                   │
└────────────────────────────────────────────────┘
┌─dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, CAST('::1', 'IPv6'))─┐
│ ::1                                                                            │
└────────────────────────────────────────────────────────────────────────────────┘

dictGetInt16

導入バージョン: v1.1.0 Dictionary の属性値を、Dictionary の設定にかかわらず Int16 データ型に変換します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetInt16(dict_name, attr_name, id_expr)

引数

dict_name — 辞書名。String
attr_name — 辞書のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値、またはタプル値 (辞書の設定に依存) を返す式。Expression または Tuple(T)

ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外を発生させます。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1)

Response

┌─dictGetInt16('all_types_dict', 'Int16_value', 1)─┐
│                                            -5000 │
└──────────────────────────────────────────────────┘

dictGetInt16OrDefault

導入バージョン: v1.1.0 Dictionary の属性値を、Dictionary の設定にかかわらず 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 に対応する Dictionary 属性の値を返します。対応する値がない場合は、default_value_expr パラメータとして渡された値を返します。

ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetInt16('all_types_dict', 'Int16_value', 1)─┐
│                                            -5000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt16OrDefault('all_types_dict', 'Int16_value', 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 — キー値。辞書キー型の値、または Tuple 値を返す式 (辞書の設定に依存) 。Expression または Tuple(T)

戻り値 id_expr に対応する辞書属性の値を返します。対応する値がない場合は、辞書の設定でその属性に指定された <null_value> 要素の内容を返します。

ClickHouse は、属性の値を解析できない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1)

Response

┌─dictGetInt32('all_types_dict', 'Int32_value', 1)─┐
│                                         -1000000 │
└──────────────────────────────────────────────────┘

dictGetInt32OrDefault

導入バージョン: v1.1.0 Dictionary の設定にかかわらず、辞書属性の値を Int32 データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary の名前。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値またはタプル値を返す式 (Dictionary の設定に依存します) 。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応する Dictionary 属性の値を返します。存在しない場合は、default_value_expr パラメータとして渡された値を返します。

属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetInt32('all_types_dict', 'Int32_value', 1)─┐
│                                         -1000000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt64

導入バージョン: v1.1.0 Dictionary の設定に関係なく、辞書属性の値を Int64 データ型に変換します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetInt64(dict_name, attr_name, id_expr)

引数

dict_name — 辞書名。String
attr_name — 辞書のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値またはタプル値を返す式 (辞書設定に依存) 。Expression または Tuple(T)

ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1)

Response

┌─dictGetInt64('all_types_dict', 'Int64_value', 1)─┐
│                             -9223372036854775807 │
└──────────────────────────────────────────────────┘

dictGetInt64OrDefault

導入バージョン: v1.1.0 Dictionary の設定にかかわらず、辞書属性の値を 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

CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775808);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetInt64('all_types_dict', 'Int64_value', 1)─┐
│                             -9223372036854775808 │
└──────────────────────────────────────────────────┘
┌─dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt8

導入バージョン: v1.1.0 辞書の設定に関係なく、辞書属性の値を 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 は例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1)

Response

┌─dictGetInt8('all_types_dict', 'Int8_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

CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetInt8('all_types_dict', 'Int8_value', 1)─┐
│                                           -100 │
└────────────────────────────────────────────────┘
┌─dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1)─┐
│                                                            -1 │
└───────────────────────────────────────────────────────────────┘

dictGetKeys

導入バージョン: v25.12.0 属性が指定した値に等しい辞書キーを返します。これは、単一の属性に対する関数 dictGet の逆です。 dictGetKeys で使用されるクエリごとの逆ルックアップキャッシュのサイズを制限するには、設定 max_reverse_dictionary_lookup_cache_size_bytes を使用します。このキャッシュは、同じクエリ内で辞書を再走査しないよう、各属性値に対応するシリアライズ済みのキーのタプルを格納します。このキャッシュはクエリをまたいで保持されません。上限に達すると、エントリは LRU に従って追い出されます。これは、大きな辞書で、入力のカーディナリティが低く、かつワーキングセットがキャッシュに収まる場合に最も効果的です。キャッシュを無効にするには 0 を設定します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

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

引数

dict_name — Dictionary の名前。String
attr_name — 照合する属性。String
value_expr — 属性と照合する値。Expression

戻り値 単一キーの Dictionary の場合、属性が value_expr と等しいキーの配列を返します。複合キーの Dictionary の場合、属性が value_expr と等しいキーのタプルの配列を返します。Dictionary 内に value_expr に対応する属性がない場合は、空の配列が返されます。ClickHouse は、属性の値を解析できない場合、またはその値を属性のデータ型に変換できない場合に例外をスローします。例 使用例

Query

CREATE TABLE task_priority_source (task_id UInt64, priority_level String) ENGINE = Memory;
INSERT INTO task_priority_source VALUES (1, 'low'), (2, 'high'), (3, 'medium'), (4, 'high');
CREATE DICTIONARY task_id_to_priority_dictionary (task_id UInt64, priority_level String) PRIMARY KEY task_id SOURCE(CLICKHOUSE(TABLE 'task_priority_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 0 MAX 0);
SELECT arraySort(dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high')) AS ids;

Response

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

dictGetOrDefault

導入バージョン: v18.16.0 Dictionary から値を取得します。キーが見つからない場合は、デフォルト値を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

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

引数

dict_name — Dictionary の名前。String
attr_names — Dictionary のカラム名、またはカラム名のタプル。String または Tuple(String)
id_expr — キー値。単純キーを持つ Dictionary の場合は、UInt64 値を返す式です。複合キーを持つ Dictionary の場合は、キー値のタプルを返す式です。複合キーが単一の属性で構成されている場合は、tuple でラップせずにその値を直接渡すこともできます。UInt64 または Tuple(T)
default_value — キーが見つからない場合に返されるデフォルト値。型は属性のデータ型と一致している必要があります。

戻り値 キーが見つかった場合は、id_expr に対応する Dictionary の属性値を返します。キーが見つからない場合は、指定した default_value を返します。例 デフォルト値付きで値を取得

Query

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(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT dictGetOrDefault('ext_dict_mult', 'c1', toUInt64(999), 0) AS val

Response

dictGetOrNull

導入バージョン: v21.4.0 Dictionary から値を取得し、キーが見つからない場合は NULL を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

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

引数

dict_name — 辞書の名前。文字列リテラル。 - attr_name — 取得するカラム名。文字列リテラル。 - id_expr — キー値。辞書のキー型の値を返す式。

戻り値 キーが見つかった場合は、id_expr に対応する辞書属性の値を返します。キーが見つからない場合は、NULL を返します。例 範囲キー辞書を使用する例

Query

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(TABLE 'range_key_dictionary_source_table' DB currentDatabase())) LIFETIME(MIN 1 MAX 1000) LAYOUT(RANGE_HASHED()) RANGE(MIN start_date MAX end_date);
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

dictGetRoot

導入バージョン: v26.7.0 hierarchical dictionary 内で、秘密鍵の最上位の祖先 (ルート) を返します。これは、dictGetHierarchy が返す配列の最後の要素を取得するのと等価な便利な関数です。つまり、dictGetHierarchy(dict_name, key)[-1] です。秘密鍵自体が階層の最上位ノードである場合は、その秘密鍵が返されます。秘密鍵が Dictionary に存在しない場合は、0 が返されます。

この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。

構文

dictGetRoot(dict_name, key)

引数

dict_name — Dictionary名。String
key — 秘密鍵値。UInt64

戻り値 秘密鍵の最上位の祖先 (ルート) を返します。UInt64 例 秘密鍵のルートを取得する

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetRoot('hierarchical_dictionary', 5)

Response

┌─dictGetRoot('hierarchical_dictionary', 5)─┐
│                                         1 │
└───────────────────────────────────────────┘

dictGetString

導入バージョン: v1.1.0 辞書の設定に関係なく、辞書属性の値を String データ型に変換します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetString(dict_name, attr_name, id_expr)

引数

dict_name — 辞書の名前。String
attr_name — 辞書のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。Expression または Tuple(T)

ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetString('all_types_dict', 'String_value', 1)

Response

┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘

dictGetStringOrDefault

導入バージョン: v1.1.0 Dictionary の設定にかかわらず、辞書属性の値を 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 は例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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');

Response

┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘
┌─dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default')─┐
│ default                                                                  │
└──────────────────────────────────────────────────────────────────────────┘

dictGetUInt16

導入バージョン: v1.1.0 Dictionary の属性値を、辞書設定に関係なく UInt16 データ型に変換します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetUInt16(dict_name, attr_name, id_expr)

引数

dict_name — 辞書名。String
attr_name — 辞書のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。Expression または Tuple(T)

ClickHouse は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1)

Response

┌─dictGetUInt16('all_types_dict', 'UInt16_value', 1)─┐
│                                               5000 │
└────────────────────────────────────────────────────┘

dictGetUInt16OrDefault

導入バージョン: v1.1.0 Dictionary の設定にかかわらず、Dictionary 属性の値を 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

CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetUInt16('all_types_dict', 'UInt16_value', 1)─┐
│                                               5000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 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)

ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1)

Response

┌─dictGetUInt32('all_types_dict', 'UInt32_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

CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetUInt32('all_types_dict', 'UInt32_value', 1)─┐
│                                            1000000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt64

導入バージョン: v1.1.0 辞書の設定にかかわらず、辞書属性の値を UInt64 データ型に変換します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

dictGetUInt64(dict_name, attr_name, id_expr)

引数

dict_name — Dictionary の名前。 String
attr_name — Dictionary のカラム名。 String または Tuple(String)
id_expr — キー値。辞書キー型の値、またはタプル値を返す式 (辞書設定に依存) 。Expression または Tuple(T)

戻り値 id_expr に対応する Dictionary 属性の値を返します。対応する値がない場合は、辞書設定でその属性に指定された <null_value> 要素の内容を返します。

ClickHouse は、属性の値を解析できない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)

Response

┌─dictGetUInt64('all_types_dict', 'UInt64_value', 1)─┐
│                                9223372036854775807 │
└────────────────────────────────────────────────────┘

dictGetUInt64OrDefault

導入バージョン: v1.1.0 Dictionary の属性値を、Dictionary の設定に関係なく UInt64 データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary の名前。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — 辞書キーの値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応する Dictionary 属性の値を返します。存在しない場合は、default_value_expr パラメータとして渡された値を返します。

属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetUInt64('all_types_dict', 'UInt64_value', 1)─┐
│                                9223372036854775807 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt8

導入バージョン: v1.1.0 Dictionary の設定に関係なく、Dictionary 属性の値を UInt8 データ型に変換します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetUInt8(dict_name, attr_name, id_expr)

引数

dict_name — 辞書名。String
attr_name — 辞書のカラム名。String または Tuple(String)
id_expr — キー値。辞書キー型の値、またはタプル値 (辞書設定に依存) を返す式。Expression または Tuple(T)

属性の値をパースできない場合、または値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1)

Response

┌─dictGetUInt8('all_types_dict', 'UInt8_value', 1)─┐
│                                              100 │
└──────────────────────────────────────────────────┘

dictGetUInt8OrDefault

導入バージョン: v1.1.0 辞書設定に関係なく、辞書属性の値をUInt8データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary の名前。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — キー値。Dictionary のキー型の値、またはタプル値を返す式 (dictionary configuration に依存) 。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応する Dictionary の属性値を返します。該当しない場合は、default_value_expr パラメーターとして渡された値を返します。

ClickHouse は、属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetUInt8('all_types_dict', 'UInt8_value', 1)─┐
│                                              100 │
└──────────────────────────────────────────────────┘
┌─dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0)─┐
│                                                              0 │
└────────────────────────────────────────────────────────────────┘

dictGetUUID

導入バージョン: v1.1.0 辞書の設定にかかわらず、辞書属性の値を 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 は、属性の値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '123e4567-e89b-12d3-a456-426614174000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1)

Response

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

dictGetUUIDOrDefault

導入バージョン: v1.1.0 Dictionary の設定に関係なく、Dictionary 属性の値を UUID データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)

引数

dict_name — Dictionary の名前。String
attr_name — Dictionary のカラム名。String または Tuple(String)
id_expr — キー値。Dictionary キー型の値またはタプル値を返す式 (辞書の設定に依存) 。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が含まれていない場合に返される値。Expression または Tuple(T)

戻り値 id_expr に対応する Dictionary 属性の値を返します。存在しない場合は、default_value_expr パラメータとして渡された値を返します。

属性の値をパースできない場合、またはその値が属性のデータ型と一致しない場合、ClickHouse は例外をスローします。

例 使用例

Query

CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '550e8400-e29b-41d4-a716-446655440000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictGetUUID('all_types_dict', 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000           │
└────────────────────────────────────────────────┘
┌─dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, CAST('00000000-0000-0000-0000-000000000000', 'UUID'))─┐
│ 00000000-0000-0000-0000-000000000000                                                                            │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictHas

導入バージョン: v1.1.0 キーがDictionaryに存在するかどうかを判定します。

この関数は非決定論的です。同じ引数に対して異なる結果を返す場合があります。

構文

dictHas('dict_name', id_expr)

引数

dict_name — Dictionary の名前。String
id_expr — キー値 const String

戻り値 キーが存在する場合は 1、存在しない場合は 0 を返します。UInt8 例 Dictionary にキーが存在するか確認する

Query

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- 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);

Response

┌─dictHas('hierarchical_dictionary', 2)─┐
│                                     1 │
└───────────────────────────────────────┘
┌─dictHas('hierarchical_dictionary', 7)─┐
│                                     0 │
└───────────────────────────────────────┘

dictIsIn

導入バージョン: v1.1.0 Dictionary 内の階層チェーン全体をたどって、キーの祖先かどうかを確認します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

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

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');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- valid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 6, 3);

-- invalid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 3, 5);

Response

┌─dictIsIn('hierarchical_dictionary', 6, 3)─┐
│                                         1 │
└───────────────────────────────────────────┘
┌─dictIsIn('hierarchical_dictionary', 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

​dictGetRoot

​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

dictGetRoot

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn