Projeções hipotéticas são projeções virtuais, com escopo de sessão, que você pode anexar a uma tabela da família MergeTree sem de fato construí-las ou armazená-las. Elas existem apenas dentro da sessão atual e são listadas pelo EXPLAIN WHATIF.
O EXPLAIN WHATIF ainda não estima o benefício de uma projeção hipotética — ele informa cada uma com status: not_applicable. Defini-las é útil hoje para validar uma definição em relação à tabela sem materializá-la e para ferramentas que leem a system.hypothetical_projections.
CREATE HYPOTHETICAL PROJECTION
A sintaxe espelha ALTER TABLE ... ADD PROJECTION, e a definição é validada exatamente da mesma forma, de modo que uma projeção rejeitada aqui também não poderia ter sido materializada. Nada é construído ou gravado — apenas a descrição é armazenada, na sessão atual.
name — nome da projeção; deve ser único dentro de (database, table) nesta sessão e não pode colidir com uma projeção real existente na tabela.- O corpo aceita as mesmas formas de uma projeção real: uma projeção de reordenação com
ORDER BY, uma de agregação com GROUP BY, uma filtrada com WHERE, ou a forma de índice de projeção INDEX <expression> TYPE <projection_index_type>.
WITH SETTINGS (...) é aceito e preservado; as configurações ficam visíveis em system.hypothetical_projections.
A tabela de destino deve ser uma tabela da família MergeTree em um banco de dados Atomic (ela precisa ter um UUID), porque o armazenamento da sessão indexa as entradas pelo UUID da tabela. As restrições impostas por um ADD PROJECTION real também valem aqui: tabelas com UNIQUE KEY, modos de mesclagem não-Ordinary sob deduplicate_merge_projection_mode = throw, MergeTree com sintaxe antiga e discos imutáveis são rejeitados.
Exemplo
DROP HYPOTHETICAL PROJECTION
Remove uma projeção hipotética da sessão atual.
DROP ALL HYPOTHETICAL PROJECTIONS
Remove todas as projeções hipotéticas definidas na sessão atual, independentemente da tabela. Os índices hipotéticos permanecem intactos; DROP ALL HYPOTHETICAL INDEXES faz o inverso.
Escopo e ciclo de vida
- Projeções hipotéticas existem apenas na sessão atual — não são visíveis para outras sessões e são descartadas quando a sessão termina.
- Definir ou remover uma delas não constrói nenhuma projeção e nunca afeta as queries comuns feitas na tabela.
- Inspecione as projeções hipotéticas da sessão atual por meio de
system.hypothetical_projections.
Privilégios necessários
CREATE HYPOTHETICAL PROJECTION exige o privilégio ALTER ADD PROJECTION na tabela — o mesmo exigido pelo ALTER TABLE ... ADD PROJECTION real — porque valida a definição em relação às colunas da tabela. Como não lê nenhum dado da tabela, o SELECT nas colunas da projeção ainda não é necessário; quando o EXPLAIN WHATIF passar a estimar projeções, ele lerá essas colunas e o SELECT em nível de coluna será então exigido, como já ocorre com CREATE HYPOTHETICAL INDEX.
DROP HYPOTHETICAL PROJECTION exige o mesmo privilégio, de modo que nomear uma tabela em um drop não revele se ela existe ou é elegível. DROP ALL HYPOTHETICAL PROJECTIONS não nomeia nenhuma tabela e não exige privilégio algum.
Veja também
Última modificação em 26 de setembro de 2026
