サンプル（変換ステージ）

説明

前のステージの結果から非決定的サンプルを返します。

サポートされているモードは次の 2 つです。

  • DOCUMENTS モードでは、一定数のドキュメントをサンプリングできます。
    • このモードは、サイズ n のサンプルを出力するという点で GoogleSQL.RESERVOIR と似ており、サイズ n のすべてのサンプルは同じ確率で出力されます。
  • PERCENT モードでは、一定の割合のドキュメントをサンプリングできます。
    • このモードは、各ドキュメントが等しい確率 percent で独立して選択されるという点で GoogleSQL.BERNOULLI と似ています。その結果、平均して #documents * percent / 100 個のドキュメントが返されます。

構文

Node.js

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

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

動作

ドキュメント モード

ドキュメント モードでは、指定された数のドキュメントがランダムな順序で取得されます。指定する数値は、負でない INT64 値にする必要があります。

たとえば、次のコレクションの場合:

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();

この例では、ランダムに選択された 1 つのドキュメントのみがランダムに返されます。

  {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'}

クライアントの例

ウェブ

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

パーセント モード

パーセント モードでは、各ドキュメントが percent の確率で返されるように指定します。ドキュメント モードとは異なり、ここでは順序はランダムではなく、既存のドキュメントの順序が保持されます。このパーセント入力は、0.0～1.0 の範囲の double 値である必要があります。

各ドキュメントは個別に選択されるため、出力は非決定的であり、平均して #documents * percent / 100 個のドキュメントが返されます。

たとえば、次のコレクションの場合:

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();

これにより、cities コレクションのドキュメントの（平均）50% の非決定的サンプルが生成されます。出力例を次に示します。

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

パーセント モードでは、各ドキュメントが選択される確率は同じであるため、ドキュメントが 1 つも返されない場合や、すべてのドキュメントが返される場合があります。

クライアントの例

ウェブ

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