Los índices hipotéticos son índices de omisión virtuales limitados al ámbito de la sesión que puedes asociar a una tabla de la familia MergeTree sin llegar a construirlos ni almacenarlos. Solo existen dentro de la sesión actual y EXPLAIN WHATIF los usa para estimar cómo afectaría un índice de omisión real a una consulta, normalmente la tasa de omisión (la fracción de marcas que podrían omitirse) y un costo aproximado en marcas y bytes.
Usa índices hipotéticos para evaluar posibles índices antes de asumir el costo de materializarlos en disco.
CREATE HYPOTHETICAL INDEX
ALTER TABLE ... ADD INDEX, pero no se crea ni se escribe ningún índice; solo se almacena la descripción del índice en la sesión actual.
name — nombre del índice; debe ser único dentro de (database, table) para esta sesión.expression — la columna o expresión que se va a indexar.TYPE type — minmax, set(N), bloom_filter(p), ngrambf_v1(...), tokenbf_v1(...). text y vector_similarity no son compatibles y se rechazan al ejecutar CREATE, porque la validación real de ALTER TABLE ... ADD INDEX depende de configuraciones a nivel de tabla que el almacenamiento limitado a la sesión no puede reproducir.GRANULARITY value — número de gránulos de datos por gránulo de índice. El valor predeterminado es 1.
La tabla de destino debe ser una tabla de la familia MergeTree en una base de datos Atomic (debe tener un UUID). Las tablas sin UUID —por ejemplo, en una base de datos Ordinary heredada o un MergeTree con sintaxis antigua— se rechazan, porque el almacenamiento de sesión identifica los índices hipotéticos mediante el UUID de la tabla.
Ejemplo
Evaluar un índice hipotético con EXPLAIN WHATIF
EXPLAIN WHATIF sobre un SELECT representativo. El estimador informa de la aplicabilidad de cada índice candidato, las marcas que leería, la tasa de omisión resultante y cómo se produjo la estimación (empirical, statistical o applicability_only).
Resultado:
est_bytes es una estimación basada en el tamaño medio de las filas de la tabla, por lo que la cifra exacta varía según el almacenamiento y la compresión.
Para omitir el escaneo empírico en memoria y estimar a partir de las estadísticas de columnas, primero defínelas en las columnas pertinentes (están desactivadas de forma predeterminada), espera a que termine la mutación de materialización y, a continuación, desactiva la ruta empírica:
Consulte la referencia de EXPLAIN WHATIF para ver el esquema de salida completo y las opciones de configuración.
Elimina un índice hipotético de la sesión actual.
DROP ALL HYPOTHETICAL INDEXES
- Los índices hipotéticos existen solo en la sesión actual; no son visibles para otras sesiones y se descartan cuando la sesión termina.
- Definir o eliminar uno no crea ningún índice ni afecta nunca a las consultas normales sobre la tabla. La variante empírica de
EXPLAIN WHATIF sí lee datos de la tabla para construir el índice candidato en memoria, y ese escaneo cuenta para los límites de lectura y las cuotas de la sesión.
- Inspeccione los índices hipotéticos de la sesión actual mediante
system.hypothetical_indexes.
Los candidatos text y vector_similarity se rechazan en el momento de CREATE HYPOTHETICAL INDEX, porque su validación real depende de ajustes a nivel de tabla que el almacén limitado a la sesión no puede replicar.
EXPLAIN WHATIF muestra status: not_applicable para consultas con FINAL (la poda del índice de omisión interactúa con PrimaryKeyExpand) y devuelve NOT_IMPLEMENTED cuando la consulta se sirve desde una proyección (un índice de la tabla padre no se materializa en las partes de proyección).
El skip_ratio empírico es una cota superior: cuenta cada gránulo que sobrevive de forma independiente y no modela la coalescencia de huecos de seek (merge_tree_min_rows_for_seek / merge_tree_min_bytes_for_seek), ni la combinación de un candidato con un índice de omisión existente bajo un predicado disyuntivo (OR). Por lo tanto, un índice materializado real puede leer algo más, o podar en casos en los que la estimación no lo hace.
CREATE HYPOTHETICAL INDEX requiere SELECT sobre las columnas a las que hace referencia la expresión del índice — SELECT a nivel de columna (por ejemplo, GRANT SELECT(b)) es suficiente — porque el EXPLAIN WHATIF empírico lee esas columnas.
DROP HYPOTHETICAL INDEX y DROP ALL HYPOTHETICAL INDEXES no requieren ningún privilegio adicional; solo eliminan registros del almacenamiento local de la sesión.
Última modificación el 23 de julio de 2026
