# Bases syntax

When you create a base in Obsidian, it is saved as a .base file. Bases are typically edited using the app interface, but the syntax can also be edited manually, and embedded in a code block.

The Bases syntax defines Views, filters, and formulas. Bases must be valid YAML conforming to the schema defined below.

Here's an example of a base file. We'll walk through each section in detail.

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

By default a base includes every file in the vault. There is no from or source like in SQL or Dataview. The filters section lets you define conditions to narrow down the dataset.

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

There are two opportunities to apply filters:

1. At the global filters level (shown above) where they apply to all views in the base.
2. At the view level where apply only to a specific view.

These two sections are functionally equivalent and when evaluating for a view they will be concatenated with an AND.

The filters section contains either a single filter statement as a string, or a recursively defined filter object. Filter objects may contain one of and, or, or not. These keys are a heterogeneous list of other filter objects or filter statements in strings. A filter statement is a line which evaluates to truthy or falsey when applied to a note. It can be one of the following:

• A basic comparison using standard arithmetic operators.
• A function. A variety of Functions are built-in, and plugins can add additional functions.

The syntax and available functions for filters and formulas are the same.

The formulas section defines formula properties that can be displayed across all views in the base file.

formulas:
  formatted_price: 'if(price, price.toFixed(2) + " dollars")'
  ppu: "(price / age).toFixed(2)"

Formula properties support basic arithmetic operators and a variety of built-in Functions. In the future, plugins will be able to add functions for use in formulas.

You can reference properties in different ways depending on their type:

• Note properties are properties defined in the note’s frontmatter. For example note.price or note["price"].
  If no prefix is specified, the property is assumed to be a note property.

• File properties describe the file itself.
  For example file.size or file.ext. You can also reference the file object directly, e.g., file.hasLink().

• Formula properties are other formulas in the base.
  Example formula.formatted_price.

A formula can use values from other formula properties, as long as there’s no circular reference.

Formula properties are always stored as strings in YAML, but their actual output data type is determined by the type of the underlying data and the return value of any functions used.

Note the use of nested quotes is necessary to include text literals in the YAML field. Text literals must be enclosed in single or double quotes.

The properties section allows storing configuration information about each property. It is up to the individual view how to use these configuration values. For example, in tables the display name is used for the column headers.

properties:
  status:
    displayName: Status
  formula.formatted_price:
    displayName: "Price"
  file.ext:
    displayName: Extension

Display names are not used in filters or formulas.

The summaries section can be used to define custom summary formulas. In addition to defining summary formulas here, there are several default summary formulas available.

summaries:
  customAverage: 'values.mean().round(3)'

In this example, the customAverage formula is the same as the default Average, except the value is rounded to a different number of places. In summary formulas, the values key word is a list containing all of the values for that property across every note in the result set. The summary formula should return a single Value.

Note that this summaries section is different from the summaries section in the view config (explained below) where summary formulas as assigned to specific properties.

The views section defines how the data can be rendered. Each entry in the views list defines a separate view of the same data, and there can be as many different views as needed.

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 selects from the built-in and plugin-added view types.
• name is the display name, and can be used to define the default view.
• filters are exactly the same as described above, but apply only to the view.
• groupBy specifies a property and sort direction. The value of the specified property for each row is used to place the row into groups.
• summaries maps property names to a named summary. Summaries perform an aggregation on the property across all rows.

Views can add additional data to store any information needed to maintain state or properly render, however plugin authors should take care to not use keys already in use by the core Bases plugin. As an example, a table view may use this to limit the number of rows or to select which column is used to sort rows and in which direction. A different view type such as a map could use this for mapping which property in the note corresponds to the latitude and longitude and which property should be displayed as the pin title.

In the future, API will allow views to read and write these values, allowing the view to build its own interface for configuration.

There are three kinds of properties used in bases:

1. Note properties, stored in frontmatter of Markdown files.
2. File properties, accessible for all file types.
3. Formula properties, defined in the .base file itself (see above).

Note properties are only available for Markdown files, and are stored in the YAML frontmatter of each note. These properties can be accessed using the format note.author or simply author as a shorthand.

File properties refer to the file currently being tested or evaluated. File properties are available for all file types, including attachments.

For example, a filter file.ext == "md" will be true for all Markdown files and false otherwise.

Use the this object to access file properties. What this refers to, will depend on where the base is displayed.

When the base is opened in main content area, this points to properties of the base file itself. For example, using this.file.folder returns the folder path where the base is located.

When the base is embedded in another file, this points to properties of the embedding file (the note or Canvas that contains the base). For example, using this.file.name returns the name of the embedding file, not the base.

When the base is in a sidebar, this refers to the active file in the main content area. This lets you create queries based on the active file. For example, you can use file.hasLink(this.file) to replicate the backlinks pane.

Arithmetic operators perform arithmetic on numbers. For example, radius * (2 * 3.14).

Dates can be modified by adding and subtracting durations. Duration units accept multiple formats:

To modify or offset Date objects, use the + or - operator with a duration string. For example, date + "1M" adds 1 month to the date, while date - "2h" subtracts 2 hours from the date.

The global function today() can be used to get the current date, and now() can be used to get the current date with time.

• now() + "1 day" returns a datetime exactly 24 hours from the time of execution.
• file.mtime > now() - "1 week" returns true if the file was modified within the last week.
• date("2024-12-01") + "1M" + "4h" + "3m" returns a Date object representing 2025-01-01 04:03:00.
• Subtract two dates to get the millisecond difference between the two, for example, now() - file.ctime.
• To get the date portion of a Date with time, use datetime.date().
• To format a Date object, use the format() function, for example datetime.format("YYYY-MM-DD").

Comparison operators can be used to compare numbers, or Date objects. Equal and not equal can be used with any kind of value, not just numbers and dates.

Boolean operators can be used to combine or invert logical values, resulting in a true or false value.

See the list of functions that can be used in formulas and filters.

Bases have a type system which is used by formulas and filters to apply functions to properties.

Strings, numbers, and booleans are "primitive" values which do not require a function to create.

• Strings are enclosed in single or double quotes, for example "message".
• Numbers are written as digits, and may optionally be enclosed in parenthesis for clarity. For example, 1 or (2.5).
• Booleans are written as true or false without quotes.

Dates represent a specific date, or a date and time depending on the function used to create them, or that type that has been assigned to the property.

• To construct a date, use the date function, for example date("2025-01-01 12:00:00")
• To modify a date, add or remove a duration, for example now() + "1 hour" or today() + "7d"
• Compare dates using comparison operators (e.g. > or <) and arithmetic operators (for example, (now() + "1d") - now() returns 86400000 milliseconds.)
• To extract portions of a date, use the available fields (now().hour), or a convenience function (now.time()).
• Many other fields and functions are available on date objects.

• Turn a single element into a list using the list() function. This is especially helpful for properties which may contain a mixture of lists or single values.
• Access list elements using square brackets, and a 0-based index. For example, property[0] returns the first element from the list.
• Access object elements using square brackets and the element name or dot notation. For example, property.subprop or property["subprop"].

Wikilinks in frontmatter properties are automatically recognized as Link objects. Links will render as a clickable link in the view.

• To construct a link, use the global link function, for example link("filename") or link("https://obsidian.md").
• You can create a link from any string, for example, link(file.ctime.date().toString()).
• To set the display text, pass in an optional string or icon as a second parameter, for example link("filename", "display") or link("filename", icon("plus")).

A File object can be turned into a link using file.asLink() with an optional display text.

Links can be compared with == and !=. They are equivalent as long as they point to the same file, or if the file does not exist when looked up, their link text must be identical.

Links can be compared to files such as file or this. They will equate if the link resolves to the file. For example, author == this.

Links can also be checked in list contains, for example, authors.contains(this).