Índices hipotéticos são skip indexes virtuais, com escopo de sessão, que você pode anexar a uma tabela da família MergeTree sem de fato criá-los nem armazená-los. Eles existem apenas na sessão atual e são usados por EXPLAIN WHATIF para estimar como um skip index real afetaria uma consulta — normalmente, a taxa de descarte (fração de marcas que poderiam ser ignoradas) e um custo aproximado em marcas e bytes.
Use índices hipotéticos para avaliar possíveis índices antes de arcar com o custo de materializá-los em disco.
CREATE HYPOTHETICAL INDEX
ALTER TABLE ... ADD INDEX, mas nenhum índice é criado nem gravado — apenas a descrição do índice é armazenada na sessão atual.
name — nome do índice; deve ser exclusivo em (database, table) nesta sessão.expression — a coluna ou expressão a ser indexada.TYPE type — minmax, set(N), bloom_filter(p), ngrambf_v1(...), tokenbf_v1(...). text e vector_similarity não têm suporte e são rejeitados no momento do CREATE, porque a validação real de ALTER TABLE ... ADD INDEX depende de configurações no nível da tabela que o armazenamento restrito à sessão não consegue replicar.GRANULARITY value — número de grânulos de dados por grânulo de índice. O padrão é 1.
A tabela de destino deve ser uma tabela da família MergeTree em um banco de dados Atomic (ela deve ter um UUID). Tabelas sem UUID — por exemplo, em um banco de dados Ordinary legado ou em MergeTree com sintaxe antiga — são rejeitadas, porque o armazenamento da sessão usa o UUID da tabela como chave para os índices hipotéticos.
Exemplo
Definir um índice hipotético, por si só, não faz nada — para ver como ele afetaria uma consulta, execute EXPLAIN WHATIF em um SELECT representativo. O estimador informa a aplicabilidade de cada índice candidato, as marcas que ele leria, a taxa de descarte resultante e como a estimativa foi produzida (empirical, statistical ou applicability_only).
Resultado:
est_bytes é uma estimativa baseada no tamanho médio das linhas da tabela, portanto o valor exato varia conforme o armazenamento e a compressão.
Para pular a varredura empírica na memória e estimar com base nas estatísticas da coluna, primeiro defina-as nas colunas relevantes (elas ficam desativadas por padrão), aguarde a conclusão da mutação de materialização e, em seguida, desative a abordagem empírica:
Consulte a referência do EXPLAIN WHATIF para ver o esquema de saída completo e as configurações.
Remove um índice hipotético da sessão atual.
DROP ALL HYPOTHETICAL INDEXES
- Índices hipotéticos existem apenas na sessão atual — são invisíveis para outras sessões e são descartados quando a sessão termina.
- Definir ou remover um deles não cria nenhum índice nem afeta consultas comuns sobre a tabela. O
EXPLAIN WHATIF, quando executado de forma empírica, lê dados da tabela para criar o índice candidato em memória, e essa varredura conta para os limites de leitura e as quotas da sessão.
- Inspecione os índices hipotéticos da sessão atual por meio de
system.hypothetical_indexes.
Os candidatos text e vector_similarity são rejeitados no momento de CREATE HYPOTHETICAL INDEX, porque a validação real deles depende de configurações no nível da tabela que o armazenamento restrito à sessão não consegue replicar.
EXPLAIN WHATIF informa status: not_applicable para consultas com FINAL (a poda por skip index interage com PrimaryKeyExpand) e retorna NOT_IMPLEMENTED quando a consulta é atendida por uma projeção (um índice da tabela pai não é materializado nas partes da projeção).
O skip_ratio empírico é um limite superior: ele contabiliza cada grânulo sobrevivente de forma independente e não modela a coalescência de lacunas de busca (merge_tree_min_rows_for_seek / merge_tree_min_bytes_for_seek), nem a combinação de um candidato com um skip index existente sob um predicado disjuntivo (OR). Portanto, um índice materializado real pode ler um pouco mais ou fazer poda em casos em que a estimativa não faz isso.
CREATE HYPOTHETICAL INDEX requer SELECT nas colunas referenciadas pela expressão do índice — SELECT em nível de coluna (por exemplo, GRANT SELECT(b)) é suficiente — porque o EXPLAIN WHATIF, em modo empírico, lê essas colunas.
DROP HYPOTHETICAL INDEX e DROP ALL HYPOTHETICAL INDEXES não exigem privilégios adicionais; apenas removem entradas do armazenamento local da sessão.
Última modificação em 23 de julho de 2026
