Obsidian bases

Obsidian Bases Skill

Mindset

Obsidian Bases is a YAML-driven query layer over vault notes. Think of .base files as live database views, not static tables — they compute and filter in real time against note frontmatter. The key discipline: define your data model in note properties first, then build views on top of it.

When to apply: Creating dynamic views of vault notes by tag, folder, or property; building task trackers, reading lists, or dashboards; or when the user asks for table, cards, or list views in Obsidian. When NOT to apply: One-off note organisation, static Markdown tables, or displaying content that does not come from frontmatter properties.

Consider starting with a simple filter and single table view, then optionally adding formulas and multiple views once the data model is validated.

Workflow

1. Create the file: Create a .base file in the vault with valid YAML content
2. Define scope: Add filters to select which notes appear (by tag, folder, property, or date)
3. Add formulas (optional): Define computed properties in the formulas section
4. Configure views: Add one or more views (table, cards, list, or map) with order specifying which properties to display
5. 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
6. 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

Schema

Base files use the .base extension and contain valid YAML.

# Global filters apply to ALL views in the base
filters:
  # Can be a single filter string
  # OR a recursive filter object with and/or/not
  and: []
  or: []
  not: []

# Define formula properties that can be used across all views
formulas:
  formula_name: 'expression'

# Configure display names and settings for properties
properties:
  property_name:
    displayName: "Display Name"
  formula.formula_name:
    displayName: "Formula Display Name"
  file.ext:
    displayName: "Extension"

# Define custom summary formulas
summaries:
  custom_summary_name: 'values.mean().round(3)'

# Define one or more views
views:
  - type: table | cards | list | map
    name: "View Name"
    limit: 10                    # Optional: limit results
    groupBy:                     # Optional: group results
      property: property_name
      direction: ASC | DESC
    filters:                     # View-specific filters
      and: []
    order:                       # Properties to display in order
      - file.name
      - property_name
      - formula.formula_name
    summaries:                   # Map properties to summary formulas
      property_name: Average

Filter Syntax

Filters narrow down results. They can be applied globally or per-view.

Filter Structure

# Single filter
filters: 'status == "done"'

# AND - all conditions must be true
filters:
  and:
    - 'status == "done"'
    - 'priority > 3'

# OR - any condition can be true
filters:
  or:
    - 'file.hasTag("book")'
    - 'file.hasTag("article")'

# NOT - exclude matching items
filters:
  not:
    - 'file.hasTag("archived")'

# Nested filters
filters:
  or:
    - file.hasTag("tag")
    - and:
        - file.hasTag("book")
        - file.hasLink("Textbook")
    - not:
        - file.hasTag("book")
        - file.inFolder("Required Reading")

Filter Operators

Operator	Description
==	equals
!=	not equal
>	greater than
<	less than
>=	greater than or equal
<=	less than or equal
&&	logical and
||	logical or
!	logical not

Properties

Three Types of Properties

1. Note properties - From frontmatter: note.author or just author
2. File properties - File metadata: file.name, file.mtime, etc.
3. Formula properties - Computed values: formula.my_formula

File Properties Reference

Property	Type	Description
file.name	String	File name
file.basename	String	File name without extension
file.path	String	Full path to file
file.folder	String	Parent folder path
file.ext	String	File extension
file.size	Number	File size in bytes
file.ctime	Date	Created time
file.mtime	Date	Modified time
file.tags	List	All tags in file
file.links	List	Internal links in file
file.backlinks	List	Files linking to this file
file.embeds	List	Embeds in the note
file.properties	Object	All frontmatter properties

The this Keyword

• In main content area: refers to the base file itself
• When embedded: refers to the embedding file
• In sidebar: refers to the active file in main content

Formula Syntax

Formulas compute values from properties. Defined in the formulas section.

formulas:
  # Simple arithmetic
  total: "price * quantity"

  # Conditional logic
  status_icon: 'if(done, "✅", "⏳")'

  # String formatting
  formatted_price: 'if(price, price.toFixed(2) + " dollars")'

  # Date formatting
  created: 'file.ctime.format("YYYY-MM-DD")'

  # Calculate days since created (use .days for Duration)
  days_old: '(now() - file.ctime).days'

  # Calculate days until due date
  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'

Key Functions

Most commonly used functions. For the complete reference of all types (Date, String, Number, List, File, Link, Object, RegExp), see FUNCTIONS_REFERENCE.md.

Function	Signature	Description
date()	date(string): date	Parse string to date (YYYY-MM-DD HH:mm:ss)
now()	now(): date	Current date and time
today()	today(): date	Current date (time = 00:00:00)
if()	if(condition, trueResult, falseResult?)	Conditional
duration()	duration(string): duration	Parse duration string
file()	file(path): file	Get file object
link()	link(path, display?): Link	Create a link

Duration Type

When subtracting two dates, the result is a Duration type (not a number).

Duration Fields: duration.days, duration.hours, duration.minutes, duration.seconds, duration.milliseconds

IMPORTANT: Duration does NOT support .round(), .floor(), .ceil() directly. Access a numeric field first (like .days), then apply number functions.

# CORRECT: Calculate days between dates
"(date(due_date) - today()).days"                    # Returns number of days
"(now() - file.ctime).days"                          # Days since created
"(date(due_date) - today()).days.round(0)"           # Rounded days

# WRONG - will cause error:
# "((date(due) - today()) / 86400000).round(0)"      # Duration doesn't support division then round

Date Arithmetic

# Duration units: y/year/years, M/month/months, d/day/days,
#                 w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds
"now() + \"1 day\""       # Tomorrow
"today() + \"7d\""        # A week from today
"now() - file.ctime"      # Returns Duration
"(now() - file.ctime).days"  # Get days as number

View Types

Table View

views:
  - type: table
    name: "My Table"
    order:
      - file.name
      - status
      - due_date
    summaries:
      price: Sum
      count: Average

Cards View

views:
  - type: cards
    name: "Gallery"
    order:
      - file.name
      - cover_image
      - description

List View

views:
  - type: list
    name: "Simple List"
    order:
      - file.name
      - status

Map View

Requires latitude/longitude properties and the Maps community plugin.

views:
  - type: map
    name: "Locations"
    # Map-specific settings for lat/lng properties

Default Summary Formulas

Name	Input Type	Description
Average	Number	Mathematical mean
Min	Number	Smallest number
Max	Number	Largest number
Sum	Number	Sum of all numbers
Range	Number	Max - Min
Median	Number	Mathematical median
Stddev	Number	Standard deviation
Earliest	Date	Earliest date
Latest	Date	Latest date
Range	Date	Latest - Earliest
Checked	Boolean	Count of true values
Unchecked	Boolean	Count of false values
Empty	Any	Count of empty values
Filled	Any	Count of non-empty values
Unique	Any	Count of unique values

Complete Examples

Task Tracker Base

filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'

formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
  is_overdue: 'if(due, date(due) < today() && status != "done", false)'
  priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))'

properties:
  status:
    displayName: Status
  formula.days_until_due:
    displayName: "Days Until Due"
  formula.priority_label:
    displayName: Priority

views:
  - type: table
    name: "Active Tasks"
    filters:
      and:
        - 'status != "done"'
    order:
      - file.name
      - status
      - formula.priority_label
      - due
      - formula.days_until_due
    groupBy:
      property: status
      direction: ASC
    summaries:
      formula.days_until_due: Average

  - type: table
    name: "Completed"
    filters:
      and:
        - 'status == "done"'
    order:
      - file.name
      - completed_date

Reading List Base

filters:
  or:
    - file.hasTag("book")
    - file.hasTag("article")

formulas:
  reading_time: 'if(pages, (pages * 2).toString() + " min", "")'
  status_icon: 'if(status == "reading", "📖", if(status == "done", "✅", "📚"))'
  year_read: 'if(finished_date, date(finished_date).year, "")'

properties:
  author:
    displayName: Author
  formula.status_icon:
    displayName: ""
  formula.reading_time:
    displayName: "Est. Time"

views:
  - type: cards
    name: "Library"
    order:
      - cover
      - file.name
      - author
      - formula.status_icon
    filters:
      not:
        - 'status == "dropped"'

  - type: table
    name: "Reading List"
    filters:
      and:
        - 'status == "to-read"'
    order:
      - file.name
      - author
      - pages
      - formula.reading_time

Daily Notes Index

filters:
  and:
    - file.inFolder("Daily Notes")
    - '/^\d{4}-\d{2}-\d{2}$/.matches(file.basename)'

formulas:
  word_estimate: '(file.size / 5).round(0)'
  day_of_week: 'date(file.basename).format("dddd")'

properties:
  formula.day_of_week:
    displayName: "Day"
  formula.word_estimate:
    displayName: "~Words"

views:
  - type: table
    name: "Recent Notes"
    limit: 30
    order:
      - file.name
      - formula.day_of_week
      - formula.word_estimate
      - file.mtime

Common Mistakes

These are workflow- and design-level anti-patterns that cause silent failures or runtime errors in Obsidian Bases. Each is distinct from the YAML syntax issues covered in Troubleshooting.

Anti-Pattern 1: Accessing formula properties without null guards

NEVER call property-dependent functions such as date(due_date) without first checking that the property exists. Calling date(due_date) when due_date is empty throws a runtime error and the whole formula column goes blank.

WHY: Obsidian Bases evaluates formulas against every note in scope. A single note with a missing property causes the entire formula column to blank out silently for all rows, making data appear lost when it is simply unguarded.

# BAD - crashes when due_date is missing
formulas:
  days_until_due: "(date(due_date) - today()).days"

# GOOD - guard with if() before accessing the property
formulas:
  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'

Always wrap property-dependent expressions in if(property, ..., fallback).

Anti-Pattern 2: Calling .round() directly on a Duration result

NEVER call .round(), .floor(), or .ceil() directly on the result of a date subtraction. Date subtraction returns a Duration, not a Number, and Duration does not expose those methods. Calling them directly causes an error.

# BAD - Duration is not a Number; .round() is undefined on it
formulas:
  age: "(now() - file.ctime).round(0)"

# GOOD - extract a numeric field first, then round
formulas:
  age: "(now() - file.ctime).days.round(0)"

Access .days, .hours, .minutes, etc. before applying any Number methods.

WHY: Duration and Number are distinct types. Skipping the field accessor means you are calling a Number method on an object that does not have it, causing a formula error that suppresses output for the entire column.

Anti-Pattern 3: Referencing formula.X without defining X in formulas

NEVER reference formula.X in order or properties without a matching key in the formulas block. If formula.priority appears in order or properties but priority is not listed under formulas, Obsidian silently drops the column. No error is shown.

# BAD - formula.priority referenced but never defined
views:
  - type: table
    order:
      - formula.priority

# GOOD - define the formula before referencing it
formulas:
  priority: 'if(priority == 1, "High", if(priority == 2, "Medium", "Low"))'

views:
  - type: table
    order:
      - formula.priority

Always verify every formula.X reference has a matching key in formulas.

WHY: Obsidian does not raise an error for undefined formula references — it simply omits the column. The silent failure makes it easy to spend time debugging data visibility when the root cause is a missing formulas entry.

Anti-Pattern 4: Using unquoted strings that contain special YAML characters

NEVER leave strings unquoted when they contain characters that YAML treats as structural syntax. Characters like :, {, }, [, ], and # are meaningful in YAML. An unquoted value containing them causes a parse error and the entire base fails to load.

# BAD - the colon inside the value breaks YAML parsing
properties:
  status:
    displayName: Status: Active

# GOOD - wrap in double quotes
properties:
  status:
    displayName: "Status: Active"

Any string that contains :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, or a backtick must be quoted.

WHY: A YAML parse error prevents the entire .base file from loading at all. Obsidian shows a generic error with no indication of which line is at fault, making unquoted special characters one of the hardest classes of mistake to diagnose quickly.

Anti-Pattern 5: Applying global filters when you only want per-view filtering

NEVER place status- or state-specific conditions in the top-level filters block when your base contains views that need to show different subsets of those notes. A filters block at the top level applies to all views. If you want one view to show active items and another to show archived ones, a global filter that excludes archived notes will silently remove them from every view.

# BAD - global filter prevents the "Archived" view from ever showing archived notes
filters: 'file.hasTag("project")'

views:
  - type: table
    name: "Active"
    filters: 'status == "active"'
  - type: table
    name: "Archived"
    filters: 'status == "archived"'   # never shows anything — global filter already excluded them

# GOOD - global filter contains only the invariant scope; per-view filters handle the rest
filters: 'file.hasTag("project")'

views:
  - type: table
    name: "Active"
    filters: 'status == "active"'
  - type: table
    name: "Archived"
    # remove global archive-exclusion or add the archive tag to the global filter scope
    filters: 'status == "archived"'

Move status-specific conditions to view-level filters. Keep global filters only for properties that are truly shared across all views (e.g., folder or tag scope).

WHY: Global filters act as an invisible pre-filter that view-level filters cannot override. Notes excluded at the global level never reach any view, so a view that looks correct in isolation will still silently suppress those records.

Anti-Pattern 6: Using file.name when file.basename is needed for display

NEVER use file.name as a display column in table or cards views when you want clean note titles. file.name includes the file extension (e.g., My Note.md). file.basename returns only the title without the extension (e.g., My Note). Displaying file.name in a table or cards view looks cluttered.

# BAD - shows "Book Title.md" instead of "Book Title"
views:
  - type: cards
    order:
      - file.name
      - author

# GOOD - shows "Book Title"
views:
  - type: cards
    order:
      - file.basename
      - author

Use file.name only when the extension itself is meaningful (e.g., comparing .md vs .canvas files). For all display purposes, prefer file.basename.

WHY: Every Obsidian note has the .md extension, so file.name in a display column produces uniformly cluttered output (Title.md, Title.md, ...) with no benefit. The extension adds visual noise without conveying information.

Embedding Bases

Embed in Markdown files:

![[MyBase.base]]

<!-- Specific view -->
![[MyBase.base#View Name]]

YAML Quoting Rules

• Use single quotes for formulas containing double quotes: 'if(done, "Yes", "No")'
• Use double quotes for simple strings: "My View Name"
• Escape nested quotes properly in complex expressions

References

• Bases Syntax
• Functions
• Views
• Formulas
• Complete Functions Reference