דוגמה

תיאור

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

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

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