ตัวอย่าง

คำอธิบาย

แสดงผลตัวอย่างแบบไม่กำหนดจากผลลัพธ์ของขั้นตอนก่อนหน้า

มี 2 โหมดที่รองรับ ได้แก่

  • 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();
Go
// 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();

ในตัวอย่างนี้ ระบบจะแสดงผลเอกสารแบบสุ่มเพียง 1 รายการ

  { 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(...) ได้ 50% โดยเฉลี่ย

Node.js

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

ซึ่งจะแสดงผลตัวอย่างแบบไม่กำหนดของเอกสารจากคอลเล็กชัน cities ได้ 50% โดยเฉลี่ย ตัวอย่างผลลัพธ์ที่เป็นไปได้

  { 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();
Go
// Get a sample of on average 50% of the documents in the database
snapshot := client.Pipeline().
	Database().
	Sample(firestore.WithPercentage(0.5)).
	Execute(ctx)