Пример

Описание

Возвращает недетерминированную выборку из результатов предыдущего этапа.

Поддерживаются два режима:

  • documents : случайным образом выбрать n документов.
  • percent : случайным образом выбрать n процентов документов.

Примеры

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
Быстрый 
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

Режимы

Режим документов

В режиме просмотра documents из входных данных случайным образом выбираются до n документов, при этом каждый документ (вместе с порядком документов) имеет одинаковую вероятность быть выбранным. Для этого Cloud Firestore необходимо сканировать и обрабатывать все документы, что может оказаться дорогостоящей операцией.

Например, для следующей коллекции:

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

В режиме просмотра документов этап выборки позволяет получить недетерминированное подмножество результатов из этой коллекции.

Node.js 

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

В этом примере будет возвращен только один случайный документ.

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

Если указанное число превышает общее количество возвращенных документов, все документы возвращаются в случайном порядке.

Node.js 

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

В результате будут получены следующие документы: 

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

Процентный режим

В режиме percent предпринимается попытка выбрать n процентов всех документов из входных данных. В результате на этом этапе генерируется приблизительно # documents * percent / 100 документов. Как и в режиме documents , Cloud Firestore гарантирует, что каждый документ имеет одинаковую вероятность быть возвращенным. Это требует от Cloud Firestore сканирования и обработки всех документов, поэтому даже при небольшом наборе результатов эта операция может оказаться дорогостоящей.

В отличие от режима documents , порядок здесь не случаен, а сохраняет существующий порядок документов. Вводимый процент должен быть значением типа double от 0.0 до 1.0 .

Например, для следующей коллекции:

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

Этап выборки в процентном режиме позволяет получить (в среднем) 50% документов на этапе сбора данных.

Node.js 

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

В результате будет получена недетерминированная выборка (в среднем) из 50% документов из cities коллекции. Ниже представлен один из возможных вариантов результата. 

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

В процентном режиме, поскольку каждый документ имеет одинаковую вероятность быть выбранным, возможно, что будут возвращены либо ни одного документа, либо все документы.

Примеры клиентов

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
Быстрый 
// 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