المكان

الوصف

يتم فلترة المستندات من المرحلة السابقة، ولا يتم عرض إلا المستندات التي يكون فيها الشرط true.

أمثلة

Web

let results;

results = await execute(db.pipeline().collection("books")
  .where(field("rating").equal(5))
  .where(field("published").lessThan(1900))
);

results = await execute(db.pipeline().collection("books")
  .where(and(field("rating").equal(5), field("published").lessThan(1900)))
);
Swift
var results: Pipeline.Snapshot

results = try await db.pipeline().collection("books")
  .where(Field("rating").equal(5))
  .where(Field("published").lessThan(1900))
  .execute()

results = try await db.pipeline().collection("books")
  .where(Field("rating").equal(5) && Field("published").lessThan(1900))
  .execute()

Kotlin

var results: Task<Pipeline.Snapshot>

results = db.pipeline().collection("books")
    .where(field("rating").equal(5))
    .where(field("published").lessThan(1900))
    .execute()

results = db.pipeline().collection("books")
    .where(Expression.and(field("rating").equal(5),
      field("published").lessThan(1900)))
    .execute()

Java

Task<Pipeline.Snapshot> results;

results = db.pipeline().collection("books")
    .where(field("rating").equal(5))
    .where(field("published").lessThan(1900))
    .execute();

results = db.pipeline().collection("books")
    .where(Expression.and(
        field("rating").equal(5),
        field("published").lessThan(1900)
    ))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import And, Field

results = (
    client.pipeline()
    .collection("books")
    .where(Field.of("rating").equal(5))
    .where(Field.of("published").less_than(1900))
    .execute()
)

results = (
    client.pipeline()
    .collection("books")
    .where(And(Field.of("rating").equal(5), Field.of("published").less_than(1900)))
    .execute()
)
Java
Pipeline.Snapshot results1 =
    firestore
        .pipeline()
        .collection("books")
        .where(field("rating").equal(5))
        .where(field("published").lessThan(1900))
        .execute()
        .get();

Pipeline.Snapshot results2 =
    firestore
        .pipeline()
        .collection("books")
        .where(and(field("rating").equal(5), field("published").lessThan(1900)))
        .execute()
        .get();
متابعة
results1, err := client.Pipeline().
	Collection("books").
	Where(firestore.FieldOf("rating").Equal(5)).
	Where(firestore.FieldOf("published").LessThan(1900)).
	Execute(ctx).Results().GetAll()
if err != nil {
	fmt.Fprintf(w, "GetAll failed: %v", err)
	return err
}

results2, err := client.Pipeline().
	Collection("books").
	Where(firestore.And(
		firestore.FieldOf("rating").Equal(5),
		firestore.FieldOf("published").LessThan(1900),
	)).
	Execute(ctx).Results().GetAll()
if err != nil {
	fmt.Fprintf(w, "GetAll failed: %v", err)
	return err
}

السلوك

مراحل متعددة

يمكن ربط مراحل where(...) متعددة معًا، ما يؤدي إلى عملها كتعبير and(...) في كل شرط.

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .where(field("location.country").equals("USA"))
  .where(field("population").greaterThan(500000))
  .execute();

يجب إجراء الفلترة استنادًا إلى or منطقية لشرطَين كمرحلة where(...) واحدة.

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .where(field("location.state").equals("NY").or(field("location.state").equals("CA")))
  .execute();

التعبيرات المعقّدة

يمكن أن يحتوي شرط الفلتر على شروط فلتر معقّدة تتضمّن تعبيرات وعوامل منطقية متداخلة بعمق. على سبيل المثال:

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .where(
    field("name").like("San%")
    .or(
      field("location.state").charLength().greaterThan(7)
      .and(field("location.country").equals("USA"))))

يتم فلترة /cities استنادًا إلى تعبير عادي، أو إذا كانت المدينة في USA وكان اسم الولاية طويلاً بما يكفي. يمكن تقديم أي تعبير كشرط، ولكن لن تتم مطابقة إلا التعبيرات التي تكون قيمتها true.

ترتيب المراحل

إنّ ترتيب المراحل مهم لأنّه يمكن أن يغيّر ترتيب تقييم طلب البحث. على سبيل المثال، طلب البحث:

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .limit(10)
  .where(field("location.country").equals("USA"))
  .execute();

لن يتم إجراء الفلترة إلا على location.country لمجموعة (عشوائية محتمَلة) من 10 مستندات، لأنّ مرحلة limit(...) السابقة تقيّد المستندات التي يتم تقديمها لمرحلة where(...). بناءً على ذلك، القاعدة الأساسية هي وضع مراحل where(...) في بداية طلب البحث قدر الإمكان.

وظيفة مشابهة لوظيفة HAVING:

يمكن أن تأتي مرحلة where(...) بعد أي مرحلة تغيّر مخطط المستندات، مثل select(...) أو aggregate(...)، وستشير إلى الحقول الناتجة من هاتَين المرحلتَين. بالنسبة إلى aggregate(...)، من المهم أن يكون شرط where(...) التالي الذي يشير إلى الحقول المتراكمة بمثابة شرط HAVING في نظام SQL نموذجي. على سبيل المثال:

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .aggregate({
    accumulators: [field("population").sum().as("total_population")],
    groups: ["location.state"]
  })
  .where(field("total_population").greaterThan(10000000))

يسمح بعرض الولايات التي تضم مدنًا يزيد عدد سكانها الإجمالي عن حجم معيّن.