> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mutações de exclusão

> Página que descreve mutações de exclusão — consultas ALTER que manipulam dados da tabela por meio de exclusões

Mutações de exclusão referem-se a consultas `ALTER` que manipulam dados da tabela por meio de exclusões. Em especial, incluem consultas como `ALTER TABLE DELETE`. Executar essas consultas gera novas versões modificadas das partes de dados. Isso significa que essas instruções acionam a reescrita de partes de dados inteiras para todos os dados inseridos antes da mutação, resultando em uma grande quantidade de solicitações de gravação.

<Info>
  Para exclusões, você pode evitar essa grande quantidade de solicitações de gravação usando motores de tabela especializados, como [ReplacingMergeTree](/pt-BR/concepts/features/operations/update/replacing-merge-tree) ou [CollapsingMergeTree](/pt-BR/reference/engines/table-engines/mergetree-family/collapsingmergetree), em vez do motor de tabela MergeTree padrão.
</Info>

A instrução de exclusão leve remove linhas da tabela `[db.]table` que correspondem à expressão `expr`. Ela está disponível apenas para a família \*MergeTree de mecanismos de tabela.

```sql theme={null}
DELETE FROM [db.]table [ON CLUSTER cluster] [IN PARTITION partition_expr] WHERE expr;
```

É chamado de "exclusão leve" para diferenciá-lo do comando [ALTER TABLE ... DELETE](/pt-BR/reference/statements/alter/delete), que é uma operação pesada.

<div id="examples">
  ## Exemplos
</div>

```sql theme={null}
-- Exclui todas as linhas da tabela `hits` onde a coluna `Title` contém o texto `hello`
DELETE FROM hits WHERE Title LIKE '%hello%';
```

<div id="lightweight-delete-does-not-delete-data-immediately">
  ## Exclusão leve não exclui os dados imediatamente
</div>

Exclusão leve é implementada como uma [mutação](/pt-BR/reference/statements/alter#mutations) que marca linhas como excluídas, mas não as remove fisicamente de imediato.

Por padrão, as instruções `DELETE` aguardam a conclusão da marcação das linhas como excluídas antes de retornar. Isso pode levar muito tempo se o volume de dados for grande. Como alternativa, você pode executá-la de forma assíncrona em segundo plano usando a configuração [`lightweight_deletes_sync`](/pt-BR/reference/settings/session-settings#lightweight_deletes_sync). Se ela estiver desabilitada, a instrução `DELETE` retornará imediatamente, mas os dados ainda poderão ficar visíveis para consultas até que a mutação em segundo plano seja concluída.

A mutação não remove fisicamente as linhas marcadas como excluídas; isso só acontece durante a próxima mesclagem. Como resultado, é possível que, por um período indeterminado, os dados não sejam de fato excluídos do armazenamento, apenas marcados como excluídos.

Se você precisar garantir que seus dados sejam excluídos do armazenamento em um prazo previsível, considere usar a configuração da tabela [`min_age_to_force_merge_seconds`](/pt-BR/reference/settings/merge-tree-settings#min_age_to_force_merge_seconds). Ou use o comando [ALTER TABLE ... DELETE](/pt-BR/reference/statements/alter/delete). Observe que excluir dados com `ALTER TABLE ... DELETE` pode consumir recursos significativos, pois recria todas as partes afetadas.

<div id="deleting-large-amounts-of-data">
  ## Exclusão de grandes volumes de dados
</div>

Exclusões em grande volume podem afetar negativamente o desempenho do ClickHouse. Se você estiver tentando excluir todas as linhas de uma tabela, considere usar o comando [`TRUNCATE TABLE`](/pt-BR/reference/statements/truncate).

Se você espera fazer exclusões frequentes, considere usar uma [chave de particionamento personalizada](/pt-BR/reference/engines/table-engines/mergetree-family/custom-partitioning-key). Você poderá então usar o comando [`ALTER TABLE ... DROP PARTITION`](/pt-BR/reference/statements/alter/partition#drop-partitionpart) para remover rapidamente todas as linhas associadas a essa partição.

<div id="limitations-of-lightweight-delete">
  ## Limitações da exclusão leve
</div>

<div id="lightweight-deletes-with-projections">
  ### Exclusões leves com projeções
</div>

Por padrão, `DELETE` não funciona em tabelas com projeções. Isso ocorre porque linhas de uma projeção podem ser afetadas por uma operação `DELETE`. Porém, há uma [configuração do MergeTree](/pt-BR/reference/settings/merge-tree-settings), `lightweight_mutation_projection_mode`, para alterar esse comportamento.

<div id="performance-considerations-when-using-lightweight-delete">
  ## Considerações de desempenho ao usar exclusão leve
</div>

**Excluir grandes volumes de dados com a instrução de exclusão leve pode afetar negativamente o desempenho das consultas SELECT.**

Os itens a seguir também podem afetar negativamente o desempenho da exclusão leve:

* Uma condição `WHERE` complexa em uma consulta `DELETE`.
* Se a fila de mutações estiver cheia de muitas outras mutações, isso pode levar a problemas de desempenho, já que todas as mutações em uma tabela são executadas sequencialmente.
* A tabela afetada tem um número muito grande de partes de dados.
* Ter muitos dados em partes compactas. Em uma parte compacta, todas as colunas são armazenadas em um único arquivo.

<div id="delete-permissions">
  ## Permissões para exclusão
</div>

`DELETE` requer o privilégio `ALTER DELETE`. Para habilitar instruções `DELETE` em uma tabela específica para um determinado usuário, execute o comando a seguir:

```sql theme={null}
GRANT ALTER DELETE ON db.table to username;
```

<div id="how-lightweight-deletes-work-internally-in-clickhouse">
  ## Como as exclusões leves funcionam internamente no ClickHouse
</div>

1. **Uma "máscara" é aplicada às linhas afetadas**

   Quando uma consulta `DELETE FROM table ...` é executada, o ClickHouse salva uma máscara na qual cada linha é marcada como "existente" ou "excluída". Essas linhas "excluídas" são omitidas das consultas subsequentes. No entanto, as linhas só são realmente removidas mais tarde, por mesclagens subsequentes. Gravar essa máscara é muito mais leve do que o que é feito por uma consulta `ALTER TABLE ... DELETE`.

   A máscara é implementada como uma coluna de sistema oculta `_row_exists` que armazena `True` para todas as linhas visíveis e `False` para as excluídas. Essa coluna só está presente em uma parte se algumas linhas dessa parte tiverem sido excluídas. Essa coluna não existe quando uma parte tem todos os valores iguais a `True`.

2. **As consultas `SELECT` são transformadas para incluir a máscara**

   Quando uma coluna mascarada é usada em uma consulta, a consulta `SELECT ... FROM table WHERE condition` é internamente estendida com o predicado em `_row_exists` e transformada em:

   ```sql theme={null}
   SELECT ... FROM table PREWHERE _row_exists WHERE condition
   ```

   No momento da execução, a coluna `_row_exists` é lida para determinar quais linhas não devem ser retornadas. Se houver muitas linhas excluídas, o ClickHouse pode determinar quais grânulos podem ser totalmente ignorados ao ler o restante das colunas.

3. **As consultas `DELETE` são transformadas em consultas `ALTER TABLE ... UPDATE`**

   O `DELETE FROM table WHERE condition` é traduzido em uma mutação `ALTER TABLE table UPDATE _row_exists = 0 WHERE condition`.

   Internamente, essa mutação é executada em duas etapas:

   1. Um comando `SELECT count() FROM table WHERE condition` é executado para cada parte individual para determinar se a parte foi afetada.

   2. Com base nos comandos acima, as partes afetadas são então modificadas, e links físicos são criados para as partes não afetadas. No caso de partes no formato wide, a coluna `_row_exists` de cada linha é atualizada, e os arquivos de todas as outras colunas recebem links físicos. Para partes no formato compact, todas as colunas são regravadas porque ficam armazenadas juntas em um único arquivo.

   Pelas etapas acima, podemos ver que a exclusão leve, usando a técnica de mascaramento, melhora o desempenho em relação ao `ALTER TABLE ... DELETE` tradicional porque não regrava os arquivos de todas as colunas das partes afetadas.

<div id="related-content">
  ## Conteúdo relacionado
</div>

* Blog: [Como tratar atualizações e exclusões no ClickHouse](https://clickhouse.com/blog/handling-updates-and-deletes-in-clickhouse)