Descrição

O comando DELETE exclui as linhas que atendem à cláusula WHERE da tabela especificada. Se a cláusula WHERE estiver ausente, o efeito será excluir todas as linhas da tabela. O resultado será uma tabela válida, mas vazia.

Existem duas maneiras de excluir linhas em uma tabela usando informações contidas em outras tabelas no banco de dados: usando sub-seleções, ou especificando tabelas adicionais na cláusula USING. Qual técnica é a mais apropriada depende das circunstâncias específicas.

A cláusula opcional RETURNING faz com que o comando DELETE calcule e retorne valores com base em cada linha realmente excluída. Pode ser computada qualquer expressão usando as colunas da tabela, e/ou colunas de outras tabelas mencionadas na cláusula USING. A sintaxe da lista da cláusula RETURNING é idêntica à da lista de saída do comando SELECT.

É necessário ter o privilégio DELETE na tabela para excluir suas linhas, bem como o privilégio SELECT para qualquer tabela na cláusula USING, ou cujos valores sejam lidos pela condição.

Parâmetros

Saídas

Após a conclusão bem-sucedida, o comando DELETE retorna uma etiqueta de comando na forma

DELETE contador

O contador é o número de linhas excluídas. Note que o número pode ser menor que o número de linhas que corresponderam à condição, quando exclusões forem suprimidas por um gatilho BEFORE DELETE. Se o contador for igual a 0, nenhuma linha foi excluída pelo comando (isto não é considerado um erro).

Se o comando DELETE contiver uma cláusula RETURNING, o resultado será semelhante ao de um comando SELECT contendo as colunas e valores definidos na lista da cláusula RETURNING, computadas sobre a(s) linha(s) excluída(s) pelo comando.

Notas

O PostgreSQL permite referenciar colunas de outras tabelas na condição WHERE, especificando as outras tabelas na cláusula USING. Por exemplo, para excluir todos os filmes produzidos por um determinado produtor, pode-se executar:

DELETE FROM films USING producers
  WHERE producer_id = producers.id AND producers.name = 'foo';

O que está essencialmente acontecendo aqui é uma junção entre as tabelas films e producers, com todas as linhas de films juntadas com sucesso sendo marcadas para exclusão. Esta sintaxe não é padrão. Uma maneira mais de acordo com o padrão de fazer isto é:

DELETE FROM films
  WHERE producer_id IN (SELECT id FROM producers WHERE name = 'foo');

Em alguns casos, o estilo junção é mais fácil de escrever ou mais rápido de executar do que o estilo subseleção.

Exemplos

Excluir todos os filmes, exceto os musicais:

DELETE FROM films WHERE kind <> 'Musical';

Limpar a tabela films:

DELETE FROM films;

Excluir as tarefas concluídas, retornando os detalhes completos das linhas excluídas:

DELETE FROM tasks WHERE status = 'DONE' RETURNING *;

Excluir a linha da tabela tasks onde o cursor c_tasks está posicionado no momento:

DELETE FROM tasks WHERE CURRENT OF c_tasks;

Embora não exista uma cláusula LIMIT no comando DELETE, é possível obter um efeito semelhante usando o mesmo método descrito em Exemplo de limite de atualizações na documentação do comando UPDATE.

WITH delete_batch AS (
  SELECT l.ctid FROM user_logs AS l
    WHERE l.status = 'archived'
    ORDER BY l.creation_date
    FOR UPDATE
    LIMIT 10000
)
DELETE FROM user_logs AS dl
  USING delete_batch AS del
  WHERE dl.ctid = del.ctid;

Conformidade

Este comando está em conformidade com o padrão SQL, exceto que as cláusulas USING e RETURNING são extensões do PostgreSQL, assim como a capacidade de usar WITH com DELETE.

Veja também