Échantillon

Description

Renvoie un échantillon non déterministe à partir des résultats de l'étape précédente.

Deux modes sont disponibles :

  • Le mode DOCUMENTS permet d'échantillonner un nombre défini de documents.
    • Ce mode est semblable à GoogleSQL.RESERVOIR, car il génère un échantillon de taille n, où tout échantillon de taille n est également possible.
  • Le mode PERCENT permet d'échantillonner un pourcentage de documents.
    • Ce mode est semblable à GoogleSQL.BERNOULLI, car chaque document est sélectionné indépendamment avec une probabilité percent égale. Cela entraîne le renvoi de #documents * percent / 100 documents en moyenne.

Syntaxe

Node.js

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

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

Comportement

Mode Documents

Le mode Documents récupère un nombre spécifié de documents dans un ordre aléatoire. Le nombre spécifié doit être une valeur INT64 non négative.

Par exemple, pour la collection suivante :

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'});

L'étape d'échantillonnage en mode document peut être utilisée pour récupérer un sous-ensemble non déterministe de résultats de cette collection.

Node.js

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

Dans cet exemple, un seul document aléatoire serait renvoyé.

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

Si le nombre fourni est supérieur au nombre total de documents renvoyés, tous les documents sont renvoyés dans un ordre aléatoire.

Node.js

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

Vous obtiendrez les documents suivants :

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

Exemples de clients

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

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

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

Mode Pourcentage

En mode pourcentage, chaque document a une probabilité percent d'être renvoyé. Contrairement au mode Documents, l'ordre n'est pas aléatoire ici, mais conserve l'ordre des documents préexistant. Ce pourcentage doit être une valeur double comprise entre 0.0 et 1.0.

Étant donné que chaque document est sélectionné indépendamment, le résultat n'est pas déterministe et, en moyenne, #documents * percent / 100 documents seront renvoyés.

Par exemple, pour la collection suivante :

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'});

L'étape d'échantillonnage en mode pourcentage peut être utilisée pour récupérer (en moyenne) 50 % des documents de l'étape de collecte.

Node.js

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

Cela générera un échantillon non déterministe de (en moyenne) 50 % des documents de la collection cities. Voici un exemple de résultat possible.

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

En mode pourcentage, chaque document ayant la même probabilité d'être sélectionné, il est possible qu'aucun document ou que tous les documents soient renvoyés.

Exemples de clients

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

// 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

// 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