Query file format

This reference lists the keys of a query file (.zotquery) and a query block (```zotquery). Both hold the same YAML text, in the shape of an Obsidian .base file.

The toolbar writes these keys for you. Write them by hand when you type a query block, or when you copy a view from one file to another.

ExampleCopy Anchor Link

filters: collections.within("Thesis")
views:
  - type: table
    name: Reading list
    from: items
    sort:
      - property: title
        direction: ASC
    order:
      - title
      - firstAuthor
      - date
      - vault.literatureNote
      - vault.reading-status
    limit: 100
  - type: annotations
    name: Figures
    from: annotations
    filters: tags.contains("figure")
    groupBy:
      property: item.indexedKey
      direction: ASC
    limit: 100

Top-level keysCopy Anchor Link

ZotLit keeps every other key in the file when it saves.

View keysCopy Anchor Link

property values are property paths of the view's records, as ZotLit Query names them. For example, title is the paper title in an items view, and item.title is the paper title in an annotations view.

order also takes vault.literatureNote (in an items table), vault.<name> for a vault property (in an items view), and formula.<name> for a formula. sort and groupBy do not take a formula yet: a view that sorts or groups by one shows an error in place of its rows. groupBy does not take a vault property either.

Layouts and recordsCopy Anchor Link

A view whose type and from do not fit shows a message in place of its rows.

Layout optionsCopy Anchor Link

FiltersCopy Anchor Link

A filter is one Filter Expression, or a group of filters under and, or, or not:

filters:
  and:
    - colorName == "yellow"
    - or:
        - tags.contains("method")
        - tags.contains("result")

and matches the records that match every entry. or matches the records that match at least one. The filter editor opens a not group as one expression condition.

A filter can name the Query Context as this.item and this.attachment:

In an embed or a query block, this.item is the item that the note's zotero-key property names. In a query file's own tab, this has no value. See this: the paper of the note.

FormulasCopy Anchor Link

formulas maps each formula name to a Filter Expression. A view shows the result as the property formula.<name>:

formulas:
  year: date.year
  authors: creators.length
views:
  - type: table
    name: Reading list
    from: items
    filters: formula.year >= 2020
    order:
      - title
      - formula.year
      - formula.authors

A view computes only the formulas that its order and filters use. A formula that uses itself through other formulas is a mistake.

A formula that cannot run on the records of a view marks its property in that view only. For example, a formula colour with the expression colorName runs in an annotations view. An items view of the same file that shows formula.colour marks it, and its other properties stay on screen. A record on which a formula cannot compute its result shows an Error Value in that cell.

Vault propertiesCopy Anchor Link

A vault property, vault.<name>, is the value of the frontmatter key <name> on the paper's Literature Note. The text after vault. is the key as the note writes it, with its letter case and hyphens. For example, vault.reading-status reads the reading-status property of each paper's note.

Vault properties work in views with from: items. Properties from your Literature Notes explains how ZotLit reads them.

Each cell shows one of three states:

When a paper has more than one Literature Note, the view reads the note that changed last. In an embed or a query block inside a Literature Note, the row of that note's own paper reads that note. Copy and CSV export write the value of each vault property. The view refreshes a cell when the note's properties change.

Names that a vault property cannot takeCopy Anchor Link

The Properties menu does not list these keys, and does not add them:

A key that you type by hand into order, such as vault.tags, still shows as a column.

A key that the note's own profile writes with the replace merge strategy is read-only in the Table, because the next note update overwrites it. The cell shows a lock icon when you point to it. Out of the box, the Default profile writes title, related, collections, and citekey this way. Keys with keep or append stay editable.

Values that an edit writesCopy Anchor Link

The Table edits a vault property by the type that Obsidian's Properties panel gives it. When the property has no type there, the Table uses the type of the values in your notes, and otherwise text.

An edit writes only its own key. A cleared cell keeps the key with an empty value. Text that is not a number writes nothing to a number property.

SortCopy Anchor Link

sort:
  - property: vault.reading-status
    direction: ASC
  - property: date
    direction: DESC

Empty values sort last in both directions. A sort can mix vault properties and Zotero properties.

To sort by a vault property, the view reads at most 5,000 matching papers, sorts them, and then keeps limit rows, in each group of a grouped view. When more papers match, only those 5,000 are sorted, and the result count shows both numbers. After you change a value, the rows keep their place until the view runs again.

FilterCopy Anchor Link

A condition reads a vault property as vault.<name>, or as vault["<name>"] for a name with a hyphen or a space:

filters:
  and:
    - collections.within("Thesis")
    - vault["reading-status"] == "read"

A paper without a Literature Note counts as having no value. So vault["reading-status"] != "read" and vault["reading-status"] == null both match papers without a note.

A vault condition must be its own entry, and every row must match it:

• The whole filter is one vault condition.
• Or the condition is a direct entry under the top-level and of filters, in the file or in the view.

These conditions stop the view, and the condition's row in the filter editor shows the reason:

Split a mixed condition into two entries under and. A condition that reads this, or names the property through an expression such as vault[name], also shows the second reason.

Display namesCopy Anchor Link

properties gives a property its display name. Each key is the same text as an order entry: a property path, vault.literatureNote, vault.<name> for a vault property, or formula.<name> for a formula.

properties:
  title:
    displayName: Work
  formula.year:
    displayName: Year of source

The display name shows in every view of the file: the Table header, the Cards labels, the Properties menu, and the header row of copy and CSV export. ZotLit keeps the other keys under each property. A key with the Obsidian Bases prefix note., such as note.date, names no property.

A new query fileCopy Anchor Link

A query file that you create from the command palette or the file explorer holds this text:

views:
  - type: table
    name: Items
    from: items
    sort:
      - property: dateModified
        direction: DESC
    limit: 100
    order:
      - title
      - creators
      - date.year
      - vault.literatureNote
  - type: annotations
    name: Annotations
    from: annotations
    groupBy:
      property: item.indexedKey
      direction: ASC
    limit: 100

ZotLit writes the view names in the app's language.

See alsoCopy Anchor Link