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 "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "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 "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "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

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

StructuredAggregationQuery

استعلام 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)

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

AggregationResult

نتيجة لمجموعة واحدة من استعلام تجميع 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" }