Modificar dados com operações de pipeline do Firestore

Use as etapas update(...) e delete(...) da linguagem de manipulação de dados (DML) para criar pipelines de dados que podem consultar documentos e excluir ou modificar dados.

Requisitos da edição

As operações descritas nesta página exigem a edição Enterprise do Firestore.

Antes de começar

Você precisa saber como consultar um banco de dados com operações de pipeline.

Atualizar documentos

Use a etapa de DML update(...) para criar pipelines de dados que podem consultar documentos e adicionar ou modificar dados.

Todas as etapas de DML precisam estar no final do pipeline. Os documentos que chegam a essa etapa precisam incluir o campo __name__ para identificar quais documentos atualizar. A operação falha se algum dos documentos que você tenta atualizar não existir.

Por exemplo, a operação a seguir faz o backfill de uma mudança no modelo de dados para todos os documentos em um grupo de coleções. O pipeline adiciona um campo preferences.color a todos os documentos do grupo de coleções users que não têm esse campo.

Node.js
const snapshot = await db.pipeline()
   .collectionGroup("users")
   .where(not(exists(field("preferences.color"))))
   .addFields(constant(null).as("preferences.color"))
   .removeFields("color")
   .update()
   .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Constant, Field, Not

snapshot = (
    client.pipeline()
    .collection_group("users")
    .where(Not(Field.of("preferences.color").exists()))
    .add_fields(Constant.of(None).as_("preferences.color"))
    .remove_fields("color")
    .update()
    .execute()
)
Java
Pipeline.Snapshot snapshot = firestore.pipeline()
   .collectionGroup("users")
   .where(not(exists(field("preferences.color"))))
   .addFields(constant((String) null).as("preferences.color"))
   .removeFields("color")
   .update()
   .execute().get();
Go
snapshot := client.Pipeline().
	CollectionGroup("users").
	Where(firestore.Not(firestore.FieldExists(firestore.FieldOf("preferences.color")))).
	AddFields(firestore.Selectables(
		firestore.ConstantOfNull().As("preferences.color"),
	)).
	RemoveFields(firestore.Fields("color")).
	Update().
	Execute(ctx)

Excluir documentos

Use as etapas de DML delete(...) para criar pipelines de dados que podem consultar documentos e excluir dados. Para evitar exclusões acidentais em massa, os pipelines que terminam em delete(...) precisam incluir pelo menos uma etapa where(...). Todas as etapas de DML precisam estar no final do pipeline.

Por exemplo, o pipeline a seguir exclui todos os documentos users com address.users definido como USA e com __create_time__ há menos de 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)

Consistência

As operações de pipeline com estágios update(...) e delete() não são compatíveis em uma transação. As etapas DML são executadas fora de uma transação com o seguinte comportamento:

  • Cada documento é atualizado de forma independente. Isso significa que as operações não são atômicas em todos os documentos. A operação falha no primeiro erro, e é possível ter um sucesso parcial.
  • As seguintes etapas são aceitas:
    • collection(...)
    • collection_group(...)
    • where(...)
    • select(...)
    • add_fields(...)
    • remove_fields(...)
    • let(...)
    • sort(...)
    • limit(...)
    • offset(...)
  • As seguintes etapas não são compatíveis:
    • aggregate(...)
    • distinct(...)
    • unnest(...)
    • find_nearest(...)
    • Estágios de várias consultas, como union(...), junções e subconsultas, não são permitidos antes de um estágio DML.

Limitações

Observe as seguintes limitações para etapas de DML:

  • Os estágios de DML precisam ser os últimos em uma definição de pipeline antes de chamar .execute().
  • As operações de pipeline com estágios update(...) e delete() não são compatíveis em uma transação.
  • Se a etapa anterior à 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 ambiente autônomo.