Este motor le permite usar un clúster de Keeper/ZooKeeper como almacén de clave-valor consistente, con escrituras linealizables y lecturas con consistencia secuencial.
Para habilitar el motor de almacenamiento KeeperMap, debe definir una ruta en ZooKeeper donde se almacenarán las tablas mediante la configuración <keeper_map_path_prefix>.
Por ejemplo:
<clickhouse>
<keeper_map_path_prefix>/keeper_map_tables</keeper_map_path_prefix>
</clickhouse>
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 - ruta de ZooKeeper donde se almacenará table_name.
Esta ruta no debe contener el prefijo definido en la configuración <keeper_map_path_prefix>, porque el prefijo se añadirá automáticamente a root_path.
Además, también se admite el formato auxiliary_zookeeper_cluster_name:/some/path, donde auxiliary_zookeeper_cluster es un clúster de ZooKeeper definido dentro de la configuración <auxiliary_zookeepers>.
De forma predeterminada, se usa el clúster de ZooKeeper definido dentro de la configuración <zookeeper>.keys_limit - número de claves permitidas dentro de la tabla.
Este es un límite no estricto, por lo que en algunos casos extremos es posible que la tabla acabe conteniendo más claves.primary_key_name – cualquier nombre de columna de la lista de columnas.- se debe especificar
primary key; solo admite una columna en la clave primaria. La clave primaria se serializará en binario como un node name dentro de ZooKeeper.
- las columnas distintas de la clave primaria se serializarán en binario en el orden correspondiente y se almacenarán como el valor del nodo resultante definido por la clave serializada.
- las consultas con filtrado por clave
equals o in se optimizarán para realizar búsquedas de varias claves desde Keeper; en caso contrario, se recuperarán todos los valores.
Ejemplo:
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), se almacenará en /keeper_map_tables/keeper_map_table/data/serialized_key en Keeper.
Además, la cantidad de claves tendrá un límite suave de 4.
Si se crean varias tablas en la misma ruta de ZooKeeper, los valores se mantienen hasta que exista al menos 1 tabla que la utilice.
Como resultado, es posible usar la cláusula ON CLUSTER al crear la tabla y compartir los datos entre varias instancias de ClickHouse.
Por supuesto, es posible ejecutar manualmente CREATE TABLE con la misma ruta en instancias de ClickHouse no relacionadas para lograr el mismo efecto de compartir datos.
Cuando se insertan nuevas filas en KeeperMap, si la clave no existe, se crea una nueva entrada para esa clave.
Si la clave existe y la configuración keeper_map_strict_mode está establecida en true, se lanza una excepción; de lo contrario, se sobrescribe el valor de la clave.
Ejemplo:
INSERT INTO keeper_map_table VALUES ('some key', 1, 'value', 3.2);
DELETE o con TRUNCATE.
Si la clave existe y la configuración keeper_map_strict_mode está establecida en true, la recuperación y eliminación de datos solo tendrán éxito si pueden ejecutarse de forma atómica.
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. La clave primaria no se puede actualizar.
Si keeper_map_strict_mode está establecido en true, la obtención y actualización de datos solo se realizarán correctamente si se ejecutan de forma atómica.
ALTER TABLE keeper_map_table UPDATE v1 = v1 * 10 + 2 WHERE key LIKE 'some%' AND v3 > 3.1;
Última modificación el 10 de junio de 2026
