Mẫu

Mô tả

Trả về một mẫu không xác định từ kết quả của giai đoạn trước.

Có 2 chế độ được hỗ trợ:

  • Chế độ DOCUMENTS cho phép lấy mẫu một số lượng tài liệu nhất định
    • Chế độ này tương tự như GoogleSQL.RESERVOIR ở chỗ nó xuất ra một mẫu có kích thước n, trong đó mọi mẫu có kích thước n đều có khả năng xảy ra như nhau.
  • Chế độ PERCENT cho phép lấy mẫu một tỷ lệ phần trăm tài liệu
    • Chế độ này tương tự như GoogleSQL.BERNOULLI ở chỗ mỗi tài liệu được chọn độc lập với xác suất percent bằng nhau. Điều này dẫn đến việc trung bình #documents * percent / 100 tài liệu được trả về.

Cú pháp

Node.js

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

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

Hành vi

Chế độ Tài liệu

Chế độ tài liệu truy xuất một số lượng tài liệu chỉ định sẵn theo thứ tự ngẫu nhiên. Số được chỉ định phải là giá trị INT64 không âm.

Ví dụ: đối với bộ sưu tập sau:

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

Bạn có thể dùng giai đoạn lấy mẫu ở chế độ tài liệu để truy xuất một tập hợp con không xác định của kết quả từ tập hợp này.

Node.js

const sampled = await db.pipeline()
    .collection("/cities")
    .sample(1)
    .execute();

Trong ví dụ này, chỉ có 1 tài liệu ngẫu nhiên được trả về.

  {name: 'New York City', state: 'New York'}

Nếu số được cung cấp lớn hơn tổng số tài liệu được trả về, thì tất cả tài liệu sẽ được trả về theo thứ tự ngẫu nhiên.

Node.js

const sampled = await db.pipeline()
    .collection("/cities")
    .sample(5)
    .execute();

Việc này sẽ dẫn đến các tài liệu sau:

  {name: 'New York City', state: 'New York'}
  {name: 'Chicago', state: 'Illinois'}
  {name: 'San Francisco', state: 'California'}

Ví dụ về ứng dụng

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)
);
test.firestore.js
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()
PipelineSnippets.swift

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()
DocSnippets.kt

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();
DocSnippets.java
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()
)
firestore_pipelines.py
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();
PipelineSnippets.java

Chế độ phần trăm

Ở chế độ phần trăm, mỗi tài liệu có một cơ hội percent cụ thể để được trả về. Không giống như chế độ tài liệu, thứ tự ở đây không phải là ngẫu nhiên mà sẽ giữ nguyên thứ tự tài liệu hiện có. Giá trị phần trăm đầu vào này phải là giá trị kép nằm trong khoảng từ 0.0 đến 1.0.

Vì mỗi tài liệu được chọn độc lập nên đầu ra không xác định và trung bình, #documents * percent / 100 tài liệu sẽ được trả về.

Ví dụ: đối với bộ sưu tập sau:

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

Bạn có thể dùng giai đoạn lấy mẫu ở chế độ phần trăm để truy xuất (trung bình) 50% tài liệu từ giai đoạn thu thập.

Node.js

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

Điều này sẽ dẫn đến một mẫu không xác định gồm (trung bình) 50% tài liệu từ bộ sưu tập cities. Sau đây là một kết quả có thể xảy ra.

  {name: 'New York City', state: 'New York'}
  {name: 'Chicago', state: 'Illinois'}

Ở chế độ phần trăm, vì mỗi tài liệu có cùng xác suất được chọn, nên có thể không có tài liệu nào hoặc tất cả tài liệu đều được trả về.

Ví dụ về ứng dụng

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 })
);
test.firestore.js
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()
PipelineSnippets.swift

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()
DocSnippets.kt

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();
DocSnippets.java
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()
)
firestore_pipelines.py
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();
PipelineSnippets.java