Snippets

Snippetها تکه‌کدهای قابل‌استفادهٔ مجدد از SQL یا سایر کوئری‌های Native هستند. هر کسی که به ویرایشگر Native دسترسی داشته باشد می‌تواند Snippet بسازد یا ویرایش کند و این Snippetها برای همهٔ افرادی که کوئری Native می‌نویسند در دسترس خواهند بود.

مثلاً اگر شما مرتباً کوئری‌هایی می‌نویسید که چند جدول را به هم Join می‌کند، می‌توانید SQL مربوط به آن Joinها را به‌صورت یک Snippet ذخیره کنید تا خودتان (و بقیهٔ تیم) بتوانید همان کد را در چند سؤال مختلف استفاده کنید.

می‌توانید با Snippetها KPIهای استاندارد یا فیلترهای ثابت را با SQL تعریف کنید، مشابه کاری که با Metricها و Segmentها در Query builder انجام می‌دهید؛ مثل این‌که «Revenue» دقیقاً چطور محاسبه می‌شود یا «کاربر فعال» چه تعریفی دارد.

همچنین می‌توانید مجموعه‌ای از فیلترهای قابل‌استفادهٔ مجدد برای سؤال‌های SQL را هم به‌صورت Snippet ذخیره کنید.

ساخت Snippet

در ویرایشگر Native:

1. با کلیک روی + New > SQL query یا + New > Native query در بالا سمت راست، ویرایشگر Native را باز کنید.

2. مقداری SQL (یا کوئری Native) بنویسید و بخشی از کد را که می‌خواهید بعداً مجدد استفاده کنید انتخاب (Highlight) کنید. لازم نیست این بخش کل کوئری باشد. مثلاً می‌توانید این بخش را انتخاب کنید:

   orders AS o
   LEFT JOIN products AS p ON o.product_id = p.id
   WHERE p.category = {% raw %}{{category}}{% endraw %}
   

   داخل یک Snippet می‌توانید از این موارد استفاده کنید:

   • پارامترهای SQL مثل {% raw %}{{param}}{% endraw %}،
   • ارجاع به Snippetهای دیگر مثل {% raw %}{{snippet: orders}}{% endraw %} (متابیس جلوی Reference حلقه‌ای را می‌گیرد)،
   • ارجاع به سؤال‌ها یا مدل‌های ذخیره‌شده، مثل {% raw %}{{#123-orders-model}}{% endraw %}.

3. روی بخش انتخاب‌شده راست‌کلیک کنید و گزینهٔ Save as snippet را بزنید.

   

4. برای Snippet نام و توضیح بگذارید. نام Snippet باید یکتا باشد (حتی برای Snippetهای آرشیوشده).

5. ذخیره کنید.

همچنین می‌توانید از نوار کناری Snippet هم Snippet جدید بسازید:

1. ویرایشگر Native را با + New > SQL query یا + New > Native query باز کنید.
2. با کلیک روی دکمهٔ Snippets بالای ادیتور، نوار کناری Snippet را باز کنید.
3. کدی را که می‌خواهید به‌صورت Snippet ذخیره کنید وارد کنید.
4. ذخیره کنید.

استفاده از Snippet

می‌توانید یک Snippet ذخیره‌شده را داخل کوئری‌تان وارد کنید؛ این کار یک ارجاع به شکل {% raw %}{{snippet: }}{% endraw %} در کوئری قرار می‌دهد:

SELECT
  *
FROM
 {% raw %}{{snippet: orders and products}}{% endraw %}

برای اضافه کردن Snippet به کوئری، کافی است شروع کنید به تایپ {% raw %}{{snippet: }}{% endraw %}؛ متابیس لیستی از Snippetهای قابل‌دسترسی را به‌صورت Autocomplete نمایش می‌دهد.

متابیس روی فاصله‌ها در ارجاع Snippet حساس است؛ یعنی باید به‌صورت {% raw %}{{snippet: Products}}{% endraw %} بنویسید؛ بدون فاصله بین {% raw %}{{{% endraw %} و snippet و با یک فاصله بین : و نام Snippet.

هنگام اجرای کوئری، متابیس در پشت صحنه ارجاع Snippet را با SQL آن Snippet جایگزین می‌کند.

همچنین می‌توانید Snippet را از خود نوار کناری انتخاب و وارد کوئری کنید:

1. با کلیک روی دکمهٔ Snippets بالای ادیتور، نوار کناری Snippet را باز کنید.
2. دنبال Snippet مورد نظر بگردید (Search). نتایج فقط شامل Snippetهایی می‌شوند که شما اجازهٔ دیدن آن‌ها را دارید.
3. روی Snippet مورد نظر بروید و روی فلش کنار نام Snippet کلیک کنید تا Snippet در کوئری وارد شود.

اگر در Snippet از alias استفاده کرده‌اید، در بقیهٔ کوئری باید از همان alias استفاده کنید. مثلاً اگر در Snippet نوشته باشید products AS p، در خارج از Snippet باید p.column_name را برای اشاره به ستون‌های آن جدول استفاده کنید.

پیش‌نمایش کوئری حاوی Snippet

متابیس در ادیتور، Snippet را به‌صورت Reference نمایش می‌دهد و نسخهٔ نهایی SQL را (که در آن Snippet باز شده است) نشان نمی‌دهد. برای دیدن کوئری نهایی‌ای که برای دیتابیس ارسال می‌شود، روی آیکون Eye بالای ادیتور کلیک کنید.

ویرایش Snippet

ویرایش Snippet راه قدرتمندی است برای اعمال تغییر روی تعداد زیادی سؤال به‌طور هم‌زمان. مثلاً اگر SQL مربوط به دریافت دادهٔ کاربران از جدول‌های X، Y و Z را به‌صورت Snippet با نام User Data ذخیره کرده‌اید و بعداً لازم شد روش دریافت این داده‌ها را (مثلاً با اضافه‌کردن یک ستون یا جدول دیگر) تغییر دهید، کافی است خود Snippet را به‌روزرسانی کنید تا همهٔ سؤال‌هایی که از آن Snippet استفاده می‌کنند، خودبه‌خود به‌روزرسانی شوند.

برای ویرایش Snippet:

1. با کلیک روی آیکون Snippet بالای ادیتور، نوار کناری Snippet را باز کنید.

2. Snippet مورد نظر را جست‌وجو کنید (فقط Snippetهایی را می‌بینید که اجازهٔ ویرایش آن‌ها را دارید).

3. روی فلش کنار نام Snippet کلیک کنید و گزینهٔ Edit را بزنید.

   در این‌جا می‌توانید کد، نام و توضیح Snippet را تغییر دهید.

• تغییر نام Snippet: با تغییر نام، همهٔ کوئری‌هایی که از آن Snippet استفاده می‌کنند، ارجاع‌شان به نام جدید به‌روزرسانی می‌شود. این کار سؤال‌های موجود را نمی‌شکند، اما Snippetهای دیگری را که این Snippet را صدا می‌زنند ممکن است خراب کند (چون نام قدیمی دیگر وجود ندارد).

• تغییر کد Snippet: این‌جا همان‌جایی است که باید خیلی مراقب باشید؛ اگر کد اشتباه در Snippet ذخیره کنید، تمام سؤال‌هایی که از آن Snippet استفاده می‌کنند می‌شکنند. قبل از ذخیرهٔ تغییرات، حتماً کد را تست کنید.

آرشیو کردن Snippetها

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

وقتی یک Snippet را آرشیو می‌کنید:

• دیگر در لیست Autocomplete Snippet ظاهر نمی‌شود،
• در لیست Snippetهای نوار کناری هم نمایش داده نمی‌شود،
• اما هیچ‌کدام از سؤال‌هایی که از آن Snippet استفاده کرده‌اند خراب نمی‌شوند و همچنان کار می‌کنند.

برای آرشیو کردن Snippet:

1. نوار کناری Snippet را با کلیک روی آیکون Snippet باز کنید.
2. Snippet مورد نظر را جست‌وجو کنید.
3. روی فلش کنار نام Snippet کلیک و گزینهٔ Edit را بزنید.
4. روی Archive کلیک کنید.

می‌توانید از پایینِ نوار کناری Snippet، روی دکمهٔ Archived کلیک کنید تا Snippetهای آرشیوشده را ببینید و در صورت نیاز آن‌ها را Unarchive کنید.

در حال حاضر راهی برای حذف کامل Snippet وجود ندارد؛ فقط می‌توانید Snippet را آرشیو یا از آرشیو خارج کنید.

دو Snippet نمی‌توانند نام یکسان داشته باشند؛ حتی اگر یکی از آن‌ها آرشیوشده باشد، چون ممکن است هنوز در یک سؤال استفاده شود.

پارامترهای SQL در Snippetها

می‌توانید در Snippetها از پارامترهای SQL استفاده کنید. مثلاً:

{% raw %}
WHERE
  {{created_at}}
AND category = {{category}}
GROUP BY {{time_grouping}}
{% endraw %}

وقتی Snippetای که پارامتر دارد به یک کوئری اضافه شود، متابیس برای آن پارامترها ویجت می‌سازد.

می‌توانید نوع، ستون‌های متصل (Linked columns) و مقادیر پیش‌فرض پارامترهای Snippet را از نوار کناری Variables برای هر سؤال تنظیم کنید.

تنظیمات پارامترهای Snippet وابسته به خود سؤال است، نه خود Snippet؛ یعنی اگر یک Snippet را در دو سؤال مختلف استفاده کنید، می‌توانید پارامترهایش را برای هر سؤال جداگانه تنظیم کنید. مثلاً اگر:

WHERE {% raw %}{{created_at}}{% endraw %}

را در Snippet ذخیره کرده باشید، در یک سؤال می‌توانید این پارامتر را به ستون CREATED_AT و در سؤال دیگر به ستون CANCELED_AT وصل کنید.

اگر چند Snippet داشته باشید که در همهٔ آن‌ها پارامتر همنام (مثلاً {{var}}) استفاده شده باشد، در سطح سؤال فقط یک پارامتر با آن نام خواهید دید و مقدار آن در همهٔ Snippetها مشترک استفاده می‌شود.

دسترسی‌ها و مجوزهای Snippet

هر کاربری که برای حداقل یکی از دیتابیس‌های شما مجوز استفاده از ویرایشگر Native را داشته باشد:

• می‌تواند نوار کناری Snippet را ببیند،
• می‌تواند Snippet بسازد، ویرایش کند، آرشیو یا Unarchive کند،
• حتی اگر آن Snippet برای دیتابیسی نوشته شده باشد که خودِ او اجازهٔ ویرایش SQL در آن دیتابیس را ندارد.

در برخی پلن‌ها، امکانات اضافه‌ای برای سازمان‌دهی Snippetها در پوشه‌ها و تنظیم مجوز روی آن پوشه‌ها وجود دارد. برای جزئیات، مستندات Snippet folders و permissions را ببینید.

چرا از Snippet استفاده کنیم؟

Snippetها برای این موارد عالی‌اند:

• استانداردسازی (Standardization)

  این‌که «محصول محبوب» در سازمان شما چگونه تعریف می‌شود؟ بر اساس تعداد فروش؟ یا میانگین امتیاز بیشتر از ۴؟ می‌توانید این تعریف را در قالب یک Snippet مثل {% raw %}{{snippet: popular products}}{% endraw %} کدگذاری کنید تا همان منطق در تمام سؤال‌هایی که آن Snippet را استفاده می‌کنند اعمال شود. اگر بعداً لازم شد این تعریف تغییر کند، کافی است Snippet را آپدیت کنید.

  مانند Segmentها (فیلترهای نام‌گذاری‌شده) و Metricها (محاسبه‌های نام‌گذاری‌شده)، Snippetها هم کمک می‌کنند تحلیلی استاندارد و قابل‌اعتماد در سطح سازمان داشته باشید.

• صرفه‌جویی در زمان (Efficiency)

  اگر زیاد SQL کپی‌پیست می‌کنید، یا دوست ندارید هر بار روابط Foreign keyها را به‌خاطر بیاورید، می‌توانید یک بار کوئری پیچیده را بنویسید، آن را به‌صورت Snippet ذخیره کنید و هر وقت لازم شد همان Snippet را استفاده کنید.

• یادگیری و انتقال دانش (Education)

  Snippetها می‌توانند برای افراد تازه‌کار SQL (و حتی آنالیتیک‌های باتجربه) منبعی برای دیدن «SQL مرجع سازمان» یا کوئری‌های بهینه‌تر و پیچیده‌تر باشند. خواندن و بازاستفاده از کدهای خوب، یکی از بهترین راه‌ها برای رشد مهارت است. همچنین افراد می‌توانند یک Snippet را کپی کرده، کمی تغییر دهند و آن را به‌عنوان Snippet جدید برای بقیه ذخیره کنند.

بیشتر یاد بگیرید

• Snippets vs Saved Questions vs Views
• اگر در SQL خودتان مشکل دارید، به راهنمای رفع اشکال SQL سر بزنید.