דוגמה

תיאור

הפונקציה מחזירה דגימה לא דטרמיניסטית מתוצאות השלב הקודם.

יש שני מצבים נתמכים:

  • מצב DOCUMENTS מאפשר דגימה של מספר מסוים של מסמכים
    • השיטה הזו דומה לשיטה GoogleSQL.RESERVOIR בכך שהיא מחזירה מדגם בגודל n, כאשר כל מדגם בגודל n אפשרי באותה מידה.
  • במצב PERCENT אפשר לדגום אחוז מסוים של מסמכים
    • המצב הזה דומה ל-GoogleSQL.BERNOULLI בכך שכל מסמך נבחר באופן עצמאי עם הסתברות שווה של percent. התוצאה היא #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();

בדוגמה הזו, רק מסמך אחד יוחזר באופן אקראי.

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

דוגמאות ללקוחות

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

מצב אחוזים

במצב אחוזים, לכל מסמך יש סיכוי percent מוגדר להיות מוחזר. בניגוד למצב 'מסמכים', הסדר כאן לא אקראי, אלא שומר על הסדר הקיים של המסמכים. הערך באחוזים צריך להיות מספר עשרוני בין 0.0 ל-1.0.

מכיוון שכל מסמך נבחר באופן עצמאי, הפלט לא דטרמיניסטי, ובממוצע יוחזרו #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();

התוצאה תהיה מדגם לא דטרמיניסטי של (בממוצע) 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
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