همگام‌سازی (Sync) و اسکن پایگاه‌داده

متابیس به‌صورت دوره‌ای انواع مختلفی از پرس‌وجوها را روی انبار دادهٔ شما اجرا می‌کند تا متادیتای پایگاه‌داده را به‌روز نگه دارد. دانستن اطلاعات ساختاری دربارهٔ داده‌ها، به متابیس کمک می‌کند تا به‌طور خودکار نمودار مناسب را انتخاب کند و منوهای کشویی (Dropdown) در ویجت‌های فیلتر را با مقادیر درست پر کند.

• همگام‌سازی Schema پایگاه‌داده: گرفتن Schema، ساختار جدول‌ها، فیلدها، قیود (کلیدهای اولیه و خارجی) و غیرفعال‌کردن جدول‌های حذف‌شده.
• اسکن مقادیر فیلدها: نمونه‌گیری از مقادیر ستون‌ها برای پرکردن Dropdownها، یافتن مقادیر متمایز و تشخیص تجسم‌های مناسب. متابیس هرگز کل جداول پایگاه‌داده را ذخیره نمی‌کند.
• Fingerprinting: نمونه‌گیری از ۱۰٬۰۰۰ ردیف اول جدول برای محاسبهٔ آمار هر فیلد بر اساس نوع آن؛ مثل تعداد مقادیر متمایز، درصد مقادیر NULL، میانگین، میانه، حداقل، حداکثر و چارک‌ها (برای انواع عددی).

همگام‌سازی، اسکن و Fingerprinting اولیه

وقتی متابیس برای اولین بار به پایگاه‌دادهٔ شما متصل می‌شود، یک Sync انجام می‌دهد تا متادیتای ستون‌های جدول‌ها را استخراج کند و به‌طور خودکار برای هر ستون یک Semantic type تعیین کند.

می‌توانید پیشرفت این پرس‌وجوها را از مسیر آیکون چرخ‌دنده > Admin settings > Tools > Tasks و با فیلتر کردن وظایف Sync دنبال کنید.

پس از اتمام پرس‌وجوها، می‌توانید متادیتای همگام‌شده را از مسیر Admin settings > Table Metadata مشاهده و ویرایش کنید. برای جزئیات، به ویرایش متادیتا مراجعه کنید.

انتخاب زمان اجرای Sync و Scan

به‌طور پیش‌فرض، متابیس هر ساعت یک Sync سبک و هر روز یک اسکن سنگین از مقادیر فیلدها انجام می‌دهد. اگر پایگاه‌دادهٔ بزرگی دارید، ممکن است بخواهید خودتان زمان Sync و Scan را تنظیم کنید.

1. روی آیکون چرخ‌دنده کلیک کنید.
2. Admin settings را انتخاب کنید.
3. به بخش Databases بروید.
4. پایگاه‌دادهٔ مورد نظر خود را انتخاب کنید.
5. در بخش Connection and sync روی Edit connection details کلیک کنید.
6. روی Show advanced options کلیک کنید تا گزینه‌های پیشرفته باز شود.
7. گزینهٔ Choose when syncs and scans happen را فعال کنید.

از این‌جا می‌توانید زمان‌بندی Sync و Scan را تنظیم کنید.

تنظیم همگام‌سازی پایگاه‌داده

گزینه‌ها شامل موارد زیر است:

• تناوب اجرای Sync: ساعتی (پیش‌فرض) یا روزانه.
• زمانی که Sync باید اجرا شود (در منطقهٔ زمانی سروری که متابیس روی آن اجرا می‌شود).

اسکن برای مقادیر فیلتر

اسکن فقط شامل «فیلدهای فعال» می‌شود: فیلدهایی که در ۱۴ روز گذشته استفاده شده‌اند. متابیس فیلدهایی را که بیش از ۱۴ روز استفاده نشده‌اند اسکن نمی‌کند. هر زمان یک فیلد غیرفعال دوباره استفاده شود، به وضعیت فعال برمی‌گردد و در اسکن بعدی لحاظ می‌شود.

گزینه‌ها:

• Regularly, on a schedule – اسکن‌ها را طبق زمان‌بندی و با تناسب با نرخ تغییرات پایگاه‌داده اجرا می‌کند. زمان اجرا براساس منطقهٔ زمانی سروری است که متابیس روی آن اجرا می‌شود. این گزینه برای پایگاه‌داده‌های کوچک یا جدول‌هایی که مقادیر متمایز آن‌ها مرتباً تغییر می‌کند بهترین است.
• Only when adding a new filter widget – اگر می‌خواهید اسکن‌ها فقط در صورت نیاز و هنگام افزودن فیلتر اجرا شوند. فعال‌کردن این گزینه یعنی متابیس فقط زمانی مقادیر فیلدها را اسکن و کش می‌کند که شخصی یک Filter Widget جدید به داشبورد یا سؤال SQL اضافه کند (یعنی پارامتر جدیدی به کوئری SQL بیفزاید).
• Never, I'll do this manually if I need to – مناسب پایگاه‌داده‌هایی که بسیار بزرگ هستند یا عملاً مقادیر جدیدی به آن‌ها اضافه نمی‌شود. در این حالت برای به‌روزکردن مقادیر فیلتر باید با دکمهٔ Re-scan field values اسکن دستی انجام دهید.

صرف‌نظر از گزینهٔ انتخابی، اگر یک فیلد را طوری تنظیم کنید که در ویجت‌های فیلتر از Dropdown استفاده کند (بخش فیلترها در متادیتا)، متابیس برای پرکردن Dropdown باید به مقادیر آن فیلد دسترسی داشته باشد. هر زمان کسی از آن Filter Widget استفاده کند، متابیس ابتدا به‌دنبال مقادیر کش‌شده (حداکثر تا ۱۴ روز معتبر) می‌گردد؛ اگر پیدا نشد، آن فیلد را دوباره اسکن می‌کند.

همگام‌سازی دستی جدول‌ها و ستون‌ها

برای Sync دستی:

1. به Admin settings > Databases > your database بروید.
2. روی Sync database schema کلیک کنید.

اسکن دستی مقادیر ستون‌ها

برای اسکن همهٔ ستون‌های یک جدول:

1. به Admin settings > Table Metadata > your database بروید.
2. جدول مورد نظر را انتخاب کنید.
3. روی آیکون چرخ‌دنده بالای صفحه کلیک کنید.
4. روی Re-scan this table کلیک کنید.

برای اسکن مقادیر یک ستون خاص:

1. به Admin settings > Table Metadata > your database بروید.
2. جدول را انتخاب کنید.
3. ستونی را که می‌خواهید به‌روز کنید پیدا کنید.
4. روی آیکون چرخ‌دنده در پنل همان ستون کلیک کنید.
5. روی Re-scan this field کلیک کنید.

پاک‌کردن مقادیر کش‌شده برای جدول یا فیلد

برای پاک‌کردن مقادیر اسکن‌شدهٔ یک جدول:

1. به Admin settings > Table Metadata بروید.
2. پایگاه‌داده و جدول مورد نظر را انتخاب کنید.
3. روی آیکون چرخ‌دنده در گوشهٔ بالا سمت راست کلیک کنید.
4. گزینهٔ Discard cached field values را انتخاب کنید.

همچنین می‌توانید برای هر فیلد به‌صورت جداگانه با کلیک روی آیکون چرخ‌دندهٔ همان فیلد و انتخاب Discard cached field values مقادیر کش‌شده را پاک کنید.

غیرفعال‌کردن Sync و Scan برای جدول‌های خاص

برای جلوگیری از اجرای Sync و Scan روی یک جدول خاص، سطح نمایش آن جدول را به Hidden تغییر دهید (Table visibility):

1. به Admin settings > Table Metadata > your database بروید.
2. روی نام جدول در سایدبار Hover کنید.
3. روی آیکون چشم کلیک کنید.

مخفی‌کردن یک جدول باعث می‌شود آن جدول در Query Builder و Data reference نمایش داده نشود. با این حال، کاربران همچنان می‌توانند با ویرایشگر SQL (SQL editor) روی آن جدول کوئری اجرا کنند.

Sync و Scan با استفاده از API

متابیس به‌طور منظم Sync و Scan انجام می‌دهد، اما اگر مدیر پایگاه‌داده (DBA) Schema را تغییر داده یا اگر در زمان‌های مشخص حجم زیادی داده به‌صورت خودکار وارد می‌شود، شاید بخواهید اسکریپتی بنویسید که از API متابیس برای اجبار به Sync یا Scan استفاده کند. API دو روش برای شروع Sync یا Scan پایگاه‌داده ارائه می‌دهد:

Sync یا Scan کل پایگاه‌داده

می‌توانید با احراز هویت کاربر و ارسال Session token در Header درخواست HTTP، از این Endpointها استفاده کنید:

• Sync database schema: آدرس /api/database/{id}/sync_schema
• Re-scan field values: آدرس /api/database/{id}/rescan_values

Sync یک جدول خاص

• /api/notify/db/{id} برای اطلاع‌دادن به متابیس که باید یک پایگاه‌داده یا (اختیاری) یک جدول خاص را Sync کند.
• /api/notify/db/{id}/new-table برای Sync کردن یک جدول جدید بدون Sync کامل کل پایگاه‌داده (نیازمند پارامترهای schema_name و table_name).

برای استفاده از این Endpoint باید رشته‌ای را از طریق متغیر محیطی MB_API_KEY تنظیم کنید. این رشته با API keyهایی که داخل خود متابیس تعریف می‌کنید متفاوت است.

Endpoint notify برای سناریوهایی طراحی شده که می‌خواهید بعد از اتمام یک فرآیند ETL به متابیس بگویید دوباره پایگاه‌داده را Sync کند.

برای جزئیات بیشتر، مستندات API را ببینید.

نحوهٔ کار Sync پایگاه‌داده

یک Sync در متابیس در اصل یک کوئری است که لیست جدول‌ها و Viewهای به‌روز، نام ستون‌ها و نوع دادهٔ هر ستون را از پایگاه‌داده می‌گیرد:

SELECT
    TRUE
FROM
    "your_schema"."your_table_or_view"
WHERE
    1 <> 1
LIMIT 0

به‌طور پیش‌فرض، این کوئری هنگام راه‌اندازی اولیه و سپس هر ساعت یک‌بار روی پایگاه‌داده شما اجرا می‌شود. این نوع کوئری روی اکثر دیتابیس‌های رابطه‌ای سریع است، اما روی MongoDB یا برخی درایورهای جامعه‌محور می‌تواند کندتر باشد. Sync را نمی‌توان به‌طور کامل خاموش کرد، چون در این صورت متابیس عملاً کار نخواهد کرد.

داده‌هایی که در Sync جمع‌آوری می‌شوند و دلیل آن‌ها:

مورد	دلیل
نام جدول‌ها	بدون جدول اصلاً مفهومی برای پرس‌وجو باقی نمی‌ماند
نام فیلدها	بدون فیلد، وضعیت مشابه است
نوع دادهٔ فیلدها	برای Query کردن و مدیریت نوع داده‌ها
کلیدهای اصلی	نمایش جدول، صفحهٔ جزئیات، Auto‑join
کلیدهای خارجی	Auto‑join و نمایش روابط بین جدول‌ها

نحوهٔ کار اسکن پایگاه‌داده

یک Scan در متابیس کوئری‌ای است که مقادیر ستون‌ها را برای استفاده در Dropdownهای فیلتر کش می‌کند. این کار با نگاه‌کردن به ۱٬۰۰۰ رکورد متمایز اول هر جدول در ترتیب صعودی انجام می‌شود:

SELECT
    "your_table_or_view"."column" AS "column"
FROM
    "your_schema"."your_table_or_view"
GROUP BY
    "your_table_or_view"."column"
ORDER BY
    "your_table_or_view"."column" ASC
LIMIT 1000

برای هر رکورد، متابیس فقط اولین ۱۰۰ کیلوبایت از متن را ذخیره می‌کند. بنابراین اگر داده‌هایی با طول ۱٬۰۰۰ کاراکتر دارید (مثل آدرس‌ها) و ستون شما بیش از ۱۰۰ مقدار متمایز دارد، متابیس فقط ۱۰۰ مقدار اول را از خروجی Scan کش می‌کند.

مقادیر کش‌شدهٔ ستون‌ها در Dropdownهای فیلتر نمایش داده می‌شوند. اگر کاربر در جعبهٔ جست‌وجوی فیلتر، مقداری را وارد کند که در ۱٬۰۰۰ رکورد اول یا ۱۰۰ کیلوبایت اول متن نباشد، متابیس برای آن مقدار به‌صورت On‑the‑fly روی پایگاه‌داده کوئری اجرا می‌کند.

Scan از Sync سنگین‌تر است، بنابراین به‌طور پیش‌فرض یک‌بار در زمان راه‌اندازی و سپس روزی یک‌بار اجرا می‌شود. اگر Scan را به‌طور کامل غیرفعال کنید، برای به‌روزنگه‌داشتن مقادیر فیلتر باید از اسکن دستی استفاده کنید.

برای کاهش تعداد جدول‌ها و فیلدهایی که لازم است اسکن شوند، متابیس فقط فیلدهایی را اسکن می‌کند که در ۱۴ روز گذشته استفاده شده‌اند.

داده‌هایی که Scan جمع‌آوری می‌کند و دلیل آن‌ها:

مورد	دلیل
مقادیر متمایز برای فیلدهای دسته‌ای (Category)	امکان استفاده از Dropdown در فیلترها به‌جای ورود متن آزاد
مقادیر کش‌شده برای فیلدهای فعال	بهبود تجربهٔ کاربری فیلترها
مقادیر پیشرفتهٔ فیلدها (با زمینهٔ فیلتر)	مقادیر هنگام اعمال محدودیت‌های امنیت ردیفی/ستونی روی داده

Fingerprinting دوره‌ای جدول‌ها

Fingerprinting دوره‌ای بار بیشتری روی پایگاه‌دادهٔ شما ایجاد می‌کند.

به‌طور پیش‌فرض، متابیس فقط هنگام اتصال اولیهٔ پایگاه‌داده، پرس‌وجوهای Fingerprinting را اجرا می‌کند.

اگر می‌خواهید متابیس هنگام ارائهٔ پیشنهاد در UI، از نمونه‌های بزرگ‌تری از مقادیر ستون‌ها استفاده کند، این تنظیم را فعال کنید:

1. به Admin > Databases > your database بروید.
2. روی Edit connection details کلیک کنید.
3. روی Show advanced options کلیک کنید.
4. گزینهٔ Periodically refingerprint tables را روشن کنید.

نحوهٔ کار Fingerprinting پایگاه‌داده

پرس‌وجوی Fingerprinting به ۱۰٬۰۰۰ ردیف اول یک جدول یا View در پایگاه‌داده نگاه می‌کند:

SELECT
    *
FROM
    "your_schema"."your_table_or_view"
LIMIT 10000

متابیس از نتایج این کوئری برای ارائهٔ پیشنهادهای بهتر در UI (مثل Auto‑binning) استفاده می‌کند.

برای جلوگیری از فشار بیش از حد روی پایگاه‌داده، متابیس فقط در بار اول اتصال، این پرس‌وجو را اجرا می‌کند.

به‌طور پیش‌فرض، بعد از این Fingerprinting اولیه، متابیس دوباره دیتابیس را Fingerprint نمی‌کند. برای Fingerprint مجدد داده‌ها می‌توانید گزینهٔ Periodically refingerprint tables را روشن کنید.

نوع داده‌هایی که Fingerprinting می‌گیرد و دلیل آن‌ها:

مورد	دلیل
تعداد مقادیر متمایز	تعیین استراتژی کش‌کردن مقادیر فیلد
حداقل/حداکثر مقادیر عددی	Binning در Visualizationها و فیلترهای بازه‌ای
بازهٔ تاریخ (کمینه/بیشینه تاریخ‌ها)	پیش‌فرض‌های فیلتر تاریخ و نمایش Timeline
تشخیص نوع خاص (URL، ایمیل، JSON، دادهٔ مکانی مانند ایالت‌های آمریکا)	نحوهٔ نمایش و فیلترکردن فیلد
نسبت مقادیر Null	ارزیابی کیفیت داده
میانگین/میانهٔ مقادیر	پیش‌فرض‌های Visualization
شاخص‌های طول متن	پنهان‌کردن فیلدهای متنی خیلی بلند از UI

مطالعهٔ بیشتر

متابیس در فرایند Sync و Scan هیچ کش‌کردن اضافی یا Rate limiting جداگانه‌ای انجام نمی‌دهد. اگر داده‌هایتان ناقص یا قدیمی به‌نظر می‌رسند، این راهنماها را ببینید:

• نمی‌توانم جدول‌ها را ببینم
• داده در متابیس با پایگاه‌داده‌ام هم‌خوان نیست