آشنایی با عملکرد پُرسمان بااستفاده از «توضیح پُرسمان»

«توضیح پُرسمان» به شما امکان می‌دهد پُرسمان‌های Cloud Firestore را به باطن ارسال کنید و درعوض، آمار عملکرد دقیقی درباره اجرای پُرسمان باطن دریافت کنید. این عملکرد مانند عملیات EXPLAIN [ANALYZE] در بسیاری از سیستم‌های پایگاه داده رابطه‌ای عمل می‌کند.

درخواست‌های Query Explain را می‌توان بااستفاده از کتابخانه‌های کلاینت سرور Firestore ارسال کرد.

نتایج «توضیح پُرسمان» به شما کمک می‌کند نحوه اجرای پُرسمان‌هایتان را درک کنید و ناکارآمدی‌ها و مکان گلوگاه‌های احتمالی سمت سرور را به شما نشان می‌دهد.

توضیح پُرسمان:

• اطلاعات آماری درباره مرحله برنامه‌ریزی پُرسمان ارائه می‌دهد تا بتوانید نمایه‌های پُرسمان را اصلاح کنید و کارایی را افزایش دهید.
• استفاده از گزینه تجزیه‌وتحلیل به شما کمک می‌کند هزینه و عملکرد خود را براساس هر پُرسمان درک کنید و به شما امکان می‌دهد به‌سرعت الگوهای مختلف پُرسمان را تکرار کنید تا استفاده از آن‌ها را بهینه کنید.

آشنایی با گزینه‌های Query Explain: پیش‌فرض و تجزیه‌وتحلیل

عملیات «توضیح پُرسمان» را می‌توان بااستفاده از گزینه پیش‌فرض یا گزینه تحلیل انجام داد.

با گزینه پیش‌فرض، Query Explain پُرسمان را برنامه‌ریزی می‌کند، اما از مرحله اجرا رد می‌شود. با این کار، اطلاعات مرحله برنامه‌ریز برگردانده می‌شود. می‌توانید از این ویژگی برای بررسی اینکه پُرسمان نمایه‌های لازم را دارد و درک اینکه کدام نمایه‌ها استفاده می‌شوند استفاده کنید. این کار به شما کمک می‌کند تا برای مثال، تأیید کنید که یک پُرسمان خاص از نمایه ترکیبی استفاده می‌کند، به‌جای اینکه مجبور باشد در بسیاری از نمایه‌های مختلف تقاطع ایجاد کند.

با گزینه تجزیه‌وتحلیل، Query Explain هم پُرسمان را طرح‌ریزی می‌کند و هم آن را اجرا می‌کند. این کار همه اطلاعات برنامه‌ریز ذکرشده قبلی را به‌همراه آمار زمان اجرای پُرسمان برمی‌گرداند. این شامل اطلاعات صورت‌حساب پُرسمان به‌همراه اطلاعات آماری سطح سیستم درباره اجرای پُرسمان خواهد بود. می‌توانید از این ابزار برای آزمایش پیکربندی‌های مختلف پُرسمان و نمایه استفاده کنید تا هزینه و تأخیر آن‌ها را بهینه‌سازی کنید.

هزینه Query Explain چقدر است؟

وقتی از Query Explain با گزینه پیش‌فرض استفاده می‌کنید، هیچ عملیات نمایه‌سازی یا خواندنی انجام نمی‌شود. صرف‌نظر از پیچیدگی پُرسمان، یک عملیات خواندن محاسبه می‌شود.

وقتی از Query Explain با گزینه تجزیه‌وتحلیل استفاده می‌کنید، عملیات نمایه و خواندن انجام می‌شود، بنابراین هزینه پُرسمان طبق معمول از شما کسر می‌شود. هیچ هزینه اضافی‌ای برای فعالیت تجزیه‌وتحلیل وجود ندارد، فقط هزینه معمول برای پُرسمان اجراشده دریافت می‌شود.

استفاده از Query Explain با گزینه پیش‌فرض

می‌توانید از کتابخانه‌های مشتری برای ارسال درخواست گزینه پیش‌فرض استفاده کنید.

توجه داشته باشید که درخواست‌ها با IAM اصالت‌سنجی می‌شوند و از همان اجازه‌ها برای عملیات پُرسمان معمولی استفاده می‌کنند. سایر روش‌های اصالت‌سنجی، مانند Firebase Authentication، نادیده گرفته می‌شوند. برای اطلاعات بیشتر، راهنمای IAM برای کتابخانه‌های کارخواه سرور را ببینید.

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)"},
    ]
}

برای اطلاعات بیشتر، به مرجع گزارش «توضیح پُرسمان» مراجعه کنید.

استفاده از Query Explain با گزینه تجزیه‌وتحلیل

می‌توانید از کتابخانه‌های مشتری برای ارسال درخواست گزینه تجزیه‌وتحلیل استفاده کنید.

توجه داشته باشید که درخواست‌ها با IAM اصالت‌سنجی می‌شوند و از همان اجازه‌ها برای عملیات پُرسمان معمولی استفاده می‌کنند. سایر روش‌های اصالت‌سنجی، مانند Firebase Authentication، نادیده گرفته می‌شوند. برای اطلاعات بیشتر، راهنمای IAM برای کتابخانه‌های کارخواه سرور را ببینید.

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",
               }
    }

}

برای اطلاعات بیشتر، به مرجع گزارش «توضیح پُرسمان» مراجعه کنید.

تفسیر نتایج و انجام اصلاحات

بیایید به یک سناریوی نمونه نگاه کنیم که در آن فیلم‌ها را براساس ژانر و کشور تولید جستجو می‌کنیم.

برای توضیح، معادل این پُرسمان SQL را فرض کنید.

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

اگر از گزینه تجزیه‌وتحلیل استفاده کنیم، سنجه‌های برگردانده‌شده نشان می‌دهند که پُرسمان روی دو نمایه تک‌فیلدی، (category ASC, __name__ ASC) و (country ASC, __name__ ASC)، اجرا می‌شود. این ویژگی ۱۶۵۰۰ ورودی نمایه را اسکن می‌کند، اما فقط ۱۲۰۰ سند را برمی‌گرداند.

// 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",
               }
    }
}