Modificar dados com operações de pipeline

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 versã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 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 entram nessa 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();
test.firestore.js
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()
)
firestore_pipelines.py
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();
PipelineSnippets.java

Excluir documentos

Use as etapas DML delete(...) para construir pipelines de dados que podem consultar documentos e excluir dados. Para evitar exclusões em massa acidentais, 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__ inferior a 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();
test.firestore.js
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()
)
firestore_pipelines.py
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();
PipelineSnippets.java

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 da 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 um sucesso parcial é possível.
  • As seguintes etapas são compatíveis:
    • 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 de DML.

Limitações

Observe as seguintes limitações para as 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 no-ops.