> ## 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`](/docs/pt-BR/reference/statements/explain#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`](/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`](/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. 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`](/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. `DROP ALL HYPOTHETICAL PROJECTIONS` não nomeia nenhuma tabela e não exige privilégio algum.

## Veja também

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