Beispiel

Beschreibung

Gibt eine nicht deterministische Stichprobe aus den Ergebnissen der vorherigen Phase zurück.

Es werden zwei Modi unterstützt:

  • documents: Wählt zufällig n Dokumente aus.
  • percent: Wählt zufällig n Prozent der Dokumente aus.

Beispiele

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
}

Modi

Dokumentmodus

Im documents Modus werden bis zu n Dokumente zufällig aus der Eingabe ausgewählt, wobei jedes Dokument (zusammen mit der Reihenfolge der Dokumente) mit gleicher Wahrscheinlichkeit ausgewählt wird. Dazu muss Cloud Firestore alle Dokumente scannen und verarbeiten. Dies kann daher ein teurer Vorgang sein.

Beispiel für die folgende Sammlung:

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

Die Stichprobenphase im Dokumentmodus kann verwendet werden, um eine nicht deterministische Teilmenge der Ergebnisse aus dieser Sammlung abzurufen.

Node.js

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

In diesem Beispiel wird nur ein zufälliges Dokument zurückgegeben.

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

Wenn die angegebene Zahl größer als die Gesamtzahl der zurückgegebenen Dokumente ist, werden alle Dokumente in zufälliger Reihenfolge zurückgegeben.

Node.js

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

Das Ergebnis sind die folgenden Dokumente:

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

Prozentmodus

Im Modus percent werden n Prozent aller Dokumente aus der Eingabe ausgewählt. In dieser Phase werden also ungefähr # documents * percent / 100 Dokumente erzeugt. Wie im Modus documents sorgt Cloud Firestore dafür, dass jedes Dokument mit gleicher Wahrscheinlichkeit zurückgegeben wird. Dazu muss Cloud Firestore alle Dokumente scannen und verarbeiten. Dies kann daher ein teurer Vorgang sein, auch wenn das Ergebnis-Set klein ist.

Im Gegensatz zum Modus documents ist die Reihenfolge hier nicht zufällig, sondern die vorhandene Dokumentreihenfolge wird beibehalten. Diese Prozenteingabe muss ein Double-Wert zwischen 0.0 und 1.0 sein.

Beispiel für die folgende Sammlung:

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

Die Stichprobenphase im Prozentmodus kann verwendet werden, um durchschnittlich 50% der Dokumente aus der collection(...) Phase abzurufen.

Node.js

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

Das Ergebnis ist eine nicht deterministische Stichprobe von durchschnittlich 50% der Dokumente aus der Sammlung cities. Hier ein Beispiel für eine mögliche Ausgabe:

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

Im Prozentmodus haben alle Dokumente die gleiche Wahrscheinlichkeit, ausgewählt zu werden. Daher ist es möglich, dass keine oder alle Dokumente zurückgegeben werden.

Kundenbeispiele

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)