لتشغيل استعلام تجميع.
بدلاً من عرض نتائج 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/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery
يستخدم عنوان URL بنية تحويل الترميز gRPC.
معلمات المسار
المَعلمات | |
---|---|
parent |
مطلوبة. اسم المورد الرئيسي. بالتنسيق: |
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "explainOptions": { object ( |
الحقول | |
---|---|
explainOptions |
اختياريّ. شرح خيارات الاستعلام. وفي حال ضبطها، سيتم عرض إحصاءات إضافية لطلبات البحث. إذا لم يكن مضمّنًا، سيتم عرض نتائج طلب البحث فقط. |
حقل الاتحاد query_type الاستعلام المراد تشغيله. يمكن أن يكون الحقل "query_type " واحدًا فقط مما يلي: |
|
structuredAggregationQuery |
استعلام تجميع. |
حقل الاتحاد consistency_selector يتم تعيين وضع التناسق للاستعلام بشكل افتراضي على التناسق القوي. يمكن أن يكون الحقل "consistency_selector " واحدًا فقط مما يلي: |
|
transaction |
ويمكنك تنفيذ التجميع ضمن معاملة نشطة حاليًا. القيمة هنا هي معرِّف المعاملة المبهم لتنفيذ الطلب. سلسلة بترميز base64. |
newTransaction |
تبدأ معاملة جديدة كجزء من طلب البحث، مع ضبطها تلقائيًا على "للقراءة فقط". سيظهر معرِّف المعاملة الجديد كأول ردّ في ساحة المشاركات. |
readTime |
ينفّذ الطلب في الطابع الزمني المحدّد. يجب أن يكون هذا الطابع الزمني بدقة ميكرو ثانية خلال الساعة الماضية، أو إذا تم تفعيل ميزة "استرداد نقطة زمنية"، يمكن أيضًا أن يكون طابعًا زمنيًا لدقيقة كاملة خلال آخر 7 أيام. طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
نص الاستجابة
الردّ على Firestore.RunAggregationQuery
.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "result": { object ( |
الحقول | |
---|---|
result |
هي نتيجة تجميع واحدة. غير موجود عند الإبلاغ عن التقدم الجزئي. |
transaction |
المعاملة التي بدأت كجزء من هذا الطلب لا يتوفّر هذا الخيار إلا عند الردّ الأول عندما تم طلب بدء معاملة جديدة. سلسلة بترميز base64. |
readTime |
الوقت الذي تم فيه احتساب النتيجة الإجمالية. هذه النتيجة تتزايد دائمًا بشكل رتيب، وفي هذه الحالة، تكون نتيجة التجميع السابقة في ساحة مشاركات النتائج مضمونة لعدم تغييرها بين إذا لم يعرض طلب البحث أي نتائج، سيتم إرسال ردّ يتضمّن طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
explainMetrics |
مقاييس لشرح طلبات البحث ولا تتوفّر هذه السمة إلا عند توفير السمة |
نطاقات التفويض
يتطلب استخدام أحد نطاقات OAuth التالية:
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المصادقة.
StructuredAggregationQuery
استعلام Firestore لتشغيل تجميع عبر StructuredQuery
.
تمثيل JSON |
---|
{ "aggregations": [ { object ( |
الحقول | |
---|---|
aggregations[] |
اختياريّ. سلسلة من التجميعات ليتم تطبيقها على نتائج المتطلبات:
|
حقل الاتحاد query_type الاستعلام الأساسي المطلوب التجميع عليه. يمكن أن يكون الحقل "query_type " واحدًا فقط مما يلي: |
|
structuredQuery |
الاستعلام المنظم المتداخل. |
التجميع
وتحدد عملية تجميع ينتج عنها نتيجة واحدة.
تمثيل JSON |
---|
{ "alias": string, // Union field |
الحقول | |
---|---|
alias |
اختياريّ. اسم اختياري للحقل لتخزين نتيجة التجميع فيه. وفي حال عدم توفيره، ستختار Firestore اسمًا تلقائيًا يكون بالتنسيق
يصبح:
المتطلبات:
|
حقل الاتحاد operator نوع التجميع المطلوب تنفيذه. يمكن أن يكون الحقل "operator " واحدًا فقط مما يلي: |
|
count |
عدد مجمّعي السلع |
sum |
مجمّع تجميع المجموع |
avg |
مجمّع سلع متوسط |
الإحصاء
عدد المستندات التي تطابق طلب البحث.
تعمل دالة التجميع COUNT(*)
على المستند بأكمله، لذا لا تتطلب مرجعًا للحقل.
تمثيل JSON |
---|
{ "upTo": string } |
الحقول | |
---|---|
upTo |
اختياريّ. قيد اختياري على الحد الأقصى لعدد المستندات المطلوب حسابها. يوفر هذا طريقة لتعيين حد أقصى لعدد المستندات المطلوب مسحها ضوئيًا، مما يقلل من وقت الاستجابة والتكلفة. يتم تفسير القيمة غير المحدّدة على أنّها بلا حدود. مثال عالي المستوى:
المتطلبات:
|
المجموع
مجموع قيم الحقل المطلوب.
سيتم تجميع القيم الرقمية فقط. يتم تخطّي جميع القيم غير الرقمية بما في ذلك
NULL
.وإذا كانت القيم المجمّعة تحتوي على
NaN
، سيتم عرضNaN
. تتبع رياضيات اللانهاية معايير IEEE-754.وإذا كانت مجموعة القيم المجمّعة فارغة، يتم عرض 0.
لعرض عدد صحيح 64 بت إذا كانت جميع الأرقام المجمّعة أعدادًا صحيحة ولم تتتجاوز نتيجة المجموع. وإلا، يتم عرض النتيجة كدالة مزدوجة. لاحظ أنه حتى إذا كانت جميع القيم المجمّعة أعدادًا صحيحة، يتم عرض النتيجة كمضاعفة إذا كان لا يمكن وضعها ضمن عدد صحيح موقَّع 64 بت. وعند حدوث ذلك، ستفقد القيمة التي تم إرجاعها الدقة.
عند حدوث تدفق أقل، يكون تجميع النقاط العائمة غير حتمية. هذا يعني أن تشغيل نفس الاستعلام بشكل متكرر بدون أي تغييرات على القيم الأساسية قد ينتج عنه نتائج مختلفة قليلاً في كل مرة. في هذه الحالات، يجب تخزين القيم كأعداد صحيحة فوق أرقام النقاط العائمة.
تمثيل JSON |
---|
{
"field": {
object ( |
الحقول | |
---|---|
field |
الحقل المطلوب التجميع عليه. |
Avg
متوسط قيم الحقل المطلوب.
سيتم تجميع القيم الرقمية فقط. يتم تخطّي جميع القيم غير الرقمية بما في ذلك
NULL
.وإذا كانت القيم المجمّعة تحتوي على
NaN
، سيتم عرضNaN
. تتبع رياضيات اللانهاية معايير IEEE-754.إذا كانت القيمة المجمّعة فارغة، يتم عرض
NULL
.يتم عرض النتيجة دائمًا في شكل مزدوج.
تمثيل JSON |
---|
{
"field": {
object ( |
الحقول | |
---|---|
field |
الحقل المطلوب التجميع عليه. |
AggregationResult
نتيجة لمجموعة واحدة من استعلام تجميع Firestore.
مفاتيح aggregateFields
هي نفسها لجميع النتائج في طلب بحث التجميع، على عكس طلبات بحث المستند التي يمكن أن تحتوي على حقول مختلفة لكل نتيجة.
تمثيل JSON |
---|
{
"aggregateFields": {
string: {
object ( |
الحقول | |
---|---|
aggregateFields |
نتيجة وظائف التجميع، مثل: المفتاح هو عنصر يحتوي على قائمة من أزواج |