> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Dictionary をメモリに格納するためのレイアウトタイプ

# Dictionary レイアウト

<div id="storing-dictionaries-in-memory">
  ## Dictionary レイアウトの種類
</div>

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

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

<Tip>
  **推奨レイアウト**

  [flat](/ja/reference/statements/create/dictionary/layouts/flat)、[hashed](/ja/reference/statements/create/dictionary/layouts/hashed)、および [complex\_key\_hashed](/ja/reference/statements/create/dictionary/layouts/hashed#complex_key_hashed) は、最良のクエリパフォーマンスを提供します。
  キャッシュ系レイアウトは、パフォーマンスが低くなる可能性があり、パラメータ調整も難しいため推奨されません。詳細は [cache](/ja/reference/statements/create/dictionary/layouts/cache) を参照してください。
</Tip>

<div id="specify-dictionary-layout">
  ## Dictionary のレイアウトを指定する
</div>

<Tip>
  ClickHouse Cloud で Dictionary を使用している場合は、DDLクエリオプションを使用して Dictionary を作成し、`default` ユーザーとして作成してください。
  また、サポートされている Dictionary ソースの一覧は、[Cloud Compatibility ガイド](/ja/products/cloud/guides/cloud-compatibility)で確認してください。
</Tip>

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

<Tabs>
  <Tab title="DDL">
    ```sql theme={null}
    CREATE DICTIONARY (...)
    ...
    LAYOUT(LAYOUT_TYPE(param value)) -- レイアウト設定
    ...
    ```
  </Tab>

  <Tab title="設定ファイル">
    ```xml theme={null}
    <clickhouse>
        <dictionary>
            ...
            <layout>
                <layout_type>
                    <!-- レイアウト設定 -->
                </layout_type>
            </layout>
            ...
        </dictionary>
    </clickhouse>
    ```
  </Tab>
</Tabs>

<br />

完全な DDL 構文については、[CREATE DICTIONARY](/ja/reference/statements/create/dictionary) も参照してください。

レイアウト名に `complex-key*` を含まない Dictionary は [UInt64](/ja/reference/data-types/int-uint) 型のキーを持ち、`complex-key*` Dictionary は複合キー (複雑で、任意の型を持つキー) を持ちます。

**数値キーの例** (カラム `key_column` は [UInt64](/ja/reference/data-types/int-uint) 型) :

<Tabs>
  <Tab title="DDL">
    ```sql theme={null}
    CREATE DICTIONARY dict_name (
        key_column UInt64,
        ...
    )
    PRIMARY KEY key_column
    ```
  </Tab>

  <Tab title="設定ファイル">
    ```xml theme={null}
    <structure>
        <id>
            <name>key_column</name>
        </id>
        ...
    </structure>
    ```
  </Tab>
</Tabs>

<br />

**複合キーの例** (キーは [String](/ja/reference/data-types/string) 型の要素を 1 つ持ちます) :

<Tabs>
  <Tab title="DDL">
    ```sql theme={null}
    CREATE DICTIONARY dict_name (
        country_code String,
        ...
    )
    PRIMARY KEY country_code
    ```
  </Tab>

  <Tab title="設定ファイル">
    ```xml theme={null}
    <structure>
        <key>
            <attribute>
                <name>country_code</name>
                <type>String</type>
            </attribute>
        </key>
        ...
    </structure>
    ```
  </Tab>
</Tabs>

<div id="improve-performance">
  ## Dictionary のパフォーマンスを向上させる
</div>

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

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

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

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

Dictionary の一覧とそのステータスは、[system.dictionaries](/ja/reference/system-tables/dictionaries) テーブルで確認できます。