StructuredQuery

استعلام Firestore.

يتم تنفيذ مراحل الاستعلام بالترتيب التالي: 1. من 2. حيث 3. حدد 4. orderBy + startAt + endAt 5. الإزاحة 6. الحد

تمثيل JSON 
{
  "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)
  }
}
الحقول
select

object (Projection)

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

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

object (CollectionSelector)

المجموعات المطلوب الاستعلام عنها.
where

object (Filter)

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

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"
startAt

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.
endAt

object (Cursor)

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

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

يتطلب:

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

integer

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

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

يتطلب:

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

integer

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

يُطبق بعد كل القيود الأخرى.

يتطلب:

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

object (FindNearest)

هذه السمة اختيارية. عملية بحث محتملة من الجيران الأقرب.

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

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

توقّعات الميزانية

إسقاط حقول المستند المطلوب عرضها.

تمثيل JSON 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
الحقول
fields[]

object (FieldReference)

الحقول المطلوب عرضها.

إذا كانت فارغة، سيتم عرض جميع الحقول. لعرض اسم المستند فقط، استخدِم ['__name__'].

أداة اختيار المجموعة

مجموعة مختارات، مثل messages as m1.

تمثيل JSON 
{
  "collectionId": string,
  "allDescendants": boolean
}
الحقول
collectionId

string

معرّف المجموعة. وعند ضبط هذه السياسة، يتم فقط اختيار المجموعات التي تحمل هذا المعرّف.
allDescendants

boolean

وعند ضبط هذه السياسة على "خطأ"، يتم فقط اختيار المجموعات الثانوية المباشرة للسمة parent المحدّدة في العنصر RunQueryRequest الذي يتضمّن هذا العنصر. عند ضبط القيمة على "صحيح"، يتم اختيار كل المجموعات التابعة.

فلتر

فلتر

تمثيل JSON 
{

  // Union field filter_type can be only one of the following:
  "compositeFilter": {
    object (CompositeFilter)
  },
  "fieldFilter": {
    object (FieldFilter)
  },
  "unaryFilter": {
    object (UnaryFilter)
  }
  // End of list of possible types for union field filter_type.
}
الحقول
حقل الاتحاد filter_type. نوع الفلتر يمكن أن يكون filter_type واحدًا فقط مما يلي:
compositeFilter

object (CompositeFilter)

عامل تصفية مُركّب
fieldFilter

object (FieldFilter)

فلتر على حقل مستند.
unaryFilter

object (UnaryFilter)

فلتر يأخذ وسيطة واحدة بالضبط.

الفلتر المركّب

فلتر يدمج فلاتر أخرى متعددة باستخدام عامل التشغيل المحدد.

تمثيل JSON 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
الحقول
op

enum (Operator)

عامل دمج عوامل تصفية متعددة.
filters[]

object (Filter)

قائمة الفلاتر المطلوب دمجها

يتطلب:

  • هناك فلتر واحد على الأقل.

المؤثِّر

عامل تصفية مركب

تعدادات
OPERATOR_UNSPECIFIED غير محدَّد يجب عدم استخدام هذه القيمة.
AND يجب إدخال المستندات لاستيفاء جميع الفلاتر المدمجة.
OR يجب أن تستوفي المستندات فلترًا واحدًا على الأقل من الفلاتر المدمجة.

فلتر الحقل

فلتر على حقل معيّن

تمثيل JSON 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
الحقول
field

object (FieldReference)

الحقل الذي تريد الفلترة حسبه.
op

enum (Operator)

العامل المطلوب الفلترة حسبه.
value

object (Value)

القيمة المطلوب المقارنة بها.

المؤثِّر

عامل تصفية الحقل

تعدادات
OPERATOR_UNSPECIFIED غير محدَّد يجب عدم استخدام هذه القيمة.
LESS_THAN

قيمة field المحدّدة أقل من قيمة value المحدّدة.

يتطلب:

  • تأتي "field" في المرتبة orderBy.
LESS_THAN_OR_EQUAL

قيمة field المحدّدة أقل من أو تساوي value المحدَّد.

يتطلب:

  • تأتي "field" في المرتبة orderBy.
GREATER_THAN

قيمة field المحدّدة أكبر من قيمة value المحدّدة.

يتطلب:

  • تأتي "field" في المرتبة orderBy.
GREATER_THAN_OR_EQUAL

قيمة field المحدّدة أكبر من أو تساوي value المحدَّد.

يتطلب:

  • تأتي "field" في المرتبة orderBy.
EQUAL تساوي قيمة field المحدّدة قيمة value المحدّدة.
NOT_EQUAL

لا تساوي قيمة field المحدّدة قيمة value المحدّدة.

يتطلب:

  • ما مِن NOT_EQUAL أو NOT_IN أو IS_NOT_NULL أو IS_NOT_NAN أخرى.
  • تأتي field في المركز الأول في orderBy.
ARRAY_CONTAINS field المحدّد هو مصفوفة تحتوي على السمة value المحددة.
IN

تساوي قيمة field المحدّدة قيمة واحدة على الأقل في المصفوفة المحدّدة.

يتطلب:

  • قيمة value هي ArrayValue غير فارغ، ويخضع لحدود الفصل.
  • ما مِن فلاتر "NOT_IN" في طلب البحث نفسه.
ARRAY_CONTAINS_ANY

field المحدّد هو مصفوفة تتضمّن أيًّا من القيم في المصفوفة المحدّدة.

يتطلب:

  • قيمة value هي ArrayValue غير فارغ، ويخضع لحدود الفصل.
  • ما مِن فلاتر ARRAY_CONTAINS_ANY أخرى ضمن عملية الفصل نفسها.
  • ما مِن فلاتر "NOT_IN" في طلب البحث نفسه.
NOT_IN

ليست قيمة field في المصفوفة المحددة.

يتطلب:

  • هذه القيمة value هي قيمة ArrayValue غير فارغة تشتمل على 10 قيم كحدّ أقصى.
  • ما مِن OR أو IN أو ARRAY_CONTAINS_ANY أو NOT_IN أو NOT_EQUAL أو IS_NOT_NULL أو IS_NOT_NAN الأخرى.
  • تأتي field في المركز الأول في orderBy.

فلتر UnaryFilter

فلتر بمعامل واحد.

تمثيل JSON 
{
  "op": enum (Operator),

  // Union field operand_type can be only one of the following:
  "field": {
    object (FieldReference)
  }
  // End of list of possible types for union field operand_type.
}
الحقول
op

enum (Operator)

عامل التشغيل الأحادي المطلوب تطبيقه.
حقل الاتحاد operand_type. وسيطة الفلتر. يمكن أن يكون operand_type واحدًا فقط مما يلي:
field

object (FieldReference)

الحقل الذي تريد تطبيق عامل التشغيل عليه.

المؤثِّر

عامل تشغيل أحادي.

تعدادات
OPERATOR_UNSPECIFIED غير محدَّد يجب عدم استخدام هذه القيمة.
IS_NAN تساوي قيمة field المحدّدة NaN.
IS_NULL تساوي قيمة field المحدّدة NULL.
IS_NOT_NAN

لا تساوي قيمة field المحدّدة NaN.

يتطلب:

  • ما مِن NOT_EQUAL أو NOT_IN أو IS_NOT_NULL أو IS_NOT_NAN أخرى.
  • تأتي field في المركز الأول في orderBy.
IS_NOT_NULL

لا تساوي قيمة field المحدّدة NULL.

يتطلب:

  • عنوان NOT_EQUAL واحد أو NOT_IN أو IS_NOT_NULL أو IS_NOT_NAN
  • تأتي field في المركز الأول في orderBy.

طلب

طلب في حقل

تمثيل JSON 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
الحقول
field

object (FieldReference)

الحقل المطلوب الترتيب حسبه.
direction

enum (Direction)

الاتجاه الذي يجب الطلب وفقًا له. وتكون القيمة التلقائية هي ASCENDING.

الاتجاه

اتجاه الفرز.

تعدادات
DIRECTION_UNSPECIFIED غير محدَّد
ASCENDING تصاعدي.
DESCENDING تنازلي.

البحث الأقرب

إعداد بحث الجيران الأقرب.

تمثيل JSON 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
الحقول
vectorField

object (FieldReference)

مطلوب. حقل متّجه مفهرس للبحث عنه يمكن فقط عرض المستندات التي تحتوي على متجهات تتطابق أبعادها مع queryVector.
queryVector

object (Value)

مطلوب. متجه الاستعلام الذي نبحث عنه. يجب ألا يزيد طول الخط المتجه عن 2048.
distanceMeasure

enum (DistanceMeasure)

مطلوب. قياس المسافة المطلوب استخدامه، مطلوب.
limit

integer

مطلوب. عدد الجيران الأقرب المُراد إرجاعه. يجب أن يكون عددًا صحيحًا موجبًا لا يزيد عن 1000.

قياس المسافة

قياس المسافة المستخدم عند المقارنة بين المتجهات.

تعدادات
DISTANCE_MEASURE_UNSPECIFIED يجب عدم ضبطها.
EUCLIDEAN تقيس مسافة EUCLIDEAN بين المتجهات. راجِع الإقليدية لمزيد من المعلومات
COSINE تقارن المتجهات بناءً على الزاوية بينها، مما يسمح لك بقياس التشابه الذي لا يعتمد على حجم المتجهات. نوصي باستخدام DOT_PRODUCT مع وحدة متجهات تمت تسويتها بدلاً من مسافة COSINE، والتي تكون مكافئة رياضيًا بأداء أفضل. راجِع مقالة تشابه جيب التمام لمزيد من المعلومات.
DOT_PRODUCT يشبه جيب التمام ولكنه يتأثر بحجم المتجهات. راجِع Dot Product لمزيد من المعلومات.