ตัวอย่าง

คำอธิบาย

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

โหมดที่รองรับมี 2 โหมด ดังนี้

  • DOCUMENTS ช่วยให้สุ่มตัวอย่างเอกสารตามจำนวนที่กำหนดได้
    • โหมดนี้คล้ายกับ GoogleSQL.RESERVOIR ตรงที่เอาต์พุตเป็นตัวอย่าง ขนาด n โดยที่ตัวอย่างขนาด n ใดๆ ก็เป็นไปได้เท่าๆ กัน
  • โหมด PERCENT ช่วยให้สุ่มตัวอย่างเอกสารเป็นเปอร์เซ็นต์ได้
    • โหมดนี้คล้ายกับ GoogleSQL.BERNOULLI ตรงที่เอกสารแต่ละฉบับจะได้รับการเลือกอย่างอิสระโดยมีความน่าจะเป็นเท่ากันที่ percent ซึ่งส่งผลให้ระบบแสดงเอกสาร #documents * percent / 100 รายการโดยเฉลี่ย

ไวยากรณ์

Node.js

  const sampled = await db.pipeline()
    .database()
    .sample(50)
    .execute();

  const sampled = await db.pipeline()
    .database()
    .sample({ percent: 0.5 })
    .execute();

พฤติกรรม

โหมดเอกสาร

โหมดเอกสารจะดึงข้อมูลเอกสารตามจำนวนที่ระบุในลำดับแบบสุ่ม หมายเลขที่ระบุต้องเป็นค่า INT64 ที่ไม่ใช่ค่าลบ

ตัวอย่างเช่น สำหรับคอลเล็กชันต่อไปนี้

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'}

ตัวอย่างไคลเอ็นต์

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();

โหมดเปอร์เซ็นต์

ในโหมดเปอร์เซ็นต์ เอกสารแต่ละรายการจะมีpercentโอกาสที่จะแสดง ซึ่งต่างจากโหมดเอกสารตรงที่ลำดับในที่นี้ไม่ได้สุ่ม แต่จะ รักษาลำดับเอกสารที่มีอยู่ก่อนแล้ว อินพุตเปอร์เซ็นต์นี้ต้อง เป็นค่าแบบ Double ระหว่าง 0.0 ถึง 1.0

เนื่องจากระบบจะเลือกเอกสารแต่ละรายการแยกกัน เอาต์พุตจึงไม่แน่นอนและโดยเฉลี่ยแล้วระบบจะแสดงเอกสาร #documents * percent / 100 รายการ

ตัวอย่างเช่น สำหรับคอลเล็กชันต่อไปนี้

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% ของเอกสารจากขั้นตอนการรวบรวม

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();