Excluir

delete() é uma etapa de linguagem de manipulação de dados (DML, na sigla em inglês) que permite que uma consulta remova documentos com base nos resultados de uma consulta. Essa etapa pode ser anexada ao final de uma consulta e exclui todos os documentos referenciados pelo campo __name__ da etapa anterior.

Exemplos

Por exemplo, a consulta a seguir exclui todos os users documentos com address.users definido como USA e com __create_time__ menor que 10 dias:

Node.js
const pipeline = db.pipeline()
  .collectionGroup("users")
  .where(field("address.country").equal("USA"))
  .where(field("__create_time__").timestampAdd("day", 10).lessThan(currentTimestamp()))
  .delete();
await pipeline.execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import CurrentTimestamp, Field

snapshot = (
    client.pipeline()
    .collection_group("users")
    .where(Field.of("address.country").equal("USA"))
    .where(
        Field.of("__create_time__")
        .timestamp_add("day", 10)
        .less_than(CurrentTimestamp())
    )
    .delete()
    .execute()
)
Java
Pipeline.Snapshot deleteResults = firestore.pipeline()
  .collectionGroup("users")
  .where(field("address.country").equal("USA"))
  .where(field("__create_time__").add(constant(10)).lessThan(currentTimestamp()))
  .delete()
  .execute().get();
Go
snapshot := client.Pipeline().
	CollectionGroup("users").
	Where(firestore.FieldOf("address.country").Equal("USA")).
	Where(firestore.FieldOf("__create_time__").Add(firestore.ConstantOf(10)).LessThan(firestore.CurrentTimestamp())).
	Delete().
	Execute(ctx)

Comportamento

Resposta

A etapa delete() sempre emite um único documento, como { documents_modified: 28L }, descrevendo quantos documentos foram excluídos.

Exclusão de coleção completa

É possível excluir todos os documentos de uma coleção anexando delete() à etapa de entrada, como:

Node.js

const results = await db.pipeline()
  .collection("/users")
  .delete()
  .execute();

Verifique se a etapa where(...) antes do delete() final limita corretamente os documentos para atualizar apenas os esperados. É recomendável executar a consulta sem a etapa delete() final primeiro para validar se apenas os documentos pretendidos foram removidos.

Etapa final

A etapa delete() precisa estar no final de um pipeline. Não é possível fornecer outras etapas.

Excluir tudo

Por padrão, a etapa delete() remove todos os documentos referenciados pela etapa anterior. Se você quiser limitar o tamanho da carga de trabalho ou souber que as condições de filtro correspondem exatamente a um documento, um limit(1) poderá ser adicionado antes do delete() final para limitar o trabalho total.

Mutações entre coleções

A etapa delete() final aplica mutações a qualquer documento referenciado por __name__ (supondo que toda a autenticação necessária seja fornecida). Isso inclui a exclusão de documentos de vários grupos de coleções ou coleções diferentes como parte da mesma solicitação.

__name__ obrigatório

A etapa delete() exige que a etapa anterior forneça um campo __name__ que contenha uma referência de documento a ser removida. Se isso não for feito, ocorrerá um erro de execução e, quando executado fora de uma transação, poderá resultar em sucesso parcial.

A maioria das etapas de entrada, como collection(...), collection_group(...), database(...) e documents(...), inclui o campo __name__ por padrão. Portanto, isso só é relevante se você estiver usando uma projeção (como select(...)) ou realizando uma transformação nos documentos (como aggregate(...)).

A resposta inclui um resumo do número de documentos modificados. Por exemplo, a resposta a seguir confirma que o pipeline modificou três documentos:

{documents_modified: 3L}

Limitações

  • As etapas de DML não oferecem suporte a Cloud Firestore Security Rules. As tentativas de operação de DML por meio de Cloud Firestore Security Rules são negadas.

  • Durante a visualização desse recurso, não é possível executar etapas de DML em uma transação. Para mais informações sobre o comportamento de consistência, consulte Consistência.

  • Se a etapa anterior à etapa de DML produzir vários documentos com o mesmo __name__, cada instância será processada. Para update(...), isso significa que o mesmo documento de destino pode ser modificado várias vezes. Para delete(...), as tentativas subsequentes após a primeira serão sem operação.