Method: projects.databases.documents.runAggregationQuery

لتنفيذ طلب بحث عن تجميع.

بدلاً من عرض نتائج Document مثل Firestore.RunQuery، تسمح واجهة برمجة التطبيقات هذه بتشغيل عملية تجميع لإنتاج سلسلة من ملفات AggregationResult من جهة الخادم.

مثال على المستوى العالي:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

طلب HTTP

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

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

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

المَعلمات
parent

string

مطلوب. اسم المورد الرئيسي. بالتنسيق: projects/{projectId}/databases/{databaseId}/documents أو projects/{projectId}/databases/{databaseId}/documents/{document_path}. على سبيل المثال: projects/my-project/databases/my-database/documents أو projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

نص الطلب

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

تمثيل JSON 
{
  "explainOptions": {
    object (ExplainOptions)
  },

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

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "newTransaction": {
    object (TransactionOptions)
  },
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
الحقول
explainOptions

object (ExplainOptions)

هذه السمة اختيارية. شرح خيارات الاستعلام. وفي حال ضبطها، سيتم عرض إحصاءات إضافية لطلبات البحث. وإذا لم يكن الأمر كذلك، فسيتم عرض نتائج الاستعلام فقط.
حقل الاتحاد query_type. الاستعلام المطلوب تنفيذه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structuredAggregationQuery

object (StructuredAggregationQuery)

طلب تجميع.
حقل الاتحاد consistency_selector. يتم ضبط وضع الاتساق لطلب البحث تلقائيًا على الاتساق القوي. يمكن أن يكون consistency_selector واحدًا فقط مما يلي:
transaction

string (bytes format)

تنفيذ التجميع ضمن معاملة نشطة بالفعل.

القيمة هنا هي معرّف المعاملة مبهم لتنفيذ الاستعلام فيه.

سلسلة بترميز base64.
newTransaction

object (TransactionOptions)

بدء معاملة جديدة كجزء من طلب البحث، مع ضبط الإعداد التلقائي على القراءة فقط.

سيتم عرض معرِّف المعاملة الجديد كأول ردّ في مصدر البيانات.
readTime

string (Timestamp format)

لتنفيذ طلب البحث عند الطابع الزمني المحدّد.

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

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

نص الاستجابة

تمثّل هذه السمة الردّ على Firestore.RunAggregationQuery.

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

تمثيل JSON 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
الحقول
result

object (AggregationResult)

نتيجة تجميع واحدة.

لا تتوفّر هذه الميزة عند الإبلاغ عن التقدّم الجزئي.
transaction

string (bytes format)

المعاملة التي بدأت كجزء من هذا الطلب.

لا تظهر إلا في الاستجابة الأولى عندما يطلب الطلب بدء معاملة جديدة.

سلسلة بترميز base64.
readTime

string (Timestamp format)

وقت حساب النتيجة المجمّعة. وهذا يتزايد دائمًا بصورة رتيبة؛ في هذه الحالة، نضمن عدم تغيير نتيجة التجميع السابقة في ساحة مشاركات النتائج بين readTime وهذه النتيجة.

إذا لم يعرض طلب البحث أي نتائج، سيتم إرسال ردّ بـ readTime بدون result، ويمثّل ذلك وقت تنفيذ طلب البحث.

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

object (ExplainMetrics)

مقاييس شرح طلب البحث ولا تتوفّر هذه السمة إلا عند توفير RunAggregationQueryRequest.explain_options، ويتم إرسالها مرة واحدة فقط مع آخر ردّ في ساحة المشاركات.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

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

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

طلب البحث عن التجميع المنظَّم

طلب بحث Firestore لتشغيل تجميع على StructuredQuery

تمثيل JSON 
{
  "aggregations": [
    {
      object (Aggregation)
    }
  ],

  // 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.
}
الحقول
aggregations[]

object (Aggregation)

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

يتطلب:

  • ما لا يقل عن خمس تجميعات أو خمس مجموعات كحد أقصى لكل طلب بحث.
حقل الاتحاد query_type. الاستعلام الأساسي المطلوب تجميعه. يمكن أن يكون query_type واحدًا فقط مما يلي:
structuredQuery

object (StructuredQuery)

استعلام منظم متداخل.

التجميع

تحدد هذه السمة تجميعًا ينتج عنه نتيجة واحدة.

تمثيل JSON 
{
  "alias": string,

  // Union field operator can be only one of the following:
  "count": {
    object (Count)
  },
  "sum": {
    object (Sum)
  },
  "avg": {
    object (Avg)
  }
  // End of list of possible types for union field operator.
}
الحقول
alias

string

هذه السمة اختيارية. اسم اختياري للحقل لتخزين نتيجة التجميع فيه.

إذا لم يتم توفير الاسم، ستختار Firestore اسمًا تلقائيًا بالتنسيق field_<incremental_id++>. على سبيل المثال:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*)
OVER (
  ...
);

يصبح:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*) AS field_2
OVER (
  ...
);

يتطلب:

  • يجب أن يكون فريدًا على مستوى جميع الأسماء المستعارة للتجميع.
  • يجب الامتثال لقيود document field name.
حقل الاتحاد operator. تمثّل هذه السمة نوع التجميع المطلوب تنفيذه. يمكن أن يكون operator واحدًا فقط مما يلي:
count

object (Count)

عدد مجمّع السلع.
sum

object (Sum)

مجمّع السلع.
avg

object (Avg)

متوسط مجمّع السلع.

الإحصاء

عدد المستندات التي تطابق طلب البحث.

تعمل دالة التجميع COUNT(*) على المستند بأكمله، لذا لا تتطلب مرجعًا للحقل.

تمثيل JSON 
{
  "upTo": string
}
الحقول
upTo

string (Int64Value format)

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

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

ويتم تفسير القيمة "غير محدّد" على أنّها غير مشروطة.

مثال على المستوى العالي:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

يتطلب:

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

المجموع

مجموع قيم الحقل المطلوب.

  • سيتم تجميع القيم الرقمية فقط. يتم تخطّي جميع القيم غير الرقمية بما في ذلك NULL.

  • وإذا كانت القيم المجمّعة تحتوي على NaN، يتم عرض NaN. تتبع الرياضيات اللانهائية معايير IEEE-754.

  • إذا كانت مجموعة القيم المجمّعة فارغة، يتم عرض 0.

  • لعرض عدد صحيح 64 بت إذا كانت جميع الأرقام المجمّعة أعداد صحيحة ولم تتجاوز نتيجة المجموع. بخلاف ذلك، يتم عرض النتيجة على هيئة مضاعفة. تجدر الإشارة إلى أنّه حتى إذا كانت جميع القيم المجمّعة أعداد صحيحة، يتم عرض النتيجة كقيمة مزدوجة إذا لم تكن متوافقة مع عدد صحيح بعلامة 64 بت. وعند حدوث ذلك، ستفقد القيمة المعروضة الدقة.

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

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

object (FieldReference)

الحقل المطلوب تجميعه.

Avg

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

  • سيتم تجميع القيم الرقمية فقط. يتم تخطّي جميع القيم غير الرقمية بما في ذلك NULL.

  • وإذا كانت القيم المجمّعة تحتوي على NaN، يتم عرض NaN. تتبع الرياضيات اللانهائية معايير IEEE-754.

  • إذا كانت مجموعة القيم المجمّعة فارغة، يتم عرض NULL.

  • يتم دائمًا عرض النتيجة على شكل مزدوج.

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

object (FieldReference)

الحقل المطلوب تجميعه.

نتيجة التجميع

نتيجة حزمة واحدة من طلب تجميع Firestore.

مفاتيح aggregateFields هي نفسها لجميع النتائج في طلب البحث عن التجميع، على عكس طلبات البحث في المستندات التي يمكن أن تحتوي على حقول مختلفة لكل نتيجة.

تمثيل JSON 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
الحقول
aggregateFields

map (key: string, value: object (Value))

نتيجة دوال التجميع، مثل: COUNT(*) AS total_docs.

المفتاح هو alias المعيّن لدالة التجميع عند الإدخال، ويساوي حجم هذه الخريطة عدد دوال التجميع في الاستعلام.

عنصر يحتوي على قائمة بأزواج "key": value مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }