Modificare i dati con le operazioni della pipeline

Utilizza le fasi update(...) e delete(...) Data Manipulation Language (DML) per creare pipeline di dati che possono eseguire query per i documenti ed eliminare o modificare i dati.

Requisiti relativi alla versione

Le operazioni descritte in questa pagina richiedono la versione Enterprise di Firestore.

Prima di iniziare

Devi sapere come eseguire query su un database con le operazioni della pipeline.

Aggiornare i documenti

Utilizza la fase DML update(...) per creare pipeline di dati che possono eseguire query per i documenti e poi aggiungere o modificare i dati.

Tutte le fasi DML devono essere alla fine della pipeline. I documenti che entrano in questa fase devono includere il campo __name__ per identificare quali documenti aggiornare. L'operazione non riesce se uno dei documenti che tenti di aggiornare non esiste.

Ad esempio, la seguente operazione esegue il backfill di una modifica delmodello dei datii in tutti i documenti di un gruppo di raccolte. La pipeline aggiunge un campo preferences.color a tutti i documenti nel gruppo di raccolte users in cui manca questo 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

Elimina documenti

Utilizza le fasi DML della delete(...) fase per creare pipeline di dati che possono eseguire query per i documenti ed eliminare i dati. Per evitare eliminazioni collettive accidentali, le pipeline che terminano con delete(...) devono includere almeno una fase where(...). Tutte le fasi DML devono essere alla fine della pipeline.

Ad esempio, la seguente pipeline elimina tutti i documenti users con address.users impostato su USA e con __create_time__ inferiore a 10 giorni:

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

Coerenza

Le operazioni della pipeline con le fasi update(...) e delete() non sono supportate all'interno di una transazione. Le fasi DML vengono eseguite al di fuori di una transazione con il seguente comportamento:

  • Ogni documento viene aggiornato in modo indipendente. Ciò significa che le operazioni non sono atomiche tra i documenti. L'operazione non riesce al primo errore ed è possibile un successo parziale.
  • Sono supportate le seguenti fasi:
    • collection(...)
    • collection_group(...)
    • where(...)
    • select(...)
    • add_fields(...)
    • remove_fields(...)
    • let(...)
    • sort(...)
    • limit(...)
    • offset(...)
  • Le seguenti fasi non sono supportate:
    • aggregate(...)
    • distinct(...)
    • unnest(...)
    • find_nearest(...)
    • Le fasi di più query come union(...), i join e le subquery non sono consentite prima di una fase DML.

Limitazioni

Tieni presenti le seguenti limitazioni per le fasi DML:

  • Le fasi DML devono essere le ultime in una definizione di pipeline prima di chiamare .execute().
  • Le operazioni della pipeline con le fasi update(...) e delete() non sono supportate all'interno di una transazione.
  • Se la fase precedente alla fase DML produce più documenti con lo stesso __name__, ogni istanza viene elaborata. Per update(...), ciò significa che lo stesso documento di destinazione potrebbe essere modificato più volte. Per delete(...), i tentativi successivi al primo non verranno eseguiti.