Этот движок позволяет использовать кластер Keeper/ZooKeeper как согласованное хранилище ключ-значение с линеаризуемыми записями и последовательно согласованными чтениями.
Чтобы включить движок таблицы KeeperMap, нужно указать путь в ZooKeeper, где будут храниться таблицы, с помощью конфига <keeper_map_path_prefix>.
Например:
<clickhouse>
<keeper_map_path_prefix>/keeper_map_tables</keeper_map_path_prefix>
</clickhouse>
path может быть любым другим допустимым путём в ZooKeeper.
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.
Пример:
CREATE TABLE keeper_map_table
(
`key` String,
`v1` UInt32,
`v2` String,
`v3` Float32
)
ENGINE = KeeperMap('/keeper_map_table', 4)
PRIMARY KEY key
<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, чтобы добиться того же эффекта общего доступа к данным.
При вставке новых строк в KeeperMap, если ключ отсутствует, для него создаётся новая запись.
Если ключ уже существует и параметр keeper_map_strict_mode установлен в значение true, генерируется исключение; в противном случае значение по этому ключу перезаписывается.
Пример:
INSERT INTO keeper_map_table VALUES ('some key', 1, 'value', 3.2);
DELETE или команды TRUNCATE.
Если ключ существует и параметр keeper_map_strict_mode установлен в true, получение и удаление данных будут выполняться успешно только в том случае, если их можно выполнить атомарно.
DELETE FROM keeper_map_table WHERE key LIKE 'some%' AND v1 > 1;
ALTER TABLE keeper_map_table DELETE WHERE key LIKE 'some%' AND v1 > 1;
TRUNCATE TABLE keeper_map_table;
ALTER TABLE. Первичный ключ обновить нельзя.
Если параметр keeper_map_strict_mode имеет значение true, получение и обновление данных будут выполняться успешно только атомарно.
ALTER TABLE keeper_map_table UPDATE v1 = v1 * 10 + 2 WHERE key LIKE 'some%' AND v3 > 3.1;
Последнее изменение 10 июня 2026 г.
