نموذج

الوصف

تعرض هذه الدالة عيّنة غير قطعية من نتائج المرحلة السابقة.

هناك وضعان متاحان:

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