وقتی در Obsidian [[ساختن یک پایگاه|یک پایگاه میسازید]]، به صورت فایل `.base` ذخیره میشود. پایگاهها معمولاً با استفاده از رابط کاربری اپلیکیشن ویرایش میشوند، اما سینتکس آنها را میتوان به صورت دستی نیز ویرایش کرد و در یک بلوک کد جاسازی نمود.
سینتکس [[معرفی پایگاهها|پایگاهها]] [[نماها]]، فیلترها و [[فرمولها]] را تعریف میکند. پایگاهها باید YAML معتبر و مطابق با طرحواره تعریفشده در زیر باشند.
## نمونه
در اینجا نمونهای از یک فایل پایگاه آمده است. هر بخش را به تفصیل بررسی خواهیم کرد.
```yaml
filters:
or:
- file.hasTag("tag")
- and:
- file.hasTag("book")
- file.hasLink("Textbook")
- not:
- file.hasTag("book")
- file.inFolder("Required Reading")
formulas:
formatted_price: 'if(price, price.toFixed(2) + " dollars")'
ppu: "(price / age).toFixed(2)"
properties:
status:
displayName: Status
formula.formatted_price:
displayName: "Price"
file.ext:
displayName: Extension
summaries:
customAverage: 'values.mean().round(3)'
views:
- type: table
name: "My table"
limit: 10
groupBy:
property: note.age
direction: DESC
filters:
and:
- 'status != "done"'
- or:
- "formula.ppu > 5"
- "price > 2.1"
order:
- file.name
- file.ext
- note.age
- formula.ppu
- formula.formatted_price
summaries:
formula.ppu: Average
```
### پالایهها
بهطور پیشفرض یک پایگاه شامل تمام فایلهای موجود در گاوصندوق میشود. چیزی مانند `from` یا `source` مانند SQL یا Dataview وجود ندارد. بخش `filters` به شما امکان میدهد شرایطی برای محدود کردن مجموعه دادهها تعریف کنید.
```yaml
# فیلتر ساده:
filters:
and:
- file.hasTag("tag")
# فیلتر پیچیده:
filters:
or:
- file.hasTag("tag")
- and:
- file.hasTag("book")
- file.hasLink("Textbook")
- not:
- file.hasTag("book")
- file.inFolder("Required Reading")
```
دو فرصت برای اعمال فیلترها وجود دارد:
1. در سطح `filters` سراسری (نشان داده شده در بالا) که روی تمام نماهای موجود در پایگاه اعمال میشوند.
2. در سطح `view` که فقط روی یک نمای خاص اعمال میشوند.
این دو بخش از نظر عملکردی معادل هستند و هنگام ارزیابی برای یک نما با `AND` ترکیب میشوند.
بخش `filters` شامل یک عبارت فیلتر تکی به صورت رشته، یا یک شیء فیلتر تعریفشده به صورت بازگشتی است. اشیاء فیلتر ممکن است شامل یکی از `and`، `or` یا `not` باشند. این کلیدها فهرستی ناهمگن از اشیاء فیلتر دیگر یا عبارات فیلتر به صورت رشته هستند. یک عبارت فیلتر خطی است که هنگام اعمال روی یک یادداشت به مقدار صحیح یا غلط ارزیابی میشود. میتواند یکی از موارد زیر باشد:
- یک مقایسه پایه با استفاده از عملگرهای حسابی استاندارد.
- یک تابع. تعدادی [[توابع]] داخلی وجود دارد و افزونهها میتوانند توابع اضافی اضافه کنند.
سینتکس و توابع موجود برای فیلترها و فرمولها یکسان هستند.
### فرمولها
بخش `formulas` [[فرمولها|ویژگیهای فرمولی]] را تعریف میکند که میتوانند در تمام نماهای موجود در فایل پایگاه نمایش داده شوند.
```yaml
formulas:
formatted_price: 'if(price, price.toFixed(2) + " dollars")'
ppu: "(price / age).toFixed(2)"
```
ویژگیهای فرمولی از عملگرهای حسابی پایه و تعدادی [[توابع]] داخلی پشتیبانی میکنند. در آینده، افزونهها میتوانند توابعی برای استفاده در فرمولها اضافه کنند.
میتوانید به روشهای مختلفی بسته به نوع ویژگیها به آنها ارجاع دهید:
- **ویژگیهای یادداشت** ویژگیهایی هستند که در فرادادهٔ ابتدای فایل یادداشت تعریف شدهاند. به عنوان مثال `note.price` یا `note["price"]`.
اگر هیچ پیشوندی مشخص نشده باشد، فرض بر این است که ویژگی از نوع `note` است.
- **ویژگیهای فایل** خود فایل را توصیف میکنند.
به عنوان مثال `file.size` یا `file.ext`. همچنین میتوانید مستقیماً به شیء فایل ارجاع دهید، مثلاً `file.hasLink()`.
- **ویژگیهای فرمولی** فرمولهای دیگر موجود در پایگاه هستند.
مثال: `formula.formatted_price`.
یک فرمول میتواند از مقادیر ویژگیهای فرمولی دیگر استفاده کند، تا زمانی که ارجاع دوری وجود نداشته باشد.
ویژگیهای فرمولی همیشه به صورت رشته در YAML ذخیره میشوند، اما **نوع داده خروجی** واقعی آنها توسط نوع داده زیربنایی و مقدار بازگشتی توابع استفادهشده تعیین میشود.
توجه داشته باشید که استفاده از نقلقولهای تو در تو برای قرار دادن متون ثابت در فیلد YAML ضروری است. متون ثابت باید در نقلقول تکی یا دوتایی محصور شوند.
### ویژگیها
بخش `properties` امکان ذخیره اطلاعات پیکربندی مربوط به هر ویژگی را فراهم میکند. نحوه استفاده از این مقادیر پیکربندی به نمای مربوطه بستگی دارد. به عنوان مثال، در جدولها نام نمایشی برای سرفصلهای ستون استفاده میشود.
```yaml
properties:
status:
displayName: Status
formula.formatted_price:
displayName: "Price"
file.ext:
displayName: Extension
```
نامهای نمایشی در فیلترها یا فرمولها استفاده نمیشوند.
### خلاصهها
بخش `summaries` میتواند برای تعریف فرمولهای خلاصه سفارشی استفاده شود. علاوه بر تعریف فرمولهای خلاصه در اینجا، چندین فرمول خلاصه پیشفرض نیز موجود است.
```yaml
summaries:
customAverage: 'values.mean().round(3)'
```
در این نمونه، فرمول `customAverage` مانند `Average` پیشفرض است، با این تفاوت که مقدار به تعداد اعشار متفاوتی گرد میشود. در فرمولهای خلاصه، کلمه کلیدی `values` فهرستی شامل تمام مقادیر آن ویژگی در تمام یادداشتهای مجموعه نتایج است. فرمول خلاصه باید یک `Value` واحد بازگرداند.
توجه داشته باشید که این بخش `summaries` با بخش `summaries` موجود در پیکربندی نما (توضیح داده شده در زیر) متفاوت است، جایی که فرمولهای خلاصه به ویژگیهای خاص اختصاص داده میشوند.
#### فرمولهای خلاصه پیشفرض
| نام | نوع ورودی | توضیحات |
| --------- | ---------- | ------------------------------------------------------------- |
| Average | شماره | میانگین ریاضی تمام اعداد از مقادیر ورودی. |
| Min | شماره | کوچکترین عدد از مقادیر ورودی. |
| Max | شماره | بزرگترین عدد از مقادیر ورودی. |
| Sum | شماره | مجموع تمام اعداد در ورودی. |
| Range | شماره | اختلاف بین `Max` و `Min`. |
| Median | شماره | میانه ریاضی تمام اعداد از مقادیر ورودی. |
| Stddev | شماره | انحراف معیار تمام اعداد از مقادیر ورودی. |
| Earliest | تاریخ | زودترین تاریخ از مقادیر ورودی. |
| Latest | تاریخ | دیرترین تاریخ از مقادیر ورودی. |
| Range | تاریخ | اختلاف بین `Latest` و `Earliest`. |
| Checked | بولین | تعداد مقادیر `true`. |
| Unchecked | بولین | تعداد مقادیر `false`. |
| Empty | هر نوع | تعداد مقادیری در ورودی که بدون مقدار هستند. |
| Filled | هر نوع | تعداد مقادیری در ورودی که بدون مقدار نیستند. |
| Unique | هر نوع | تعداد مقادیر یکتا در ورودی. |
### نماها
بخش `views` نحوه نمایش دادهها را تعریف میکند. هر ورودی در فهرست `views` یک نمای جداگانه از همان دادهها تعریف میکند و میتوان به هر تعداد نمای مختلف نیاز داشت.
```yaml
views:
- type: table
name: "My table"
limit: 10
groupBy:
property: note.age
direction: DESC
filters:
and:
- 'status != "done"'
- or:
- "formula.ppu > 5"
- "price > 2.1"
order:
- file.name
- file.ext
- note.age
- formula.ppu
- formula.formatted_price
summaries:
formula.ppu: Average
```
- `type` از بین انواع نمای داخلی و اضافهشده توسط افزونهها انتخاب میکند.
- `name` نام نمایشی است و میتواند برای تعریف نمای پیشفرض استفاده شود.
- `filters` دقیقاً مانند آنچه در بالا توضیح داده شد هستند، اما فقط روی آن نما اعمال میشوند.
- `groupBy` یک ویژگی و جهت مرتبسازی مشخص میکند. مقدار ویژگی مشخصشده برای هر ردیف برای قرار دادن ردیف در گروهها استفاده میشود.
- `summaries` نام ویژگیها را به یک خلاصه نامگذاریشده نگاشت میکند. خلاصهها یک تجمیع روی ویژگی در تمام ردیفها انجام میدهند.
[[نماها]] میتوانند دادههای اضافی برای ذخیره هر اطلاعاتی که برای حفظ وضعیت یا نمایش صحیح لازم است اضافه کنند، با این حال توسعهدهندگان افزونه باید مراقب باشند که از کلیدهایی که قبلاً توسط افزونه اصلی پایگاهها استفاده شدهاند استفاده نکنند. به عنوان مثال، یک نمای جدول ممکن است از این برای محدود کردن تعداد ردیفها یا انتخاب ستون مرتبسازی و جهت آن استفاده کند. یک نوع نمای دیگر مانند نقشه میتواند از این برای نگاشت ویژگیهای مربوط به عرض و طول جغرافیایی و ویژگیای که باید به عنوان عنوان پین نمایش داده شود استفاده کند.
در آینده، API به نماها اجازه خواهد داد این مقادیر را بخوانند و بنویسند و به نما امکان ساخت رابط کاربری خاص خود برای پیکربندی را میدهد.
## ویژگیها
سه نوع ویژگی در پایگاهها استفاده میشود:
1. **ویژگیهای یادداشت**، ذخیرهشده در فرادادهٔ ابتدای فایلهای Markdown.
2. **ویژگیهای فایل**، قابل دسترسی برای تمام انواع فایل.
3. **ویژگیهای فرمولی**، تعریفشده در خود فایل `.base` (به بالا مراجعه کنید).
### ویژگیهای یادداشت
[[ویژگیها|ویژگیهای یادداشت]] فقط برای فایلهای Markdown در دسترس هستند و در فرادادهٔ ابتدای فایل YAML هر یادداشت ذخیره میشوند. این ویژگیها با قالب `note.author` یا بهسادگی `author` به عنوان مخفف قابل دسترسی هستند.
### ویژگیهای فایل
ویژگیهای فایل به فایلی اشاره دارند که در حال حاضر مورد آزمایش یا ارزیابی است. ویژگیهای فایل برای تمام [[قالبهای فایل پذیرفتهشده|انواع فایل]] از جمله پیوستها در دسترس هستند.
به عنوان مثال، فیلتر `file.ext == "md"` برای تمام فایلهای Markdown صحیح و در غیر این صورت غلط خواهد بود.
| ویژگی | نوع | توضیحات |
| ------------- | ------ | ------------------------------------------------------------- |
| `file.backlinks` | فهرست | فهرست فایلهای بکلینک. توجه: این ویژگی از نظر عملکرد سنگین است. در صورت امکان، جستجو را معکوس کنید و از `file.links` استفاده کنید. نتایج با تغییر گاوصندوق بهطور خودکار ریفرش نمیشوند. |
| `file.ctime` | تاریخ | زمان ایجاد |
| `file.embeds` | فهرست | فهرست تمام جاسازیها در یادداشت |
| `file.ext` | رشته | پسوند فایل |
| `file.file` | فایل | شیء فایل، فقط در توابع خاصی قابل استفاده است |
| `file.folder` | رشته | مسیر پوشه فایل |
| `file.links` | فهرست | فهرست تمام پیوندهای داخلی در یادداشت، شامل فرادادهٔ ابتدای فایل |
| `file.mtime` | تاریخ | زمان اصلاح |
| `file.name` | رشته | نام فایل |
| `file.path` | رشته | مسیر فایل |
| `file.properties` | شیء | تمام ویژگیهای فایل. توجه: نتایج با تغییر گاوصندوق بهطور خودکار ریفرش نمیشوند. |
| `file.size` | شماره | اندازه فایل |
| `file.tags` | فهرست | فهرست تمام برچسبها در محتوای فایل و فرادادهٔ ابتدای فایل |
### دسترسی به ویژگیها با `this`
از شیء `this` برای دسترسی به ویژگیهای فایل استفاده کنید. اینکه `this` به چه چیزی اشاره میکند، به محل نمایش پایگاه بستگی دارد.
وقتی پایگاه در ناحیه محتوای اصلی باز میشود، `this` به ویژگیهای خود فایل پایگاه اشاره میکند. به عنوان مثال، استفاده از `this.file.folder` مسیر پوشهای که پایگاه در آن قرار دارد را برمیگرداند.
وقتی پایگاه در فایل دیگری جاسازی شده باشد، `this` به ویژگیهای فایل _جاسازیکننده_ (یادداشت یا Canvas که پایگاه را در بر دارد) اشاره میکند. به عنوان مثال، استفاده از `this.file.name` نام فایل جاسازیکننده را برمیگرداند، نه نام پایگاه.
وقتی پایگاه در نوار کناری باشد، `this` به فایل فعال در ناحیه محتوای اصلی اشاره میکند. این به شما امکان ایجاد پرسمانها بر اساس فایل فعال را میدهد. به عنوان مثال، میتوانید از `file.hasLink(this.file)` برای بازسازی پنل بکلینکها استفاده کنید.
## عملگرها
### عملگرهای حسابی
عملگرهای حسابی عملیات ریاضی روی اعداد انجام میدهند. به عنوان مثال، `radius * (2 * 3.14)`.
| عملگر | توضیحات |
| -------- | ----------- |
| `+` | جمع |
| `-` | تفریق |
| `*` | ضرب |
| `/` | تقسیم |
| `%` | باقیمانده |
| `( )` | پرانتز |
### محاسبات تاریخ
تاریخها را میتوان با جمع و تفریق مدتزمانها تغییر داد. واحدهای مدتزمان قالبهای متعددی میپذیرند:
| واحد | مدتزمان |
| ------------------------ | -------- |
| `y`، `year`، `years` | سال |
| `M`، `month`، `months` | ماه |
| `d`، `day`، `days` | روز |
| `w`، `week`، `weeks` | هفته |
| `h`، `hour`، `hours` | ساعت |
| `m`، `minute`، `minutes` | دقیقه |
| `s`، `second`، `seconds` | ثانیه |
برای تغییر یا جابجایی اشیاء Date، از عملگر `+` یا `-` با یک رشته مدتزمان استفاده کنید. به عنوان مثال، `date + "1M"` یک ماه به تاریخ اضافه میکند، در حالی که `date - "2h"` دو ساعت از تاریخ کم میکند.
[[توابع|تابع]] سراسری `today()` میتواند برای دریافت تاریخ فعلی و `now()` برای دریافت تاریخ و زمان فعلی استفاده شود.
- `now() + "1 day"` یک datetime دقیقاً ۲۴ ساعت پس از زمان اجرا را برمیگرداند.
- `file.mtime > now() - "1 week"` اگر فایل در هفته گذشته تغییر کرده باشد `true` برمیگرداند.
- `date("2024-12-01") + "1M" + "4h" + "3m"` یک شیء Date نمایانگر `2025-01-01 04:03:00` برمیگرداند.
- دو تاریخ را از هم کم کنید تا اختلاف میلیثانیهای بین آن دو را بدست آورید، به عنوان مثال `now() - file.ctime`.
- برای دریافت بخش تاریخ از یک Date با زمان، از `datetime.date()` استفاده کنید.
- برای قالببندی یک شیء Date، از تابع `format()` استفاده کنید، به عنوان مثال `datetime.format("YYYY-MM-DD")`.
### عملگرهای مقایسهای
عملگرهای مقایسهای میتوانند برای مقایسه اعداد یا اشیاء Date استفاده شوند. برابر و نابرابر میتوانند با هر نوع مقداری استفاده شوند، نه فقط اعداد و تاریخها.
| عملگر | توضیحات |
| -------- | ---------------------- |
| `==` | برابر |
| `!=` | نابرابر |
| `>` | بزرگتر از |
| `<` | کوچکتر از |
| `>=` | بزرگتر یا مساوی |
| `<=` | کوچکتر یا مساوی |
### عملگرهای بولین
عملگرهای بولین میتوانند برای ترکیب یا معکوس کردن مقادیر منطقی استفاده شوند و نتیجهای صحیح یا غلط تولید کنند.
| عملگر | توضیحات |
| -------- | ----------- |
| `!` | نقیض منطقی |
| `&&` | و منطقی |
| \|\| | یا منطقی |
## توابع
[[توابع|فهرست توابع]] قابل استفاده در فرمولها و [[نماها|فیلترها]] را ببینید.
## انواع داده
پایگاهها دارای سیستم نوع هستند که توسط فرمولها و فیلترها برای اعمال توابع بر ویژگیها استفاده میشود.
### رشتهها، اعداد و بولینها
رشتهها، اعداد و بولینها مقادیر «اولیه» هستند که برای ایجاد آنها نیازی به تابع نیست.
- رشتهها در نقلقول تکی یا دوتایی محصور میشوند، به عنوان مثال `"message"`.
- اعداد به صورت ارقام نوشته میشوند و ممکن است به صورت اختیاری در پرانتز برای وضوح محصور شوند. به عنوان مثال، `1` یا `(2.5)`.
- بولینها بدون نقلقول به صورت `true` یا `false` نوشته میشوند.
### تاریخها و مدتزمانها
تاریخها یک تاریخ خاص یا یک تاریخ و زمان را بسته به تابع استفادهشده برای ایجاد آنها یا نوعی که به [[ویژگیها|ویژگی]] اختصاص داده شده، نمایش میدهند.
- برای ساختن یک تاریخ، از تابع `date` استفاده کنید، به عنوان مثال `date("2025-01-01 12:00:00")`
- برای تغییر یک تاریخ، یک مدتزمان اضافه یا کم کنید، به عنوان مثال `now() + "1 hour"` یا `today() + "7d"`
- تاریخها را با عملگرهای مقایسهای (مثلاً `>` یا `<`) و عملگرهای حسابی مقایسه کنید (به عنوان مثال، `(now() + "1d") - now()` مقدار `86400000` میلیثانیه برمیگرداند.)
- برای استخراج بخشهایی از یک تاریخ، از فیلدهای موجود (`now().hour`) یا یک تابع میانبر (`now.time()`) استفاده کنید.
- بسیاری از [[توابع|فیلدها و توابع]] دیگر روی اشیاء تاریخ موجود هستند.
### اشیاء و فهرستها
- یک عنصر واحد را با استفاده از تابع `list()` به فهرست تبدیل کنید. این بهویژه برای ویژگیهایی مفید است که ممکن است ترکیبی از فهرستها یا مقادیر تکی داشته باشند.
- با استفاده از کروشه و یک شاخص بر پایه صفر به عناصر فهرست دسترسی پیدا کنید. به عنوان مثال، `property[0]` اولین عنصر فهرست را برمیگرداند.
- با استفاده از کروشه و نام عنصر یا نشانهگذاری نقطهای به عناصر شیء دسترسی پیدا کنید. به عنوان مثال، `property.subprop` یا `property["subprop"]`.
### فایلها و پیوندها
[[پیوند دادن یادداشتها|پیوندهای ویکی]] در [[ویژگیها|ویژگیهای فرادادهٔ ابتدای فایل]] بهطور خودکار به عنوان اشیاء Link شناسایی میشوند. پیوندها به صورت یک پیوند قابل کلیک در [[نماها|نما]] نمایش داده میشوند.
- برای ساختن یک پیوند، از [[توابع|تابع]] سراسری `link` استفاده کنید، به عنوان مثال `link("filename")` یا `link("https://obsidian.md")`.
- میتوانید از هر رشتهای یک پیوند بسازید، به عنوان مثال `link(file.ctime.date().toString())`.
- برای تنظیم متن نمایش، یک رشته یا آیکون اختیاری به عنوان پارامتر دوم ارسال کنید، به عنوان مثال `link("filename", "display")` یا `link("filename", icon("plus"))`.
یک شیء File را میتوان با استفاده از `file.asLink()` با یک متن نمایش اختیاری به پیوند تبدیل کرد.
پیوندها را میتوان با `==` و `!=` مقایسه کرد. آنها تا زمانی که به یک فایل اشاره کنند معادل هستند، یا اگر فایل هنگام جستجو وجود نداشته باشد، متن پیوند آنها باید یکسان باشد.
پیوندها را میتوان با فایلهایی مانند `file` یا `this` مقایسه کرد. آنها در صورتی برابر خواهند بود که پیوند به آن فایل حل شود. به عنوان مثال، `author == this`.
پیوندها همچنین میتوانند در بررسی وجود در فهرست مورد بررسی قرار گیرند، به عنوان مثال `authors.contains(this)`.