StructuredQuery

{
  "select": {
    object (Projection)
  },
  "from": [
    {
      object (CollectionSelector)
    }
  ],
  "where": {
    object (Filter)
  },
  "orderBy": [
    {
      object (Order)
    }
  ],
  "startAt": {
    object (Cursor)
  },
  "endAt": {
    object (Cursor)
  },
  "offset": integer,
  "limit": integer,
  "findNearest": {
    object (FindNearest)
  }
}

object (Projection)

مجموعة فرعية اختيارية من الحقول المطلوب عرضها.

ويكون هذا الإجراء بمثابة DocumentMask على المستندات التي يتم عرضها من طلب البحث. عند عدم ضبطها، تفترض أنّ المتصل يريد عرض جميع الحقول.

object (CollectionSelector)

المجموعات المطلوب البحث عنها.

object (Filter)

الفلتر المطلوب تطبيقه.

object (Order)

الترتيب الذي سيتم تطبيقه على نتائج الاستعلام.

تسمح Firestore للمتصلين بتقديم طلب كامل أو طلب جزئي أو عدم تقديم أي طلب على الإطلاق. في جميع الحالات، تضمن Firestore ترتيبًا مستقرًا من خلال القواعد التالية:

• يجب توفير السمة orderBy للإشارة إلى جميع الحقول المستخدَمة في فلتر عدم المساواة.
• يتم إلحاق جميع الحقول المطلوبة في orderBy ولكنها غير متوفّرة حاليًا بترتيب قاموسي لاسم الحقل.
• إذا لم يتم تحديد طلب في __name__، يتم إلحاقه تلقائيًا.

يتم إلحاق الحقول بنفس اتجاه الترتيب المستخدَم في الترتيب الأخير المحدَّد، أو بالحقل "ASCENDING" إذا لم يتم تحديد ترتيب. مثال:

• ORDER BY a يصبح ORDER BY a ASC, __name__ ASC
• ORDER BY a DESC يصبح ORDER BY a DESC, __name__ DESC
• WHERE a > 1 يصبح WHERE a > 1 ORDER BY a ASC, __name__ ASC
• WHERE __name__ > ... AND a > 1 يصبح WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC

object (Cursor)

بادئة محتملة لموضع معين في مجموعة النتائج لبدء طلب البحث.

يستند ترتيب مجموعة النتائج إلى عبارة ORDER BY في الاستعلام الأصلي.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

تم ترتيب نتائج طلب البحث هذا حسب (b ASC, __name__ ASC).

ويمكن أن تشير المؤشرات إلى الترتيب الكامل أو بادئة الموقع الجغرافي، ولكنّها لا يمكن أن تشير إلى حقول أكثر من الحقول المتوفّرة في ORDER BY المقدَّمة.

استمرارًا للمثال أعلاه، سيكون لإرفاق مؤشرات البدء التالية تأثير متفاوت:

• START BEFORE (2, /k/123): ابدأ الاستعلام قبل a = 1 AND b > 2 AND __name__ > /k/123 مباشرةً.
• START AFTER (10): بدء الاستعلام بعد a = 1 AND b > 10 مباشرةً

على عكس OFFSET الذي يتطلب فحص أول N نتيجة لتخطيها، يسمح مؤشر البدء ببدء الاستعلام في موضع منطقي. هذا الموضع ليس مطلوبًا لمطابقة نتيجة فعلية، سيتم مسحه للأمام من هذا الموضع للعثور على المستند التالي.

المتطلبات:

• لا يمكن أن يكون عدد القيم أكبر من عدد الحقول المحدّدة في عبارة ORDER BY.

object (Cursor)

بادئة محتملة لموضع معين في النتيجة التي يتم تعيينها لإنهاء طلب البحث في.

يشبه هذا العمود START_AT ولكن من خلاله يتحكّم في موضع النهاية بدلاً من موضع البدء.

المتطلبات:

• لا يمكن أن يكون عدد القيم أكبر من عدد الحقول المحدّدة في عبارة ORDER BY.

integer

عدد المستندات المطلوب تخطيها قبل عرض النتيجة الأولى.

ينطبق ذلك بعد القيود المحدَّدة في WHERE وSTART AT وEND AT، ولكن قبل عبارة LIMIT.

المتطلبات:

• يجب أن تكون القيمة أكبر من صفر أو مساوية له في حال تحديدها.

integer

تمثّل هذه السمة الحد الأقصى لعدد النتائج المطلوب عرضها.

ينطبق هذا الإعداد بعد جميع القيود الأخرى.

المتطلبات:

• يجب أن تكون القيمة أكبر من صفر أو مساوية له في حال تحديدها.

object (FindNearest)

اختياريّ. بحث محتمل عن الجيران الأقرب.

ينطبق بعد جميع الفلاتر والطلبات الأخرى.

للعثور على أقرب تضمينات متجهة لمتجه الاستعلام المحدد.