辞書を扱う関数

注記

DDL クエリで作成された辞書の場合、dict_name パラメーターは <database>.<dict_name> のように完全修飾名で指定する必要があります。省略した場合は、現在のデータベースが使用されます。

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

例となる辞書

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

dictGet<T> および dictGet<T>OrDefault 関数用の例となる辞書

-- 必要なすべてのデータ型を含むテーブルを作成
CREATE TABLE all_types_test (
    `id` UInt32,
    
    -- String 型
    `String_value` String,
    
    -- 符号なし整数型
    `UInt8_value` UInt8,
    `UInt16_value` UInt16,
    `UInt32_value` UInt32,
    `UInt64_value` UInt64,
    
    -- 符号付き整数型
    `Int8_value` Int8,
    `Int16_value` Int16,
    `Int32_value` Int32,
    `Int64_value` Int64,
    
    -- 浮動小数点型
    `Float32_value` Float32,
    `Float64_value` Float64,
    
    -- 日付/時刻型
    `Date_value` Date,
    `DateTime_value` DateTime,
    
    -- ネットワーク型
    `IPv4_value` IPv4,
    `IPv6_value` IPv6,
    
    -- UUID 型
    `UUID_value` UUID
) ENGINE = MergeTree() 
ORDER BY id;

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

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

dictGetAll 用の例となる辞書

regexp ツリー辞書用のデータを保存するテーブルを作成します：

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 ツリー辞書を作成します：

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);

範囲キー Dictionary の例

入力テーブルを作成します：

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');

Dictionary を作成します：

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);

複合キー Dictionary の例

ソーステーブルを作成します：

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');

Dictionary を作成します：

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);

階層型 Dictionary の例

ソーステーブルを作成します：

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 (レベル 1 - ノード 1)
--     ├── 2 (レベル 2 - ノード 2)
--     │   ├── 4 (レベル 3 - ノード 4)
--     │   └── 5 (レベル 3 - ノード 5)
--     └── 3 (レベル 2 - ノード 3)
--         └── 6 (レベル 3 - ノード 6)

Dictionary を作成します：

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

Dictionary から値を取得します。

構文

dictGet('dict_name', attr_names, id_expr)

引数

dict_name — Dictionary の名前。String
attr_names — Dictionary のカラム名、またはカラム名のタプル。String または Tuple(String)
id_expr — キーの値。UInt64 または Tuple(T) を返す式。UInt64 または Tuple(T)

戻り値

キーが見つかった場合、id_expr に対応する Dictionary の属性値を返します。キーが見つからない場合、その属性に対して Dictionary の設定で指定された <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

Dictionary の設定に関わらず、属性値を All データ型に変換します。

構文

dictGetAll(dict_name, attr_name, id_expr)

引数

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

戻り値

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

注記

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

例

使用例

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

    -- 該当するすべてのパターンにマッチします
    dictGetAll('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS all_matches,

    -- 最初にマッチしたもののみを返します
    dictGet('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS first_match;

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

dictGetChildren

導入バージョン: v21.4

第1レベルの子要素をインデックスの配列として返します。これは dictGetHierarchy に対する逆変換です。

構文

dictGetChildren(dict_name, key)

引数

dict_name — Dictionary の名前。String
key — チェック対象のキー。const String

戻り値

指定したキーの第一階層の子要素（直下の子要素）を返します。Array(UInt64)

例

Dictionary の第一階層の子要素を取得する

SELECT dictGetChildren('hierarchical_dictionary', 2);

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

dictGetDate

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく Date データ型に変換します。

構文

dictGetDate(dict_name, attr_name, id_expr)

引数

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

戻り値

id_expr に対応する Dictionary 属性の値を返し、それ以外の場合は、その属性について Dictionary 設定で指定された <null_value> 要素の内容を返します。

注記

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

例

使用例

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

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

dictGetDateOrDefault

導入バージョン: v1.1

Dictionary の設定に関係なく、属性値を Date データ型に変換するか、キーが見つからない場合は指定されたデフォルト値を返します。

構文

dictGetDateOrDefault(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 は、属性の値をパースできない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

例

使用例

-- 存在するキーの場合
SELECT dictGetDate('all_types_dict', 'Date_value', 1);

-- 存在しないキーの場合、指定されたデフォルト値を返す
SELECT dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'));

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

dictGetDateTime

導入バージョン: v1.1

Dictionary の設定に依存せず、Dictionary 属性の値を DateTime データ型に変換します。

構文

dictGetDateTime(dict_name, attr_name, id_expr)

引数

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

戻り値

id_expr に対応する Dictionary 属性の値を返します。それ以外の場合は、Dictionary の構成でその属性に対して指定されている <null_value> 要素の内容を返します。

注記

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

例

使用例

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

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

dictGetDateTimeOrDefault

導入: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく DateTime データ型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。

構文

dictGetDateTimeOrDefault(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 は例外を送出します。

例

使用例

-- 存在するキーの場合
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);

-- 存在しないキーの場合、指定されたデフォルト値を返す
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));

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

dictGetDescendants

導入バージョン: v21.4

dictGetChildren 関数を level 回再帰的に適用した場合と同様に、すべての子孫を返します。

構文

dictGetDescendants(dict_name, key, level)

引数

dict_name — Dictionary の名前。String
key — チェック対象のキー。const String
level — 階層レベル。level = 0 の場合、末端までのすべての子孫を返します。UInt8

返り値

指定されたキーに対する子孫を返します。Array(UInt64)

例

Dictionary の第 1 階層の子要素を取得する

-- 以下の階層型Dictionaryを考えます:
-- 0 (ルート)
-- └── 1 (レベル1 - ノード1)
--     ├── 2 (レベル2 - ノード2)
--     │   ├── 4 (レベル3 - ノード4)
--     │   └── 5 (レベル3 - ノード5)
--     └── 3 (レベル2 - ノード3)
--         └── 6 (レベル3 - ノード6)

SELECT dictGetDescendants('hierarchical_dictionary', 0, 2)

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

dictGetFloat32

導入バージョン: v1.1

Dictionary の属性値を、Dictionary 設定に関係なく Float32 型に変換します。

構文

dictGetFloat32(dict_name, attr_name, id_expr)

引数

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

戻り値

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

注記

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

例

使用例

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

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

dictGetFloat32OrDefault

導入バージョン: v1.1

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 は、属性の値を解析できない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

例

使用例

-- 存在するキーの場合
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);

-- 存在しないキーの場合、指定されたデフォルト値（-1.0）を返す
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);

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

dictGetFloat64

導入されたバージョン: v1.1

Dictionary の設定に関係なく、Dictionary の属性値を Float64 データ型に変換します。

構文

dictGetFloat64(dict_name, attr_name, id_expr)

引数

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

返り値

id_expr に対応する Dictionary 属性の値を返し、それ以外の場合は、Dictionary 設定でその属性に対して指定された <null_value> 要素の内容を返します。

注記

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

例

使用例

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

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

dictGetFloat64OrDefault

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく Float64 データ型に変換します。キーが見つからない場合は、指定したデフォルト値を返します。

構文

dictGetFloat64OrDefault(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 は、属性の値をパースできない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

例

使用例

-- キーが存在する場合
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);

-- キーが存在しない場合、指定されたデフォルト値（nan）を返す
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);

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

dictGetHierarchy

導入されたバージョン: v1.1

階層型 Dictionary 内のキーについて、そのすべての親を含む配列を生成します。

構文

dictGetHierarchy(dict_name, key)

引数

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

戻り値

指定したキーに対応する親を返します。Array(UInt64)

例

キーに対する階層を取得する

SELECT dictGetHierarchy('hierarchical_dictionary', 5)

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

dictGetIPv4

導入バージョン: v1.1

Dictionary の設定に関係なく、その属性値を IPv4 データ型に変換します。

構文

dictGetIPv4(dict_name, attr_name, id_expr)

引数

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

戻り値

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

注記

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

例

使用例

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

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

dictGetIPv4OrDefault

導入バージョン: v23.1

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 は例外をスローします。

例

使用例

-- 存在するキーの場合
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);

-- 存在しないキーの場合、指定されたデフォルト値を返す
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));

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

dictGetIPv6

導入: v23.1

Dictionary の設定にかかわらず、属性値を IPv6 データ型として取得します。

構文

dictGetIPv6(dict_name, attr_name, id_expr)

引数

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

戻り値

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

注記

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

例

使用例

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

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

dictGetIPv6OrDefault

導入バージョン: v23.1

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 は例外をスローします。

例

使用例

-- 存在するキーの場合
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);

-- 存在しないキーの場合、指定されたデフォルト値を返す
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);

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

dictGetInt16

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく Int16 データ型に変換します。

構文

dictGetInt16(dict_name, attr_name, id_expr)

引数

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

戻り値

id_expr に対応する Dictionary 属性の値を返します。それ以外の場合は、Dictionary の設定でその属性に対して指定された <null_value> 要素の内容を返します。

注記

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

例

使用例

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

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

dictGetInt16OrDefault

導入バージョン: v1.1

Dictionary の設定にかかわらず属性値を Int16 型として取得し、キーが見つからない場合は指定したデフォルト値を返します。

構文

dictGetInt16OrDefault(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 は、属性値を解析できない場合、またはその値が属性のデータ型と一致しない場合に例外をスローします。

例

使用例

-- キーが存在する場合
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);

-- キーが存在しない場合、指定したデフォルト値（-1）を返す
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);

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

dictGetInt32

導入バージョン：v1.1

Dictionary の設定に関係なく、その属性値を Int32 データ型に変換します。

構文

dictGetInt32(dict_name, attr_name, id_expr)

引数

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

返り値

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

注記

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

例

使用例

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

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

dictGetInt32OrDefault

導入バージョン: v1.1

Dictionary の属性値を、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 のキー型の値、またはタプル値を返す式（Dictionary の設定に依存）。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が含まれていない場合に返される値。Expression または Tuple(T)

戻り値

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

注記

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

例

使用例

-- キーが存在する場合
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);

-- キーが存在しない場合、指定したデフォルト値（-1）を返す
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);

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

dictGetInt64

導入: v1.1

Dictionary の設定に関係なく、Dictionary の属性の値を Int64 データ型に変換します。

構文

dictGetInt64(dict_name, attr_name, id_expr)

引数

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

戻り値

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

注記

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

例

使用例

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

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

dictGetInt64OrDefault

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく Int64 データ型に変換するか、キーが見つからない場合は指定されたデフォルト値を返します。

構文

dictGetInt64OrDefault(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 は、属性値を解析できない場合、または値が属性のデータ型と一致しない場合に例外をスローします。

例

使用例

-- キーが存在する場合
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);

-- キーが存在しない場合、指定したデフォルト値（-1）を返す
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);

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

dictGetInt8

導入バージョン: v1.1

Dictionary の設定に関係なく、Dictionary の属性値を Int8 データ型に変換して返します。

構文

dictGetInt8(dict_name, attr_name, id_expr)

引数

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

戻り値

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

注記

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

例

使用例

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

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

dictGetInt8OrDefault

v1.1 で導入

Dictionary の設定に関係なく、Dictionary の属性値を Int8 データ型に変換し、キーが見つからない場合は指定したデフォルト値を返します。

構文

dictGetInt8OrDefault(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 は例外をスローします。

例

使用例

-- キーが存在する場合
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);

-- キーが存在しない場合、指定したデフォルト値（-1）を返す
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);

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

dictGetKeys

導入バージョン: v25.12

指定された値と等しい属性を持つ Dictionary のキーを返します。これは、単一の属性に対する dictGet 関数の逆の動作です。

dictGetKeys が使用するクエリごとの逆引きキャッシュのサイズ上限を設定するには、max_reverse_dictionary_lookup_cache_size_bytes を使用します。このキャッシュは、同じクエリ内で Dictionary を再スキャンする必要がないように、各属性値に対応するシリアライズ済みのキーのタプルを保存します。このキャッシュはクエリ間で永続化されません。上限に達すると、LRU によってエントリが削除されます。入力のカーディナリティが低く、ワーキングセットがキャッシュに収まるような大きな Dictionary に対して最も効果的です。キャッシュを無効にするには 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 は例外をスローします。

例

使用例

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

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

dictGetOrDefault

導入バージョン: v18.16

Dictionary から値を取得し、キーが見つからない場合はデフォルト値を返します。

構文

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

引数

dict_name — Dictionary の名前。String
attr_names — Dictionary のカラム名、またはカラム名のタプル。String または Tuple(String)
id_expr — キーの値。UInt64 または Tuple(T) を返す式です。UInt64 または Tuple(T)
default_value — キーが見つからない場合に返すデフォルト値。型は属性のデータ型と一致している必要があります。

戻り値

キーが見つかった場合、id_expr に対応する Dictionary 属性の値を返します。キーが見つからない場合は、指定された default_value を返します。

例

デフォルト値付きで値を取得

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

dictGetOrNull

導入バージョン: v21.4

Dictionary から値を取得し、キーが見つからない場合は NULL を返します。

構文

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

引数

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

戻り値

キーが見つかった場合は、id_expr に対応する Dictionary 属性値を返します。キーが見つからない場合は、NULL を返します。

例

レンジキーを使用する Dictionary の例

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

(0,'2019-05-20')  \N
(1,'2019-05-20')  最初
(2,'2019-05-20')  2番目
(3,'2019-05-20')  3番目
(4,'2019-05-20')  \N

dictGetString

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定にかかわらず String データ型に変換します。

構文

dictGetString(dict_name, attr_name, id_expr)

引数

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

戻り値

注記

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

例

使用例

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

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

dictGetStringOrDefault

導入: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく String 型に変換します。キーが見つからない場合は、指定されたデフォルト値を返します。

構文

dictGetStringOrDefault(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 は例外をスローします。

例

使用例

-- キーが存在する場合
SELECT dictGetString('all_types_dict', 'String_value', 1);

-- キーが存在しない場合、指定したデフォルト値を返す
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');

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

dictGetUInt16

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定内容に関係なく UInt16 型に変換します。

構文

dictGetUInt16(dict_name, attr_name, id_expr)

引数

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

戻り値

注記

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

例

使用例

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

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

dictGetUInt16OrDefault

導入バージョン: v1.1

Dictionary の設定に関係なく、Dictionary の属性値を UInt16 データ型に変換し、キーが見つからない場合は指定されたデフォルト値を返します。

構文

dictGetUInt16OrDefault(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 は例外を送出します。

例

使用例

-- 存在するキーの場合
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);

-- 存在しないキーの場合、指定したデフォルト値(0)を返す
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);

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

dictGetUInt32

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく UInt32 データ型に変換します。

構文

dictGetUInt32(dict_name, attr_name, id_expr)

引数

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

戻り値

id_expr に対応する Dictionary 属性の値を返し、それ以外の場合には、Dictionary の設定でその属性に対して指定された <null_value> 要素の内容を返します。

注記

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

例

使用例

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

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

dictGetUInt32OrDefault

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定内容に関係なく UInt32 型に変換し、キーが見つからない場合には指定されたデフォルト値を返します。

構文

dictGetUInt32OrDefault(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 は例外をスローします。

例

使用例

-- 存在するキーの場合
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);

-- 存在しないキーの場合、指定したデフォルト値(0)を返す
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);

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

dictGetUInt64

導入: v1.1

Dictionary の属性の値を、Dictionary の設定に関係なく UInt64 データ型に変換します。

構文

dictGetUInt64(dict_name, attr_name, id_expr)

引数

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

戻り値

id_expr に対応する Dictionary 属性の値を返します。対応する値が存在しない場合は、Dictionary の構成でその属性に対して指定されている <null_value> 要素の内容を返します。

注記

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

例

使用例

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

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

dictGetUInt64OrDefault

導入バージョン: v1.1

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 — キーの値。Dictionary のキー型の値またはタプル値を返す式（Dictionary の設定に依存）。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値

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

注記

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

例

使用例

-- キーが存在する場合
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);

-- キーが存在しない場合、指定されたデフォルト値 (0) を返す
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);

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

dictGetUInt8

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定内容に関係なく UInt8 データ型に変換します。

構文

dictGetUInt8(dict_name, attr_name, id_expr)

引数

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

戻り値

id_expr に対応する Dictionary 属性の値を返し、それ以外の場合には、Dictionary の設定で当該属性に対して指定された <null_value> 要素の内容を返します。

注記

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

例

使用例

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

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

dictGetUInt8OrDefault

導入バージョン: v1.1

Dictionary の属性値を、Dictionary の設定に関係なく 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 の設定に依存）。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値

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

注記

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

例

使用例

-- 存在するキーの場合
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);

-- 存在しないキーの場合は、指定したデフォルト値(0)を返す
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);

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

dictGetUUID

v1.1 で導入

Dictionary の設定に関係なく、Dictionary の属性値を UUID データ型に変換します。

構文

dictGetUUID(dict_name, attr_name, id_expr)

引数

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

戻り値

注記

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

例

使用例

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

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

dictGetUUIDOrDefault

導入バージョン: v1.1

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 のキー型の値、またはタプル値を返す式（Dictionary の設定に依存します）。Expression または Tuple(T)
default_value_expr — Dictionary に id_expr キーを持つ行が存在しない場合に返される値。Expression または Tuple(T)

戻り値

id_expr に対応する Dictionary 属性の値を返し、対応する値が存在しない場合は default_value_expr パラメータで指定された値を返します。

注記

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

例

使用例

-- キーが存在する場合
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);

-- キーが存在しない場合、指定したデフォルト値を返す
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);

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

dictHas

導入バージョン: v1.1

Dictionary にキーが存在するかどうかを確認します。

構文

dictHas('dict_name', id_expr)

引数

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

戻り値

キーが存在する場合は 1、存在しない場合は 0 を返します。UInt8

例

Dictionary 内でキーの存在を確認する

-- 以下の階層型Dictionaryを考えます:
-- 0 (ルート)
-- └── 1 (レベル1 - ノード1)
--     ├── 2 (レベル2 - ノード2)
--     │   ├── 4 (レベル3 - ノード4)
--     │   └── 5 (レベル3 - ノード5)
--     └── 3 (レベル2 - ノード3)
--         └── 6 (レベル3 - ノード6)

SELECT dictHas('hierarchical_dictionary', 2);
SELECT dictHas('hierarchical_dictionary', 7);

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

dictIsIn

導入バージョン: v1.1

Dictionary 内の階層チェーン全体を対象に、キーの先祖をチェックします。

構文

dictIsIn(dict_name, child_id_expr, ancestor_id_expr)

引数

dict_name — Dictionary の名前。String
child_id_expr — チェック対象のキー。String
ancestor_id_expr — キー child_id_expr の想定される祖先キー。const String

返り値

child_id_expr が ancestor_id_expr の子でない場合は 0 を返し、child_id_expr が ancestor_id_expr の子である場合、または child_id_expr が ancestor_id_expr と等しい場合は 1 を返します。UInt8

例

階層関係の確認

-- 有効な階層
SELECT dictIsIn('hierarchical_dictionary', 6, 3)

-- 無効な階層
SELECT dictIsIn('hierarchical_dictionary', 3, 5)

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

例となる辞書​

dictGet​

dictGetAll​

dictGetChildren​

dictGetDate​

dictGetDateOrDefault​

dictGetDateTime​

dictGetDateTimeOrDefault​

dictGetDescendants​

dictGetFloat32​

dictGetFloat32OrDefault​

dictGetFloat64​

dictGetFloat64OrDefault​

dictGetHierarchy​

dictGetIPv4​

dictGetIPv4OrDefault​

dictGetIPv6​

dictGetIPv6OrDefault​

dictGetInt16​

dictGetInt16OrDefault​

dictGetInt32​

dictGetInt32OrDefault​

dictGetInt64​

dictGetInt64OrDefault​

dictGetInt8​

dictGetInt8OrDefault​

dictGetKeys​

dictGetOrDefault​

dictGetOrNull​

dictGetString​

dictGetStringOrDefault​

dictGetUInt16​

dictGetUInt16OrDefault​

dictGetUInt32​

dictGetUInt32OrDefault​

dictGetUInt64​

dictGetUInt64OrDefault​

dictGetUInt8​

dictGetUInt8OrDefault​

dictGetUUID​

dictGetUUIDOrDefault​

dictHas​

dictIsIn​

例となる辞書

dictGet

dictGetAll

dictGetChildren

dictGetDate

dictGetDateOrDefault

dictGetDateTime

dictGetDateTimeOrDefault

dictGetDescendants

dictGetFloat32

dictGetFloat32OrDefault

dictGetFloat64

dictGetFloat64OrDefault

dictGetHierarchy

dictGetIPv4

dictGetIPv4OrDefault

dictGetIPv6

dictGetIPv6OrDefault

dictGetInt16

dictGetInt16OrDefault

dictGetInt32

dictGetInt32OrDefault

dictGetInt64

dictGetInt64OrDefault

dictGetInt8

dictGetInt8OrDefault

dictGetKeys

dictGetOrDefault

dictGetOrNull

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn