Contoh

Deskripsi

Menampilkan sampel non-deterministik dari hasil tahap sebelumnya.

Ada dua mode yang didukung:

  • Mode DOCUMENTS memungkinkan pengambilan sampel sejumlah dokumen
    • Mode ini mirip dengan GoogleSQL.RESERVOIR karena menghasilkan sampel berukuran n, dan sampel apa pun berukuran n memiliki probabilitas yang sama.
  • Mode PERCENT memungkinkan pengambilan sampel sejumlah persentase dokumen
    • Mode ini mirip dengan GoogleSQL.BERNOULLI karena setiap dokumen dipilih secara independen dengan probabilitas percent yang sama. Hal ini akan menghasilkan rata-rata #documents * percent / 100 dokumen yang ditampilkan.

Sintaksis

Node.js

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

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

Perilaku

Mode Documents

Mode documents mengambil sejumlah dokumen tertentu dalam urutan acak. Nomor yang ditentukan harus berupa nilai INT64 non-negatif.

Misalnya, untuk koleksi berikut:

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

Tahap sampel dalam mode documents dapat digunakan untuk mengambil sebagian hasil non-deterministik dari koleksi ini.

Node.js

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

Dalam contoh ini, hanya 1 dokumen yang akan ditampilkan secara acak.

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

Jika jumlah yang diberikan lebih besar daripada jumlah total dokumen yang ditampilkan, semua dokumen akan ditampilkan dalam urutan acak.

Node.js

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

Hasilnya akan berupa dokumen berikut:

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

Contoh klien

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 Percent

Dalam mode percent, setiap dokumen memiliki peluang percent tertentu untuk ditampilkan. Tidak seperti mode documents, urutan di sini tidak acak dan mempertahankan urutan dokumen yang sudah ada sebelumnya. Input persentase ini harus berupa nilai ganda antara 0.0 dan 1.0.

Karena setiap dokumen dipilih secara independen, output-nya bersifat non-deterministik dan berupa rata-rata, sehingga #documents * percent / 100 dokumen akan ditampilkan.

Misalnya, untuk koleksi berikut:

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

Tahap sampel dalam mode percent dapat digunakan untuk mengambil (rata-rata) 50% dokumen dari tahap koleksi.

Node.js

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

Hal ini akan menghasilkan sampel non-deterministik dari (rata-rata) 50% dokumen dari koleksi cities. Berikut salah satu kemungkinan output.

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

Dalam mode percent, karena setiap dokumen memiliki probabilitas yang sama untuk dipilih, bisa saja tidak ada dokumen yang ditampilkan atau justru semua dokumen ditampilkan.

Contoh klien

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