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

> Этот движок позволяет использовать кластер Keeper/ZooKeeper как согласованное хранилище ключ-значение с линеаризуемыми записями и последовательно согласованными чтениями.

# Движок таблицы KeeperMap

Этот движок позволяет использовать кластер Keeper/ZooKeeper как согласованное хранилище ключ-значение с линеаризуемыми записями и последовательно согласованными чтениями.

Чтобы включить движок таблицы KeeperMap, нужно указать путь в ZooKeeper, где будут храниться таблицы, с помощью конфига `<keeper_map_path_prefix>`.

Например:

```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` — путь в ZooKeeper, где будет храниться `table_name`.
  Этот путь не должен содержать префикс, заданный в конфиге `<keeper_map_path_prefix>`, поскольку префикс будет автоматически добавлен к `root_path`.
  Также поддерживается формат `auxiliary_zookeeper_cluster_name:/some/path`, где `auxiliary_zookeeper_cluster` — это кластер ZooKeeper, определённый в конфиге `<auxiliary_zookeepers>`.
  По умолчанию используется кластер ZooKeeper, заданный в конфиге `<zookeeper>`.
* `keys_limit` — количество ключей, допустимое в table.
  Это мягкое ограничение, и в некоторых пограничных случаях в table может оказаться больше ключей.
* `primary_key_name` – любое имя столбца в списке столбцов.
* `первичный ключ` должен быть указан; поддерживается только один столбец в первичном ключе. Первичный ключ будет сериализован в бинарный формат как `node name` внутри ZooKeeper.
* столбцы, кроме первичного ключа, будут сериализованы в бинарный формат в соответствующем порядке и сохранены как value результирующего узла, определённого сериализованным key.
* queries с фильтрацией по key через `equals` или `in` будут оптимизированы в lookup нескольких ключей из `Keeper`, в противном случае будут получены все values.

Пример:

```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
```

с

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

Каждое значение, представляющее собой бинарную сериализацию `(v1, v2, v3)`, будет храниться по пути `/keeper_map_tables/keeper_map_table/data/serialized_key` в `Keeper`.
Кроме того, для числа ключей действует нестрогий лимит: 4.

Если несколько таблиц создаются по одному и тому же пути ZooKeeper, значения сохраняются, пока существует хотя бы 1 таблица, использующая этот путь.
В результате при создании таблицы можно использовать предложение `ON CLUSTER` и организовать общий доступ к данным между несколькими экземплярами ClickHouse.
Разумеется, можно и вручную выполнить `CREATE TABLE` с тем же путем на не связанных между собой экземплярах ClickHouse, чтобы добиться того же эффекта общего доступа к данным.

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

* Блог: [Создание приложений для Real-time аналитики с ClickHouse и Hex](https://clickhouse.com/blog/building-real-time-applications-with-clickhouse-and-hex-notebook-keeper-engine)