Muestra (etapa de transformación)

Descripción

Devuelve una muestra no determinística de los resultados de la etapa anterior.

Existen dos modos admitidos:

  • El modo DOCUMENTS permite muestrear una cantidad establecida de documentos.
    • Este modo es similar a GoogleSQL.RESERVOIR, ya que genera una muestra de tamaño n, en la que cualquier muestra de tamaño n es igualmente posible.
  • El modo PERCENT permite muestrear un porcentaje de documentos.
    • Este modo es similar a GoogleSQL.BERNOULLI, ya que cada documento se selecciona de forma independiente con una probabilidad percent igual. Esto da como resultado que se devuelvan #documents * percent / 100 documentos en promedio.

Sintaxis

Node.js

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

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

Comportamiento

Modo de documentos

En el modo de documentos, se recupera una cantidad específica de documentos en orden aleatorio. El número especificado debe ser un valor de INT64 no negativo.

Por ejemplo, para la siguiente colección:

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 etapa de muestra en el modo de documentos se puede usar para recuperar un subconjunto no determinístico de resultados de esta colección.

Node.js

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

En este ejemplo, solo se devolvería 1 documento al azar.

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

Si el número proporcionado es mayor que la cantidad total de documentos devueltos, se devuelven todos los documentos en orden aleatorio.

Node.js

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

Esto generará los siguientes documentos:

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

Ejemplos de clientes

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

Modo de porcentaje

En el modo de porcentaje, cada documento tiene una probabilidad de percent especificada de devolverse. A diferencia del modo de documentos, el orden aquí no es aleatorio, sino que conserva el orden preexistente de los documentos. Este porcentaje de entrada debe ser un valor doble entre 0.0 y 1.0.

Dado que cada documento se selecciona de forma independiente, el resultado no es determinístico y, en promedio, se devolverán #documents * percent / 100 documentos.

Por ejemplo, para la siguiente colección:

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 etapa de muestra en el modo de porcentaje se puede usar para recuperar (en promedio) el 50% de los documentos de la etapa de recopilación.

Node.js

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

Esto generará una muestra no determinística del 50% (en promedio) de los documentos de la colección cities. A continuación, se muestra un posible resultado.

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

En el modo de porcentaje, dado que cada documento tiene la misma probabilidad de ser seleccionado, es posible que no se devuelva ningún documento o que se devuelvan todos.

Ejemplos de clientes

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