Modificar dados com operações de pipeline do Firestore

Use os estágios da linguagem de manipulação de dados (DML, na sigla em inglês) update(...) e delete(...) para criar pipelines de dados que possam 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 o estágio DML update(...) para criar pipelines de dados que possam consultar documentos e adicionar ou modificar dados.

Todos os estágios DML precisam estar no final do pipeline. Os documentos que chegam a esse estágio precisam incluir o campo __name__ para identificar quais documentos atualizar. A operação falha se algum dos documentos que você tentar atualizar não existir.

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

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

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

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 os estágios DML delete(...) stage para criar pipelines de dados que possam consultar documentos e excluir dados. Para evitar exclusões em massa acidentais, os pipelines que terminam em delete(...) precisam incluir pelo menos um estágio where(...). Todos os estágios DML precisam estar no final do pipeline.

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

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

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

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 com uma transação. Os estágios DML são executados 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 o sucesso parcial é possível.
• Os seguintes estágios são compatíveis:
  • collection(...)
  • collection_group(...)
  • where(...)
  • select(...)
  • add_fields(...)
  • remove_fields(...)
  • let(...)
  • sort(...)
  • limit(...)
  • offset(...)
• Os seguintes estágios não são compatíveis:
  • aggregate(...)
  • distinct(...)
  • unnest(...)
  • find_nearest(...)
  • Os 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 estágios DML:

• Os estágios DML precisam ser os últimos estágios 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 com uma transação.
• Se o estágio anterior ao 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.