متغیرهای اختیاری

می‌توانید یک Clause را در کوئری‌تان اختیاری کنید. مثلاً می‌توانید یک عبارت WHERE اختیاری بسازید که شامل یک متغیر SQL است؛ در این صورت اگر هیچ مقداری برای متغیر (در ویجت فیلتر یا از طریق URL) فرستاده نشود، کوئری همچنان اجرا می‌شود، گویی اصلاً Clause WHERE وجود نداشته است.

برای اختیاری کردن یک متغیر در کوئری Native، کل عبارت حاوی {% raw %}{{variable}}{% endraw %} را داخل کروشه‌های دوتایی [[ .. ]] قرار دهید. اگر کاربر در ویجت فیلتر برای variable مقداری وارد کند، متابیس آن Clause را در Template نهایی قرار می‌دهد؛ در غیر این صورت، متابیس Clause را نادیده می‌گیرد و کوئری را طوری اجرا می‌کند که انگار آن قسمت اصلاً در کوئری نبوده است.

در مثال زیر، اگر هیچ مقداری برای cat داده نشود، کوئری همهٔ ردیف‌های جدول products را برمی‌گرداند. اما اگر cat مقداری مانند "Widget" داشته باشد، فقط ردیف‌هایی را می‌آورد که دسته‌بندی آن‌ها Widget است:

{% raw %}
SELECT
  count(*)
FROM
  products
[[WHERE category = {{cat}}]]
{% endraw %}

SQL شما باید بدون Clause اختیاری داخل [[ ]] هم معتبر باشد

باید مطمئن شوید وقتی هیچ مقداری برای متغیر موجود در Clause براکت‌دار ارسال نمی‌شود، SQL شما همچنان معتبر است.

مثلاً اگر کلمهٔ WHERE را از داخل براکت‌ها حذف کنید، وقتی مقداری برای cat وجود نداشته باشد به خطا می‌خورید:

-- این کوئری خطا خواهد داد:
{% raw %}
SELECT
  count(*)
FROM
  products
WHERE
  [[category = {{cat}}]]
{% endraw %}

چون وقتی مقداری برای cat داده نشود، متابیس تلاش می‌کند کوئری‌ای شبیه این را اجرا کند:

SELECT
  count(*)
FROM
  products
WHERE

که یک کوئری معتبر SQL نیست. در عوض، کل عبارت WHERE را داخل [[ ]] قرار دهید:

{% raw %}
SELECT
  count(*)
FROM
  products
[[WHERE
  category = {{cat}}]]
{% endraw %}

وقتی هیچ مقداری برای cat وجود نداشته باشد، متابیس همچنان یک کوئری معتبر اجرا می‌کند:

{% raw %}
SELECT
  count(*)
FROM
  products
{% endraw %}

هنگام استفاده از چند Clause اختیاری به حداقل یک WHERE نیاز دارید

برای استفاده از چند Clause اختیاری، باید حداقل یک Clause WHERE معمولی داشته باشید و بعد از آن Clauseهای اختیاری را قرار دهید که هرکدام با AND شروع می‌شوند:

{% raw %}
SELECT
  count(*)
FROM
  products
WHERE
  TRUE
  [[AND id = {{id}}]]
  [[AND {{category}}]]
{% endraw %}

Clause آخر از یک Field filter استفاده می‌کند (توجه کنید که در عبارت AND نام ستونی وجود ندارد). هنگام استفاده از Field filter باید ستون را از کوئری حذف کنید و به‌جای آن متغیر را در سایدبار Map کنید.

متغیرهای اختیاری در MongoDB

اگر از MongoDB استفاده می‌کنید، می‌توانید Clauseها را به این شکل اختیاری کنید:

{% raw %}
[
    [[{
        $match: {category: {{cat}}}
    },]]
    {
        $count: "Total"
    }
]
{% endraw %}

یا با چند فیلتر اختیاری:

{% raw %}
[
    [[{ $match: {{cat}} },]]
    [[{ $match: { price: { "$gt": {{minprice}} } } },]]
    {
        $count: "Total"
    }
]
{% endraw %}

تنظیم مقادیر پیش‌فرض پیچیده در کوئری

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

WHERE column = [[ {% raw %}{{ your_parameter }}{% endraw %} --]] your_default_value

این کامنت هر وقت مقداری به your_parameter بدهید «فعال» می‌شود.

این الگو زمانی مفید است که مقدار پیش‌فرض پیچیده باشد (مثلاً زمانی که مقدار پیش‌فرض یک تابعی مثل CURRENT_DATE است). در این مثال PostgreSQL، مقدار پیش‌فرض یک فیلتر Date با استفاده از CURRENT_DATE روی تاریخ جاری تنظیم می‌شود:

{% raw %}
SELECT
  *
FROM
  orders
WHERE
  DATE(created_at) = [[ {{dateOfCreation}} --]] CURRENT_DATE
{% endraw %}

اگر مقداری برای متغیر بفرستید، Clause WHERE اجرا می‌شود و سینتکس کامنت باعث می‌شود مقدار پیش‌فرض CURRENT_DATE عملاً کامنت شود.

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