דוגמה

תיאור

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

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

  • ‫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)