نمونه

شرح

نمونه‌ای غیرقطعی از نتایج مرحله قبلی برمی‌گرداند.

دو حالت پشتیبانی‌شده وجود دارد:

  • 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();
پایتون
# 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()
)
جاوا
// 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"});

از مرحله نمونه در حالت درصد می‌توان برای بازیابی (به‌طور میانگین) ۵۰٪ از اسناد از مرحله collection(...) استفاده کرد.

Node.js

  const sampled = await db.pipeline()
    .collection("/cities")
    .sample({ percent: 0.5 })
    .execute();

این کار منجر به نمونه غیرقطعی (به‌طور میانگین) ۵۰٪ از اسناد مجموعه 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();
پایتون
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()
)
جاوا
// 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)