> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação sobre projeções hipotéticas (what-if)

# HYPOTHETICAL PROJECTION

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`](https://clickhouse.com/docs/pt-BR/reference/statements/explain#explain-whatif).

O `EXPLAIN WHATIF` estima projeções hipotéticas normais (ordenadas): quantas marcas e linhas a leitura da projeção acessaria em uma consulta e se o otimizador a escolheria em vez da tabela base. Nem toda projeção é estimada — projeções de agregação e projeções com uma cláusula `WHERE` são dois exemplos disso —, e um candidato não estimado é listado com o respectivo motivo. Consulte [`EXPLAIN WHATIF`](https://clickhouse.com/docs/pt-BR/reference/statements/explain#explain-whatif) para ver a lista completa. As projeções hipotéticas da sessão também ficam visíveis em [`system.hypothetical_projections`](https://clickhouse.com/docs/pt-BR/reference/system-tables/hypothetical_projections).

## CREATE HYPOTHETICAL PROJECTION

```sql theme={null}
CREATE HYPOTHETICAL PROJECTION [IF NOT EXISTS] name
    ON [db.]table_name (SELECT <columns> [WHERE ...] [GROUP BY ...] [ORDER BY ...]) [WITH SETTINGS (...)]

CREATE HYPOTHETICAL PROJECTION [IF NOT EXISTS] name
    ON [db.]table_name INDEX <expression> TYPE <projection_index_type> [WITH SETTINGS (...)]
```

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**

```sql theme={null}
CREATE HYPOTHETICAL PROJECTION p_by_b ON t (SELECT a, b ORDER BY b);
CREATE HYPOTHETICAL PROJECTION p_idx ON t INDEX b TYPE basic;
```

## DROP HYPOTHETICAL PROJECTION

```sql theme={null}
DROP HYPOTHETICAL PROJECTION [IF EXISTS] name ON [db.]table_name
```

Remove uma projeção hipotética da sessão atual.

## DROP ALL HYPOTHETICAL PROJECTIONS

```sql theme={null}
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`](https://clickhouse.com/docs/pt-BR/reference/system-tables/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. `EXPLAIN WHATIF` exige `SELECT` em nível de coluna nas colunas da projeção para estimá-la, como já ocorre com [`CREATE HYPOTHETICAL INDEX`](https://clickhouse.com/docs/pt-BR/reference/statements/hypothetical-index#required-privileges).

`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, e `EXPLAIN WHATIF` verifica novamente esse privilégio antes de validar uma definição armazenada em relação à tabela. `DROP ALL HYPOTHETICAL PROJECTIONS` não nomeia nenhuma tabela e não exige privilégio algum.

## Veja também

* [`CREATE HYPOTHETICAL INDEX`](https://clickhouse.com/docs/pt-BR/reference/statements/hypothetical-index)
* [`EXPLAIN WHATIF`](https://clickhouse.com/docs/pt-BR/reference/statements/explain#explain-whatif)
* [`system.hypothetical_projections`](https://clickhouse.com/docs/pt-BR/reference/system-tables/hypothetical_projections)
* [Projeções](https://clickhouse.com/docs/pt-BR/reference/engines/table-engines/mergetree-family/mergetree.md#projections)