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

> このエンジンを使用すると、Keeper/ZooKeeper クラスターを、線形化可能な書き込みと 逐次一貫性のある読み取りを備えた整合性のあるキー・バリュー ストアとして利用できます。

# KeeperMap テーブルエンジン

このエンジンを使用すると、Keeper/ZooKeeper クラスターを、線形化可能な書き込みと逐次一貫性のある読み取りを備えた整合性のあるキー・バリュー ストアとして利用できます。

KeeperMap ストレージエンジンを有効にするには、`<keeper_map_path_prefix>` 設定を使用して、テーブルの保存先となる ZooKeeper パスを定義する必要があります。

例:

```xml theme={null}
<clickhouse>
    <keeper_map_path_prefix>/keeper_map_tables</keeper_map_path_prefix>
</clickhouse>
```

ここで、path には、有効な別の ZooKeeper パスを指定できます。

<div id="creating-a-table">
  ## テーブルの作成
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2],
    ...
) ENGINE = KeeperMap(root_path, [keys_limit]) PRIMARY KEY(primary_key_name)
```

エンジンパラメータ:

* `root_path` - `table_name` が格納される ZooKeeper パス。
  プレフィックスは `root_path` に自動的に付加されるため、このパスには `<keeper_map_path_prefix>` config で定義されたプレフィックスを含めないでください。
  また、`auxiliary_zookeeper_cluster_name:/some/path` 形式もサポートされています。ここで `auxiliary_zookeeper_cluster` は `<auxiliary_zookeepers>` config 内で定義された ZooKeeper クラスターです。
  デフォルトでは、`<zookeeper>` config 内で定義された ZooKeeper クラスターが使用されます。
* `keys_limit` - テーブル内で許可されるキーの数。
  この制限はソフトリミットであるため、エッジケースによってはテーブル内のキー数がこれを超える場合があります。
* `primary_key_name` – カラム一覧内の任意のカラム名。
* `primary key` の指定は必須で、主キーとして指定できるのは 1 つのカラムのみです。主キーは ZooKeeper 内で `node name` としてバイナリ形式にシリアライズされます。
* 主キー以外のカラムは、対応する順序でバイナリ形式にシリアライズされ、シリアライズされたキーによって定義されるノードの値として保存されます。
* キーに対する `equals` または `in` フィルタリングを含むクエリは、`Keeper` からの複数キーのルックアップに最適化されます。それ以外の場合は、すべての値が取得されます。

例:

```sql theme={null}
CREATE TABLE keeper_map_table
(
    `key` String,
    `v1` UInt32,
    `v2` String,
    `v3` Float32
)
ENGINE = KeeperMap('/keeper_map_table', 4)
PRIMARY KEY key
```

with

```xml theme={null}
<clickhouse>
    <keeper_map_path_prefix>/keeper_map_tables</keeper_map_path_prefix>
</clickhouse>
```

各値は `(v1, v2, v3)` をバイナリシリアライズしたもので、`Keeper` 内の `/keeper_map_tables/keeper_map_table/data/serialized_key` に格納されます。
さらに、キー数のソフトリミットは 4 です。

同じ ZooKeeper パス上に複数のテーブルが作成された場合、それを使用するテーブルが 1 つでも存在する限り、値は保持されます。
そのため、テーブルの作成時に `ON CLUSTER` 句を使用して、複数の ClickHouse インスタンスからデータを共有できます。
もちろん、関連のない ClickHouse インスタンスで同じパスを指定して `CREATE TABLE` を手動で実行し、同様のデータ共有効果を得ることもできます。

<div id="supported-operations">
  ## 対応している操作
</div>

<div id="inserts">
  ### 挿入
</div>

新しい行を`KeeperMap`に挿入する際、キーが存在しない場合は、そのキーに対応する新しいエントリが作成されます。
キーが存在し、設定`keeper_map_strict_mode`が`true`の場合は例外がスローされ、それ以外の場合はそのキーの値が上書きされます。

例:

```sql theme={null}
INSERT INTO keeper_map_table VALUES ('some key', 1, 'value', 3.2);
```

<div id="deletes">
  ### 削除
</div>

行は、`DELETE` クエリまたは `TRUNCATE` を使用して削除できます。
キーが存在し、かつ設定 `keeper_map_strict_mode` が `true` に設定されている場合、データのフェッチと削除は、アトミックに実行できる場合にのみ成功します。

```sql theme={null}
DELETE FROM keeper_map_table WHERE key LIKE 'some%' AND v1 > 1;
```

```sql theme={null}
ALTER TABLE keeper_map_table DELETE WHERE key LIKE 'some%' AND v1 > 1;
```

```sql theme={null}
TRUNCATE TABLE keeper_map_table;
```

<div id="updates">
  ### 更新
</div>

`ALTER TABLE` クエリを使用して値を更新できます。主キーは更新できません。
設定 `keeper_map_strict_mode` が `true` の場合、データの取得と更新はアトミックに実行された場合にのみ成功します。

```sql theme={null}
ALTER TABLE keeper_map_table UPDATE v1 = v1 * 10 + 2 WHERE key LIKE 'some%' AND v3 > 3.1;
```

<div id="related-content">
  ## 関連コンテンツ
</div>

* ブログ: [ClickHouse と Hex を使ったリアルタイム分析アプリの構築](https://clickhouse.com/blog/building-real-time-applications-with-clickhouse-and-hex-notebook-keeper-engine)