Method: projects.databases.documents.partitionQuery

لتقسيم استعلام عن طريق عرض مؤشرات الأقسام التي يمكن استخدامها لتشغيل الاستعلام بالتوازي. مؤشرات الأقسام المعروضة هي نقاط تقسيم يمكن استخدامها بواسطة document.runQuery كنقاط بداية/نهاية لنتائج طلب البحث.

طلب HTTP

POST https://firestore.googleapis.com/v1/{parent=projects/*/databases/*/documents}:partitionQuery

يستخدم عنوان URL بنية تحويل الترميز gRPC.

معلمات المسار

المَعلمات
parent

string

مطلوبة. اسم المورد الرئيسي. بالتنسيق: projects/{projectId}/databases/{databaseId}/documents. أسماء موارد المستندات غير مدعومة؛ حيث يمكن تحديد أسماء موارد قاعدة البيانات فقط.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "partitionCount": string,
  "pageToken": string,
  "pageSize": integer,

  // Union field query_type can be only one of the following:
  "structuredQuery": {
    object (StructuredQuery)
  }
  // End of list of possible types for union field query_type.

  // Union field consistency_selector can be only one of the following:
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
الحقول
partitionCount

string (int64 format)

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

على سبيل المثال، يمكن ضبط ذلك على عدد أقل من عدد طلبات البحث المتوازية المطلوب تنفيذها، أو عند تشغيل مهمة مسار بيانات، أقل بمقدار واحد من عدد العاملين أو مثيلات الحوسبة المتاحة.
pageToken

string

القيمة nextPageToken التي تم عرضها من استدعاء سابق إلى document.partitionQuery ويمكن استخدامه للحصول على مجموعة إضافية من النتائج. لا تتوفّر ضمانات بشأن الترتيب بين مجموعات النتائج. وبالتالي، يتطلب استخدام مجموعات متعددة من النتائج دمج مجموعات النتائج المختلفة.

على سبيل المثال، قد يكون ناتج طلبين تاليين يستخدمان pageToken في أحدهما:

  • المؤشر B، المؤشر M، المؤشر Q
  • المؤشر A، المؤشر U، المؤشر W

للحصول على مجموعة نتائج كاملة مرتَّبة وفقًا لنتائج طلب البحث المقدَّم في document.partitionQuery، يجب دمج مجموعات النتائج: المؤشر A، المؤشر B، المؤشر M، المؤشر Q، المؤشر U، المؤشر W
pageSize

integer

الحد الأقصى لعدد الأقسام المطلوب عرضها في هذه المكالمة، ويخضع ذلك إلى partitionCount.

على سبيل المثال، إذا كانت partitionCount = 10 وpageSize = 8، ستعرض عملية الاستدعاء الأولى لـ document.partitionQuery ما يصل إلى 8 أقسام وقيمة nextPageToken في حال توفُّر المزيد من النتائج. سيؤدي الاستدعاء الثاني إلى document.partitionQuery إلى عرض ما يصل إلى قسمَين، لإكمال إجمالي 10 أقسام محدّدة في partitionCount.
حقل الاتحاد query_type الاستعلام المطلوب تقسيمه. يمكن أن يكون الحقل "query_type" واحدًا فقط مما يلي:
structuredQuery

object (StructuredQuery)

طلب بحث مركبة. يجب أن يحدد طلب البحث المجموعة مع كل العناصر التابعة وأن يتم ترتيبه حسب الاسم تصاعديًا. لا تتوفّر الفلاتر الأخرى وعمليات ترتيب القيم حسب النتائج والإزاحة ومؤشرات البدء/النهاية.
حقل الاتحاد consistency_selector وضع التناسق لهذا الطلب. وفي حال تم ترك هذه السياسة بدون ضبط، سيتم ضبط الإعدادات التلقائية على تناسق قوي. يمكن أن يكون الحقل "consistency_selector" واحدًا فقط مما يلي:
readTime

string (Timestamp format)

يقرأ المستندات كما كانت في الوقت المحدَّد.

يجب أن يكون هذا الطابع الزمني بدقة ميكرو ثانية خلال الساعة الماضية، أو إذا تم تفعيل ميزة "استرداد نقطة زمنية"، يمكن أيضًا أن يكون طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام.

طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"

نص الاستجابة

الردّ على Firestore.PartitionQuery.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "partitions": [
    {
      object (Cursor)
    }
  ],
  "nextPageToken": string
}
الحقول
partitions[]

object (Cursor)

نتائج التقسيم. يمثل كل قسم نقطة تقسيم يمكن استخدامها بواسطة Document.runQuery كنقطة بداية أو نهاية لنتائج الاستعلام. يجب إجراء طلبات Docs.runQuery باستخدام طلب البحث نفسه المُقدَّم إلى طلب document.partitionQuery. سيتم ترتيب مؤشرات الأقسام بنفس الترتيب الذي تظهر به نتائج طلب البحث المقدَّم في Document.partitionQuery.

على سبيل المثال، إذا كان طلب document.partitionQuery يعرض مؤشرَي القسم A وB، سيؤدي تشغيل الاستعلامات الثلاثة التالية إلى عرض مجموعة النتائج الكاملة للاستعلام الأصلي:

  • استعلام، endAt A
  • استعلام، startAt A، endAt B
  • استعلام، startAt B

قد تشير النتيجة الفارغة إلى أنّ طلب البحث يحتوي على عدد قليل جدًا من النتائج التي لا يمكن تقسيمها، أو إلى أنّ طلب البحث غير متاح للتقسيم بعد.
nextPageToken

string

يشير هذا المصطلح إلى رمز مميّز للصفحة يمكن استخدامه لطلب مجموعة إضافية من النتائج، بما يصل إلى الرقم الذي يحدّده partitionCount في طلب document.partitionQuery. إذا كان هذا الحقل فارغًا، ليس هناك المزيد من النتائج.

نطاقات التفويض

يتطلب استخدام أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المصادقة.