תיאור
הפונקציה מחזירה דגימה לא דטרמיניסטית מהתוצאות של השלב הקודם.
יש שני מצבים נתמכים:
-
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) );
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()
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()
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();
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() )
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();
המשך
// Get a sample of 100 documents in a database results1, err := client.Pipeline().Database().Sample(firestore.WithDocLimit(100)).Execute(ctx).Results().GetAll() if err != nil { fmt.Fprintf(w, "GetAll failed: %v", err) return err } // Randomly shuffle a list of 3 documents results2, err := client.Pipeline(). Documents([]*firestore.DocumentRef{ client.Collection("cities").Doc("SF"), client.Collection("cities").Doc("NY"), client.Collection("cities").Doc("DC"), }). Sample(firestore.WithDocLimit(3)). Execute(ctx).Results().GetAll() if err != nil { fmt.Fprintf(w, "GetAll failed: %v", err) return err }
מצבים
מצב מסמכים
במצב 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, הסדר כאן לא אקראי, אלא שומר על הסדר הקיים במסמך. הקלט של האחוזים צריך להיות ערך כפול בין 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% מהמסמכים מהשלב collection(...).
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 }) );
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()
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()
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();
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() )
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();
המשך
// Get a sample of on average 50% of the documents in the database snapshot := client.Pipeline(). Database(). Sample(firestore.WithPercentage(0.5)). Execute(ctx)