Dictionary レイアウト

Dictionary レイアウトの種類

Dictionary をメモリ内に格納する方法は複数あり、それぞれ CPU 使用量と RAM 使用量の間でトレードオフがあります。

レイアウト	説明
flat	キーで索引付けされたフラットな配列にデータを格納します。最も高速なレイアウトですが、キーは `UInt64` で、`max_array_size` 以内である必要があります。
hashed	ハッシュテーブルにデータを格納します。キーサイズに制限はなく、任意の数の要素をサポートします。
sparse_hashed	`hashed` と似ていますが、CPU 使用量と引き換えにメモリ使用量を抑えます。
complex_key_hashed	`hashed` と同様ですが、複合キーに対応します。
complex_key_sparse_hashed	`sparse_hashed` と同様ですが、複合キーに対応します。
hashed_array	キーを配列インデックスに対応付けるハッシュテーブルを使い、属性を配列に格納します。属性数が多い場合にメモリ効率に優れます。
complex_key_hashed_array	`hashed_array` と同様ですが、複合キーに対応します。
range_hashed	順序付けされた範囲を持つハッシュテーブルです。キー + 日付/時刻の範囲によるルックアップをサポートします。
complex_key_range_hashed	`range_hashed` と同様ですが、複合キーに対応します。
cache	固定サイズのインメモリ cache です。頻繁にアクセスされるキーだけを格納します。
complex_key_cache	`cache` と同様ですが、複合キーに対応します。
ssd_cache	`cache` と同様ですが、データは SSD に格納され、索引はメモリ内に保持されます。
complex_key_ssd_cache	`ssd_cache` と同様ですが、複合キーに対応します。
direct	メモリ内には格納せず、リクエストごとにソースへ直接クエリします。
complex_key_direct	`direct` と同様ですが、複合キーに対応します。
ip_trie	IP プレフィックスを高速にルックアップするための Trie 構造です (CIDR ベース) 。
hierarchical	親子関係を表す数値キーを使用した階層構造をサポートします。
polygon	効率的な point-in-polygon ルックアップ (逆ジオコーディング) を提供します。
regexp_tree	キーを正規表現のツリー構造に照合します。

推奨レイアウトflat、hashed、および complex_key_hashed は、最良のクエリパフォーマンスを提供します。キャッシュ系レイアウトは、パフォーマンスが低くなる可能性があり、パラメータ調整も難しいため推奨されません。詳細は cache を参照してください。

キャッシュ系レイアウトは、ウォームアップ済みのエントリが各サーバーのローカルにのみ保持され、サーバーの再起動時や置き換え時に失われるため、挿入時のエンリッチメントを確実に行う用途には適していません。ClickHouse Cloud では、オートスケーリングやマネージドなノード置き換えにより、この状況がより発生しやすくなります。代わりに、データを完全にロードするレイアウトを使用してください。詳細はインジェストパスにおける cache Dictionary を参照してください。

Dictionary のレイアウトを指定する

ClickHouse Cloud で Dictionary を使用している場合は、DDLクエリオプションを使用して Dictionary を作成し、default ユーザーとして作成してください。また、サポートされている Dictionary ソースの一覧は、Cloud Compatibility ガイドで確認してください。

Dictionary のレイアウトは、LAYOUT 句 (DDL の場合) または設定ファイル定義の layout 設定で指定できます。

DDL
設定ファイル

CREATE DICTIONARY (...)
...
LAYOUT(LAYOUT_TYPE(param value)) -- レイアウト設定
...

<clickhouse>
    <dictionary>
        ...
        <layout>
            <layout_type>
                <!-- レイアウト設定 -->
            </layout_type>
        </layout>
        ...
    </dictionary>
</clickhouse>

完全な DDL 構文については、CREATE DICTIONARY も参照してください。レイアウト名に complex-key* を含まない Dictionary は UInt64 型のキーを持ち、complex-key* Dictionary は複合キー (複雑で、任意の型を持つキー) を持ちます。 数値キーの例 (カラム key_column は UInt64 型) :

DDL
設定ファイル

CREATE DICTIONARY dict_name (
    key_column UInt64,
    ...
)
PRIMARY KEY key_column

<structure>
    <id>
        <name>key_column</name>
    </id>
    ...
</structure>

複合キーの例 (キーは String 型の要素を 1 つ持ちます) :

DDL
設定ファイル

CREATE DICTIONARY dict_name (
    country_code String,
    ...
)
PRIMARY KEY country_code

<structure>
    <key>
        <attribute>
            <name>country_code</name>
            <type>String</type>
        </attribute>
    </key>
    ...
</structure>

Dictionary のパフォーマンスを向上させる

Dictionary のパフォーマンスを向上させる方法はいくつかあります。

GROUP BY の後で、Dictionary を使用する関数を呼び出します。
取得する属性を injective としてマークします。異なるキーに異なる属性値が対応する場合、その属性は injective と呼ばれます。そのため、GROUP BY でキーから属性値を取得する関数を使用している場合、この関数は自動的に GROUP BY から除外されます。

ClickHouse は Dictionary に関するエラーに対して例外を生成します。エラーの例としては、次のようなものがあります。

アクセスしている Dictionary を読み込めない。
cached Dictionary のクエリ時のエラー。

Dictionary の一覧とそのステータスは、system.dictionaries テーブルで確認できます。

SQLリファレンス

データ型

エンジン

関数

フォーマット

設定

システムテーブル

データレイク