فهم أداء طلبات البحث باستخدام شرح طلب البحث

يتيح لك "شرح الاستعلام" إرسال Cloud Firestore طلب بحث إلى الخلفيّة والحصول على إحصاءات أداء تفصيلية عن تنفيذ طلبات البحث في الخلفية. تعمل هذه العملية مثل عملية EXPLAIN [ANALYZE] في العديد من أنظمة قواعد البيانات الارتباطية.

يمكن إرسال طلبات شرح طلبات البحث باستخدام مكتبات برامج خادم Firestore.

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

شرح طلب البحث:

• توفّر الأداة إحصاءات حول مرحلة التخطيط لطلبات البحث لتتمكن من تعديل فهارس طلبات البحث وتعزيز الفعالية.
• يساعدك استخدام خيار "التحليل" في فهم التكلفة والأداء على أساس كل طلب بحث، كما يتيح لك التنقّل بسرعة بين أنماط طلبات البحث المختلفة لتحسين استخدامها.

ملاحظة: تتوافق ميزة "شرح طلب البحث" مع طلبات البحث التي تتضمّن استطلاعات. طلبات البحث عن البث غير متاحة بعد.

التعرّف على خيارات "شرح الطلب": الإعداد التلقائي والتحليل

يمكن تنفيذ عمليات "شرح طلب البحث" باستخدام الخيار تلقائي أو تحليل.

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

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

ما هي تكلفة ميزة "شرح طلب البحث"؟

عند استخدام ميزة "شرح الطلب" مع الخيار التلقائي، لا يتم تنفيذ أي عمليات فهرسة أو قراءة. بغض النظر عن تعقيد طلب البحث، يتم تحصيل رسوم عملية قراءة واحدة.

عند استخدام ميزة "شرح الاستعلام" مع خيار "التحليل"، يتم تنفيذ عمليات الفهرسة والقراءة، وبالتالي يتم تحصيل رسوم منك مقابل الاستعلام كالمعتاد. لا يتم تحصيل أي رسوم إضافية مقابل نشاط التحليل، بل يتم فقط تحصيل الرسوم المعتادة مقابل الطلب الذي يتم تنفيذه.

استخدام ميزة "شرح الطلب" مع الخيار التلقائي

يمكنك استخدام مكتبات العملاء لإرسال طلب خيار تلقائي.

تجدر الإشارة إلى أنّه تتم مصادقة الطلبات من خلال "إدارة الهوية وإمكانية الوصول" (IAM) باستخدام الأذونات نفسها لعمليات طلبات البحث العادية. ويتم تجاهل تقنيات المصادقة الأخرى، مثل Firebase Authentication. لمزيد من المعلومات، يُرجى الاطّلاع على الدليل حول إدارة الهوية وإمكانية الوصول لمكتبات عملاء الخادم.

Java (المشرف)

Query q = db.collection("col").whereGreaterThan("a", 1);
ExplainOptions options = ExplainOptions.builder().build();

ExplainResults<QuerySnapshot> explainResults = q.explain(options).get();
ExplainMetrics metrics = explainResults.getMetrics();
PlanSummary planSummary = metrics.getPlanSummary();

    

عقدة (المشرف)

const q = db.collection('col').where('country', '=', 'USA');
const options = { analyze : 'false' };

const explainResults = await q.explain(options);

const metrics = explainResults.metrics;
const plan = metrics.planSummary;

    

يعتمد التنسيق الدقيق للردّ على بيئة التنفيذ. يمكن تحويل النتائج التي تم عرضها إلى تنسيق JSON. على سبيل المثال:

{
    "indexes_used": [
        {"query_scope": "Collection", "properties": "(category ASC, __name__ ASC)"},
        {"query_scope": "Collection", "properties": "(country ASC, __name__ ASC)"},
    ]
}

لمزيد من المعلومات، اطّلِع على مرجع تقرير "شرح الطلب".

استخدام ميزة "شرح طلب البحث" مع خيار "التحليل"

يمكنك استخدام مكتبات العملاء لإرسال طلب خيار التحليل.

يُرجى العِلم أنّه تتم مصادقة الطلبات باستخدام "إدارة الهوية وإمكانية الوصول"، وذلك باستخدام الأذونات نفسها لعمليات طلب البحث العادية. ويتم تجاهل تقنيات المصادقة الأخرى، مثل Firebase Authentication. لمزيدٍ من المعلومات، يُرجى الاطّلاع على الدليل بشأن إدارة الهوية وإمكانية الوصول لمكتبات عملاء الخوادم.

ملاحظة: يتم تحليل تنفيذ طلب بحث واحد في كل مرة، وبالتالي، قد تختلف نتائج توقيت طلب البحث من طلب إلى آخر. يمكن أن تساعدك الأداة في رصد القصور الهيكلي الملحوظ، ولكنّها لا تهدف إلى تقديم إحصاءات مجمّعة عن أداء طلبات البحث.

Java (المشرف)

Query q = db.collection("col").whereGreaterThan("a", 1);

ExplainOptions options = ExplainOptions.builder().setAnalyze(true).build();

ExplainResults<QuerySnapshot> explainResults = q.explain(options).get();

ExplainMetrics metrics = explainResults.getMetrics();
PlanSummary planSummary = metrics.getPlanSummary();
List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
ExecutionStats stats = metrics.getExecutionStats();

    

العقدة (المشرف)

const q = db.collection('col').where('country', '=', 'USA');

const options = { analyze : 'true' };

const explainResults = await q.explain(options);

const metrics = explainResults.metrics;
const plan = metrics.planSummary;
const indexesUsed = plan.indexesUsed;
const stats = metrics.executionStats;

    

يعرض المثال التالي عنصر stats الذي تم إرجاعه بالإضافة إلى planInfo. يعتمد التنسيق الدقيق للردّ على بيئة التنفيذ. المثال على الاستجابة بتنسيق JSON

{
    "resultsReturned": "5",
    "executionDuration": "0.100718s",
    "readOperations": "5",
    "debugStats": {
               "index_entries_scanned": "95000",
               "documents_scanned": "5"
               "billing_details": {
                     "documents_billable": "5",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }

}

لمزيد من المعلومات، اطّلِع على مرجع تقرير "شرح الطلب".

تفسير النتائج وإجراء التعديلات

لنلقِ نظرة على مثال على سيناريو نبحث فيه عن الأفلام حسب النوع و بلد الإنتاج.

ملاحظة: تم تصميم ميزة "شرح طلبات البحث" لإجراء تحليلات ظرفية مفيدة، وسيتم تطوير تنسيق التقارير لزيادة سهولة القراءة والفهم إلى أقصى حد، وليس لزيادة ملاءمة المعالجة الآلية. من المتوقّع أن تتغيّر بعض المقاييس مع تطور Cloud Firestore (أي قد تتم إضافة المقاييس أو إزالتها أو تعديلها) ولا تندرج ضمن سياسة الإيقاف النهائي نفسها التي تنطبق على واجهات برمجة تطبيقات Cloud Firestore الأخرى. للحصول على مزيد من المعلومات، يُرجى الاطّلاع على مرجع تقرير "شرح طلب البحث".

للتوضيح، افترض مكافئ استعلام SQL هذا.

SELECT *
FROM /movies
WHERE category = 'Romantic' AND country = 'USA';

إذا استخدمنا خيار التحليل، ستعرض المقاييس المعروضة عمليات تنفيذ طلب البحث على فهارس ذات حقل واحد، هما (category ASC, __name__ ASC) و(country ASC, __name__ ASC). وهي تفحص 16,500 إدخال في الفهرس، ولكنها تعرِض 1,200 مستند فقط.

// Output query planning info
{
    "indexes_used": [
        {"query_scope": "Collection", "properties": "(category ASC, __name__ ASC)"},
        {"query_scope": "Collection", "properties": "(country ASC, __name__ ASC)"},
    ]
}

// Output query status
{
    "resultsReturned": "1200",
    "executionDuration": "0.118882s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "16500",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

لتحسين أداء تنفيذ طلب البحث، يمكنك إنشاء فهرس مركّب (category ASC, country ASC, __name__ ASC) مغطى بالكامل.

عند تنفيذ طلب البحث باستخدام خيار التحليل مرة أخرى، يمكننا ملاحظة أنّه تم اختيار ملف الفهرس الذي تم إنشاؤه حديثًا لهذا الطلب، ويتم تنفيذ طلب البحث بشكل أسرع وبكفاءة أكبر.

// Output query planning info
{
    "indexes_used": [
        {"query_scope": "Collection", "properties": "(category ASC, country ASC,  __name__ ASC)"}
    ]
}

// Output query stats
{
    "resultsReturned": "1200",
    "executionDuration": "0.026139s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "1200",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}