Campione (fase di trasformazione)

Descrizione

Restituisce un campione non deterministico dai risultati della fase precedente.

Sono supportate due modalità:

  • La modalità DOCUMENTS consente di campionare un numero fisso di documenti
    • Questa modalità è simile a GoogleSQL.RESERVOIR in quanto restituisce un campione di dimensione n, in cui qualsiasi campione di dimensione n è ugualmente possibile.
  • La modalità PERCENT consente di campionare una percentuale di documenti
    • Questa modalità è simile a GoogleSQL.BERNOULLI in quanto ogni documento viene selezionato in modo indipendente con una probabilità percent uguale. Di conseguenza, in media vengono restituiti #documents * percent / 100 documenti.

Sintassi

Node.js

  const sampled = await db.pipeline()
    .database()
    .sample(50)
    .execute();

  const sampled = await db.pipeline()
    .database()
    .sample({ percent: 0.5 })
    .execute();

Comportamento

Modalità Documenti

La modalità Documenti recupera un numero specificato di documenti in ordine casuale. Il numero specificato deve essere un valore INT64 non negativo.

Ad esempio, per la seguente raccolta:

Node.js

await db.collection('cities').doc('SF').set({name: 'San Francsico', state: 'California'});
await db.collection('cities').doc('NYC').set({name: 'New York City', state: 'New York'});
await db.collection('cities').doc('CHI').set({name: 'Chicago', state: 'Illinois'});

La fase di campionamento in modalità documento può essere utilizzata per recuperare un sottoinsieme non deterministico di risultati da questa raccolta.

Node.js

const sampled = await db.pipeline()
    .collection("/cities")
    .sample(1)
    .execute();

In questo esempio, verrà restituito un solo documento scelto in modo casuale.

  {name: 'New York City', state: 'New York'}

Se il numero fornito è maggiore del numero totale di documenti restituiti, tutti i documenti vengono restituiti in ordine casuale.

Node.js

const sampled = await db.pipeline()
    .collection("/cities")
    .sample(5)
    .execute();

Verranno generati i seguenti documenti:

  {name: 'New York City', state: 'New York'}
  {name: 'Chicago', state: 'Illinois'}
  {name: 'San Francisco', state: 'California'}

Esempi di clienti

Web

let results;

// Get a sample of 100 documents in a database
results = await execute(db.pipeline()
  .database()
  .sample(100)
);

// Randomly shuffle a list of 3 documents
results = await execute(db.pipeline()
  .documents([
    doc(db, "cities", "SF"),
    doc(db, "cities", "NY"),
    doc(db, "cities", "DC"),
  ])
  .sample(3)
);
test.firestore.js
Swift
var results: Pipeline.Snapshot

// Get a sample of 100 documents in a database
results = try await db.pipeline()
  .database()
  .sample(count: 100)
  .execute()

// Randomly shuffle a list of 3 documents
results = try await db.pipeline()
  .documents([
    db.collection("cities").document("SF"),
    db.collection("cities").document("NY"),
    db.collection("cities").document("DC"),
  ])
  .sample(count: 3)
  .execute()
PipelineSnippets.swift
Kotlin
Android
var results: Task<Pipeline.Snapshot>

// Get a sample of 100 documents in a database
results = db.pipeline()
    .database()
    .sample(100)
    .execute()

// Randomly shuffle a list of 3 documents
results = db.pipeline()
    .documents(
        db.collection("cities").document("SF"),
        db.collection("cities").document("NY"),
        db.collection("cities").document("DC")
    )
    .sample(3)
    .execute()
DocSnippets.kt
Java
Android
Task<Pipeline.Snapshot> results;

// Get a sample of 100 documents in a database
results = db.pipeline()
    .database()
    .sample(100)
    .execute();

// Randomly shuffle a list of 3 documents
results = db.pipeline()
    .documents(
        db.collection("cities").document("SF"),
        db.collection("cities").document("NY"),
        db.collection("cities").document("DC")
    )
    .sample(3)
    .execute();
DocSnippets.java
Python
# Get a sample of 100 documents in a database
results = client.pipeline().database().sample(100).execute()

# Randomly shuffle a list of 3 documents
results = (
    client.pipeline()
    .documents(
        client.collection("cities").document("SF"),
        client.collection("cities").document("NY"),
        client.collection("cities").document("DC"),
    )
    .sample(3)
    .execute()
)
firestore_pipelines.py
Java
// Get a sample of 100 documents in a database
Pipeline.Snapshot results1 = firestore.pipeline().database().sample(100).execute().get();

// Randomly shuffle a list of 3 documents
Pipeline.Snapshot results2 =
    firestore
        .pipeline()
        .documents(
            firestore.collection("cities").document("SF"),
            firestore.collection("cities").document("NY"),
            firestore.collection("cities").document("DC"))
        .sample(3)
        .execute()
        .get();
PipelineSnippets.java

Modalità percentuale

In modalità percentuale, ogni documento ha una probabilità specificata di percent di essere restituito. A differenza della modalità Documenti, l'ordine qui non è casuale, ma mantiene l'ordine preesistente dei documenti. Questo input percentuale deve essere un valore double compreso tra 0.0 e 1.0.

Poiché ogni documento viene selezionato in modo indipendente, l'output è non deterministico e in media verranno restituiti #documents * percent / 100 documenti.

Ad esempio, per la seguente raccolta:

Node.js

await db.collection('cities').doc('SF').set({name: 'San Francsico', state: 'California'});
await db.collection('cities').doc('NYC').set({name: 'New York City', state: 'New York'});
await db.collection('cities').doc('CHI').set({name: 'Chicago', state: 'Illinois'});
await db.collection('cities').doc('ATL').set({name: 'Atlanta', state: 'Georgia'});

La fase di campionamento in modalità percentuale può essere utilizzata per recuperare (in media) il 50% dei documenti dalla fase di raccolta.

Node.js

  const sampled = await db.pipeline()
    .collection("/cities")
    .sample({ percent: 0.5 })
    .execute();

Verrà creato un campione non deterministico del 50% (in media) dei documenti della raccolta cities. Di seguito è riportato un possibile output.

  {name: 'New York City', state: 'New York'}
  {name: 'Chicago', state: 'Illinois'}

In modalità percentuale, poiché ogni documento ha la stessa probabilità di essere selezionato, è possibile che non venga restituito alcun documento o che vengano restituiti tutti i documenti.

Esempi di clienti

Web

// Get a sample of on average 50% of the documents in the database
const results = await execute(db.pipeline()
  .database()
  .sample({ percentage: 0.5 })
);
test.firestore.js
Swift
// Get a sample of on average 50% of the documents in the database
let results = try await db.pipeline()
  .database()
  .sample(percentage: 0.5)
  .execute()
PipelineSnippets.swift
Kotlin
Android
// Get a sample of on average 50% of the documents in the database
val results = db.pipeline()
    .database()
    .sample(SampleStage.withPercentage(0.5))
    .execute()
DocSnippets.kt
Java
Android
// Get a sample of on average 50% of the documents in the database
Task<Pipeline.Snapshot> results = db.pipeline()
    .database()
    .sample(SampleStage.withPercentage(0.5))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_stages import SampleOptions

# Get a sample of on average 50% of the documents in the database
results = (
    client.pipeline().database().sample(SampleOptions.percentage(0.5)).execute()
)
firestore_pipelines.py
Java
// Get a sample of on average 50% of the documents in the database
Pipeline.Snapshot results =
    firestore.pipeline().database().sample(Sample.withPercentage(0.5)).execute().get();
PipelineSnippets.java