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ợ:

  • documents: chọn ngẫu nhiên n tài liệu.
  • percent: chọn ngẫu nhiên n phần trăm số tài liệu.

Ví dụ

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();
Bắt đầu
// 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
}

Chế độ

Chế độ Tài liệu

Chế độ documents chọn ngẫu nhiên tối đa n tài liệu từ dữ liệu đầu vào, trong đó mỗi tài liệu (cùng với thứ tự của tài liệu) đều có khả năng được chọn như nhau. Để đạt được điều này, Cloud Firestore vẫn cần quét và xử lý tất cả tài liệu, vì vậy, đây vẫn có thể là một thao tác tốn ké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 được trả về ngẫu nhiên.

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

Điều 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" }

Chế độ phần trăm

Chế độ percent cố gắng chọn n phần trăm trong số tất cả các tài liệu từ dữ liệu đầu vào. Điều này dẫn đến việc giai đoạn này tạo ra khoảng # documents * percent / 100 tài liệu. Giống như trong chế độ documents, Cloud Firestore đảm bảo rằng mỗi tài liệu đều có khả năng được trả về như nhau. Điều này đòi hỏi Cloud Firestore phải quét và xử lý tất cả các tài liệu, vì vậy, đây vẫn có thể là một thao tác tốn kém, ngay cả khi tập kết quả nhỏ.

Không giống như chế độ documents, thứ tự ở đây không phải là ngẫu nhiên mà thay vào đó, thứ tự này sẽ giữ nguyên thứ tự tài liệu hiện có. Giá trị phần trăm này phải là giá trị gấp đôi trong khoảng từ 0.0 đến 1.0.

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 collection(...).

Node.js

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

Thao tác này sẽ tạo ra 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 đề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 })
);
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();
Bắt đầu
// Get a sample of on average 50% of the documents in the database
snapshot := client.Pipeline().
	Database().
	Sample(firestore.WithPercentage(0.5)).
	Execute(ctx)