1---
2name: obsidian-bases
3description: Create and edit Obsidian Bases (.base files) with views, filters, formulas, and summaries. Use when working with .base files, creating database-like views of notes, or when the user mentions Bases, table views, card views, filters, or formulas in Obsidian.
4---
5 
6# Obsidian Bases Skill
7 
8## Workflow
9 
101. **Create the file**: Create a `.base` file in the vault with valid YAML content
112. **Define scope**: Add `filters` to select which notes appear (by tag, folder, property, or date)
123. **Add formulas** (optional): Define computed properties in the `formulas` section
134. **Configure views**: Add one or more views (`table`, `cards`, `list`, or `map`) with `order` specifying which properties to display
145. **Validate**: Verify the file is valid YAML with no syntax errors. Check that all referenced properties and formulas exist. Common issues: unquoted strings containing special YAML characters, mismatched quotes in formula expressions, referencing `formula.X` without defining `X` in `formulas`
156. **Test in Obsidian**: Open the `.base` file in Obsidian to confirm the view renders correctly. If it shows a YAML error, check quoting rules below
16 
17## Schema
18 
19Base files use the `.base` extension and contain valid YAML.
20 
21```yaml
22# Global filters apply to ALL views in the base
23filters:
24  # Can be a single filter string
25  # OR a recursive filter object with exactly ONE key: and, or, or not
26  and:
27    - 'status == "active"'
28    - not:
29        - 'file.hasTag("archived")'
30 
31# Define formula properties that can be used across all views
32formulas:
33  formula_name: 'expression'
34 
35# Configure display names and settings for properties
36properties:
37  property_name:
38    displayName: "Display Name"
39  formula.formula_name:
40    displayName: "Formula Display Name"
41  file.ext:
42    displayName: "Extension"
43 
44# Define custom summary formulas
45summaries:
46  custom_summary_name: 'values.mean().round(3)'
47 
48# Define one or more views
49views:
50  - type: table | cards | list | map
51    name: "View Name"
52    limit: 10                    # Optional: limit results
53    groupBy:                     # Optional: group results
54      property: property_name
55      direction: ASC | DESC
56    filters:                     # View-specific filters follow the same rules
57      and:
58        - 'status == "active"'
59    order:                       # Properties to display in order
60      - file.name
61      - property_name
62      - formula.formula_name
63    summaries:                   # Map properties to summary formulas
64      property_name: Average
65```
66 
67## Filter Syntax
68 
69Filters narrow down results. They can be applied globally or per-view.
70 
71### Filter Structure
72 
73```yaml
74# Single filter
75filters: 'status == "done"'
76 
77# AND - all conditions must be true
78filters:
79  and:
80    - 'status == "done"'
81    - 'priority > 3'
82 
83# OR - any condition can be true
84filters:
85  or:
86    - 'file.hasTag("book")'
87    - 'file.hasTag("article")'
88 
89# NOT - exclude matching items
90filters:
91  not:
92    - 'file.hasTag("archived")'
93 
94# Nested filters
95filters:
96  or:
97    - file.hasTag("tag")
98    - and:
99        - file.hasTag("book")
100        - file.hasLink("Textbook")
101    - not:
102        - file.hasTag("book")
103        - file.inFolder("Required Reading")
104```
105 
106### Filter Operators
107 
108| Operator | Description |
109|----------|-------------|
110| `==` | equals |
111| `!=` | not equal |
112| `>` | greater than |
113| `<` | less than |
114| `>=` | greater than or equal |
115| `<=` | less than or equal |
116| `&&` | logical and |
117| `\|\|` | logical or |
118| <code>!</code> | logical not |
119 
120## Properties
121 
122### Three Types of Properties
123 
1241. **Note properties** - From frontmatter: `note.author` or just `author`
1252. **File properties** - File metadata: `file.name`, `file.mtime`, etc.
1263. **Formula properties** - Computed values: `formula.my_formula`
127 
128### File Properties Reference
129 
130| Property | Type | Description |
131|----------|------|-------------|
132| `file.name` | String | File name |
133| `file.basename` | String | File name without extension |
134| `file.path` | String | Full path to file |
135| `file.folder` | String | Parent folder path |
136| `file.ext` | String | File extension |
137| `file.size` | Number | File size in bytes |
138| `file.ctime` | Date | Created time |
139| `file.mtime` | Date | Modified time |
140| `file.tags` | List | All tags in file |
141| `file.links` | List | Internal links in file |
142| `file.backlinks` | List | Files linking to this file |
143| `file.embeds` | List | Embeds in the note |
144| `file.properties` | Object | All frontmatter properties |
145 
146### The `this` Keyword
147 
148- In main content area: refers to the base file itself
149- When embedded: refers to the embedding file
150- In sidebar: refers to the active file in main content
151 
152## Formula Syntax
153 
154Formulas compute values from properties. Defined in the `formulas` section.
155 
156```yaml
157formulas:
158  # Simple arithmetic
159  total: "price * quantity"
160 
161  # Conditional logic
162  status_icon: 'if(done, "✅", "⏳")'
163 
164  # String formatting
165  formatted_price: 'if(price, price.toFixed(2) + " dollars")'
166 
167  # Date formatting
168  created: 'file.ctime.format("YYYY-MM-DD")'
169 
170  # Calculate days since created (use .days for Duration)
171  days_old: '(now() - file.ctime).days'
172 
173  # Calculate days until due date
174  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'
175```
176 
177## Key Functions
178 
179Most commonly used functions. For the complete reference of all types (Date, String, Number, List, File, Link, Object, RegExp), see [FUNCTIONS_REFERENCE.md](references/FUNCTIONS_REFERENCE.md).
180 
181| Function | Signature | Description |
182|----------|-----------|-------------|
183| `date()` | `date(string): date` | Parse string to date (`YYYY-MM-DD HH:mm:ss`) |
184| `now()` | `now(): date` | Current date and time |
185| `today()` | `today(): date` | Current date (time = 00:00:00) |
186| `if()` | `if(condition, trueResult, falseResult?)` | Conditional |
187| `duration()` | `duration(string): duration` | Parse duration string |
188| `file()` | `file(path): file` | Get file object |
189| `link()` | `link(path, display?): Link` | Create a link |
190 
191### Duration Type
192 
193When subtracting two dates, the result is a **Duration** type (not a number).
194 
195**Duration Fields:** `duration.days`, `duration.hours`, `duration.minutes`, `duration.seconds`, `duration.milliseconds`
196 
197**IMPORTANT:** Duration does NOT support `.round()`, `.floor()`, `.ceil()` directly. Access a numeric field first (like `.days`), then apply number functions.
198 
199```yaml
200# CORRECT: Calculate days between dates
201"(date(due_date) - today()).days"                    # Returns number of days
202"(now() - file.ctime).days"                          # Days since created
203"(date(due_date) - today()).days.round(0)"           # Rounded days
204 
205# WRONG - will cause error:
206# "((date(due) - today()) / 86400000).round(0)"      # Duration doesn't support division then round
207```
208 
209### Date Arithmetic
210 
211```yaml
212# Duration units: y/year/years, M/month/months, d/day/days,
213#                 w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds
214"now() + \"1 day\""       # Tomorrow
215"today() + \"7d\""        # A week from today
216"now() - file.ctime"      # Returns Duration
217"(now() - file.ctime).days"  # Get days as number
218```
219 
220## View Types
221 
222### Table View
223 
224```yaml
225views:
226  - type: table
227    name: "My Table"
228    order:
229      - file.name
230      - status
231      - due_date
232    summaries:
233      price: Sum
234      count: Average
235```
236 
237### Cards View
238 
239```yaml
240views:
241  - type: cards
242    name: "Gallery"
243    order:
244      - file.name
245      - cover_image
246      - description
247```
248 
249### List View
250 
251```yaml
252views:
253  - type: list
254    name: "Simple List"
255    order:
256      - file.name
257      - status
258```
259 
260### Map View
261 
262Requires latitude/longitude properties and the Maps community plugin.
263 
264```yaml
265views:
266  - type: map
267    name: "Locations"
268    # Map-specific settings for lat/lng properties
269```
270 
271## Default Summary Formulas
272 
273| Name | Input Type | Description |
274|------|------------|-------------|
275| `Average` | Number | Mathematical mean |
276| `Min` | Number | Smallest number |
277| `Max` | Number | Largest number |
278| `Sum` | Number | Sum of all numbers |
279| `Range` | Number | Max - Min |
280| `Median` | Number | Mathematical median |
281| `Stddev` | Number | Standard deviation |
282| `Earliest` | Date | Earliest date |
283| `Latest` | Date | Latest date |
284| `Range` | Date | Latest - Earliest |
285| `Checked` | Boolean | Count of true values |
286| `Unchecked` | Boolean | Count of false values |
287| `Empty` | Any | Count of empty values |
288| `Filled` | Any | Count of non-empty values |
289| `Unique` | Any | Count of unique values |
290 
291## Complete Examples
292 
293### Task Tracker Base
294 
295```yaml
296filters:
297  and:
298    - file.hasTag("task")
299    - 'file.ext == "md"'
300 
301formulas:
302  days_until_due: 'if(due, (date(due) - today()).days, "")'
303  is_overdue: 'if(due, date(due) < today() && status != "done", false)'
304  priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))'
305 
306properties:
307  status:
308    displayName: Status
309  formula.days_until_due:
310    displayName: "Days Until Due"
311  formula.priority_label:
312    displayName: Priority
313 
314views:
315  - type: table
316    name: "Active Tasks"
317    filters:
318      and:
319        - 'status != "done"'
320    order:
321      - file.name
322      - status
323      - formula.priority_label
324      - due
325      - formula.days_until_due
326    groupBy:
327      property: status
328      direction: ASC
329    summaries:
330      formula.days_until_due: Average
331 
332  - type: table
333    name: "Completed"
334    filters:
335      and:
336        - 'status == "done"'
337    order:
338      - file.name
339      - completed_date
340```
341 
342### Reading List Base
343 
344```yaml
345filters:
346  or:
347    - file.hasTag("book")
348    - file.hasTag("article")
349 
350formulas:
351  reading_time: 'if(pages, (pages * 2).toString() + " min", "")'
352  status_icon: 'if(status == "reading", "📖", if(status == "done", "✅", "📚"))'
353  year_read: 'if(finished_date, date(finished_date).year, "")'
354 
355properties:
356  author:
357    displayName: Author
358  formula.status_icon:
359    displayName: ""
360  formula.reading_time:
361    displayName: "Est. Time"
362 
363views:
364  - type: cards
365    name: "Library"
366    order:
367      - cover
368      - file.name
369      - author
370      - formula.status_icon
371    filters:
372      not:
373        - 'status == "dropped"'
374 
375  - type: table
376    name: "Reading List"
377    filters:
378      and:
379        - 'status == "to-read"'
380    order:
381      - file.name
382      - author
383      - pages
384      - formula.reading_time
385```
386 
387### Daily Notes Index
388 
389```yaml
390filters:
391  and:
392    - file.inFolder("Daily Notes")
393    - '/^\d{4}-\d{2}-\d{2}$/.matches(file.basename)'
394 
395formulas:
396  word_estimate: '(file.size / 5).round(0)'
397  day_of_week: 'date(file.basename).format("dddd")'
398 
399properties:
400  formula.day_of_week:
401    displayName: "Day"
402  formula.word_estimate:
403    displayName: "~Words"
404 
405views:
406  - type: table
407    name: "Recent Notes"
408    limit: 30
409    order:
410      - file.name
411      - formula.day_of_week
412      - formula.word_estimate
413      - file.mtime
414```
415 
416## Embedding Bases
417 
418Embed in Markdown files:
419 
420```markdown
421![[MyBase.base]]
422 
423<!-- Specific view -->
424![[MyBase.base#View Name]]
425```
426 
427## YAML Quoting Rules
428 
429- Use single quotes for formulas containing double quotes: `'if(done, "Yes", "No")'`
430- Use double quotes for simple strings: `"My View Name"`
431- Escape nested quotes properly in complex expressions
432 
433## Troubleshooting
434 
435### YAML Syntax Errors
436 
437**Unquoted special characters**: Strings containing `:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` `` must be quoted.
438 
439```yaml
440# WRONG - colon in unquoted string
441displayName: Status: Active
442 
443# CORRECT
444displayName: "Status: Active"
445```
446 
447**Mismatched quotes in formulas**: When a formula contains double quotes, wrap the entire formula in single quotes.
448 
449```yaml
450# WRONG - double quotes inside double quotes
451formulas:
452  label: "if(done, "Yes", "No")"
453 
454# CORRECT - single quotes wrapping double quotes
455formulas:
456  label: 'if(done, "Yes", "No")'
457```
458 
459### Common Formula Errors
460 
461**Duration math without field access**: Subtracting dates returns a Duration, not a number. Always access `.days`, `.hours`, etc.
462 
463```yaml
464# WRONG - Duration is not a number
465"(now() - file.ctime).round(0)"
466 
467# CORRECT - access .days first, then round
468"(now() - file.ctime).days.round(0)"
469```
470 
471**Missing null checks**: Properties may not exist on all notes. Use `if()` to guard.
472 
473```yaml
474# WRONG - crashes if due_date is empty
475"(date(due_date) - today()).days"
476 
477# CORRECT - guard with if()
478'if(due_date, (date(due_date) - today()).days, "")'
479```
480 
481**Referencing undefined formulas**: Ensure every `formula.X` in `order` or `properties` has a matching entry in `formulas`.
482 
483```yaml
484# This will fail silently if 'total' is not defined in formulas
485order:
486  - formula.total
487 
488# Fix: define it
489formulas:
490  total: "price * quantity"
491```
492 
493## References
494 
495- [Bases Syntax](https://help.obsidian.md/bases/syntax)
496- [Functions](https://help.obsidian.md/bases/functions)
497- [Views](https://help.obsidian.md/bases/views)
498- [Formulas](https://help.obsidian.md/formulas)
499- [Complete Functions Reference](references/FUNCTIONS_REFERENCE.md)
500