Map(K, V)

El tipo de dato Map(K, V) almacena pares clave-valor.

A diferencia de otras bases de datos, los valores de tipo Map no tienen claves únicas en ClickHouse; es decir, un Map puede contener dos elementos con la misma clave. (Esto se debe a que los Map se implementan internamente como Array(Tuple(K, V)).)

Puede usar la sintaxis m[k] para obtener el valor de la clave k en el Map m. Además, m[k] recorre el Map; es decir, el tiempo de ejecución de la operación es lineal con respecto al tamaño del Map.

Parámetros

• K — El tipo de las claves del Map. Cualquier tipo, excepto Nullable y LowCardinality anidado con tipos Nullable.
• V — El tipo de los valores del Map. Cualquier tipo.

Ejemplos

Cree una tabla con una columna de tipo Map:

CREATE TABLE tab (m Map(String, UInt64)) ENGINE=Memory;
INSERT INTO tab VALUES ({'key1':1, 'key2':10}), ({'key1':2,'key2':20}), ({'key1':3,'key2':30});

Para seleccionar los valores de key2:

SELECT m['key2'] FROM tab;

┌─arrayElement(m, 'key2')─┐
│                      10 │
│                      20 │
│                      30 │
└─────────────────────────┘

Si la clave solicitada k no está en el mapa, m[k] devuelve el valor por defecto del tipo de valor; por ejemplo, 0 para los tipos enteros y '' para los tipos de cadena. Para comprobar si existe una clave en un mapa, puede usar la función mapContains.

CREATE TABLE tab (m Map(String, UInt64)) ENGINE=Memory;
INSERT INTO tab VALUES ({'key1':100}), ({});
SELECT m['key1'] FROM tab;

┌─arrayElement(m, 'key1')─┐
│                     100 │
│                       0 │
└─────────────────────────┘

Los valores de tipo Tuple() pueden convertirse en valores de tipo Map() mediante la función CAST:

Ejemplo

SELECT CAST(([1, 2, 3], ['Ready', 'Steady', 'Go']), 'Map(UInt8, String)') AS map;

┌─map───────────────────────────┐
│ {1:'Ready',2:'Steady',3:'Go'} │
└───────────────────────────────┘

Para evitar leer el Map completo, puede usar las subcolumnas keys y values en algunos casos.

Ejemplo

CREATE TABLE tab (m Map(String, UInt64)) ENGINE = Memory;
INSERT INTO tab VALUES (map('key1', 1, 'key2', 2, 'key3', 3));

SELECT m.keys FROM tab; --   igual que mapKeys(m)
SELECT m.values FROM tab; -- igual que mapValues(m)

┌─m.keys─────────────────┐
│ ['key1','key2','key3'] │
└────────────────────────┘

┌─m.values─┐
│ [1,2,3]  │
└──────────┘

De forma predeterminada, una columna Map en MergeTree se almacena como un único flujo Array(Tuple(K, V)). Leer una sola clave con m['key'] requiere escanear toda la columna —todos los pares clave-valor de cada fila—, incluso si solo se necesita una clave. En los Map con muchas claves distintas, esto se convierte en un cuello de botella.

La serialización en buckets (with_buckets) divide los pares clave-valor en varios subflujos independientes (buckets) aplicando un hash a la clave. Cuando una consulta accede a m['key'], solo se lee del disco el bucket que contiene esa clave, omitiendo todos los demás buckets.

CREATE TABLE tab (id UInt64, m Map(String, UInt64))
ENGINE = MergeTree ORDER BY id
SETTINGS
    map_serialization_version = 'with_buckets',
    max_buckets_in_map = 32,
    map_buckets_strategy = 'sqrt';

Para no ralentizar las inserciones, puedes mantener la serialización basic para las partes de nivel cero (creadas durante INSERT) y usar with_buckets solo para las partes fusionadas:

CREATE TABLE tab (id UInt64, m Map(String, UInt64))
ENGINE = MergeTree ORDER BY id
SETTINGS
    map_serialization_version = 'with_buckets',
    map_serialization_version_for_zero_level_parts = 'basic',
    max_buckets_in_map = 32,
    map_buckets_strategy = 'sqrt';

Cuando una parte de datos se escribe con la serialización with_buckets:

1. El número medio de claves por fila se calcula a partir de las estadísticas del bloque.
2. El número de buckets se determina según la estrategia configurada (consulta Configuración).
3. Cada par clave-valor se asigna a un bucket aplicando un hash a la clave: bucket = hash(key) % num_buckets.
4. Cada bucket se almacena como un subflujo independiente con sus propias claves, valores y offsets.
5. Un flujo de metadatos buckets_info registra el número de buckets y sus estadísticas.

Cuando una consulta lee una clave específica (m['key']), el optimizador reescribe la expresión como una subcolumna de clave (m.key_<serialized_key>). La capa de serialización calcula a qué bucket pertenece la clave solicitada y lee solo ese bucket desde el disco.

Cuando se lee el mapa completo (por ejemplo, SELECT m), se leen todos los buckets y se reconstruye el mapa original. Esto es más lento que la serialización basic debido a la sobrecarga de leer y fusionar varios subflujos.

El número de buckets puede variar entre partes. Cuando se fusionan partes con distintos números de buckets, el número de buckets de la nueva parte se vuelve a calcular a partir de las estadísticas fusionadas. Las partes con serialización basic y with_buckets pueden coexistir en la misma tabla y se fusionan de forma transparente.

La siguiente tabla resume el impacto en el rendimiento de with_buckets frente a la serialización basic con distintos tamaños de Map (de 10 a 10.000 claves por fila). El número de buckets se determinó mediante la estrategia sqrt, con un máximo de 32. Los valores exactos dependen de los tipos de clave/valor, la distribución de los datos y el hardware.

• Mapas pequeños (< 32 claves de media): Mantén la serialización basic. La sobrecarga de usar buckets no se justifica en mapas pequeños. El valor predeterminado map_buckets_min_avg_size = 32 lo aplica automáticamente.
• Mapas medianos (32–100 claves): Usa with_buckets con la estrategia sqrt si las consultas acceden con frecuencia a claves individuales. La mejora de velocidad es de 4–8x en búsquedas de una sola clave.
• Mapas grandes (100+ claves): Usa with_buckets. Las búsquedas de una sola clave son entre 16 y 49 veces más rápidas. Considera map_serialization_version_for_zero_level_parts = 'basic' para mantener la velocidad de insert cerca del valor de referencia.
• Los escaneos completos del mapa dominan la carga de trabajo: Mantén basic. La serialización con buckets añade una sobrecarga de ~2x en los escaneos completos.
• Carga de trabajo mixta (algunas búsquedas de claves y algunos escaneos completos): Usa with_buckets con las partes de nivel cero configuradas en basic. La optimización PREWHERE lee solo el bucket relevante para el filtro y luego lee el mapa completo únicamente para las filas coincidentes, lo que aporta una mejora neta significativa.

Si la serialización de Map en buckets no se adapta a tu caso de uso, hay dos enfoques alternativos para mejorar el rendimiento del acceso por clave:

El tipo de datos JSON almacena cada ruta frecuente como una subcolumna dinámica independiente. Las rutas que superan el límite de max_dynamic_paths pasan a una estructura de datos compartida, que puede usar la serialización advanced para optimizar las lecturas de una sola ruta. Consulta la entrada del blog para obtener una descripción detallada de la serialización advanced.

Usa JSON cuando distintas claves necesiten distintos tipos de valor, cuando el conjunto de claves varíe significativamente entre filas o cuando las claves a las que se accede con frecuencia se conozcan de antemano y puedan declararse como rutas tipadas para acceder directamente a las subcolumnas.

Puede dividir manualmente un único Map en varias columnas según el hash de la clave a nivel de la aplicación:

CREATE TABLE tab (
    id UInt64,
    m0 Map(String, UInt64),
    m1 Map(String, UInt64),
    m2 Map(String, UInt64),
    m3 Map(String, UInt64)
) ENGINE = MergeTree ORDER BY id;

Durante la inserción, dirija cada par clave-valor a la columna m{hash(key) % 4}. Durante las consultas, lea de la columna específica: m{hash('target_key') % 4}['target_key'].

La segmentación manual resulta útil cuando las fusiones verticales son importantes para reducir el uso de memoria durante las fusiones de tablas con muchas columnas, o cuando el número de segmentos debe permanecer fijo y controlarse explícitamente. Para la mayoría de los casos de uso, la serialización automática en buckets es más sencilla y suficiente.

Véase también

• función map()
• función CAST()
• combinador -Map para el tipo de dato Map

• Blog: Cómo crear una solución de observabilidad con ClickHouse - Parte 2 - Trazas