How to query your Zotero library

ZotLit Query answers questions about the papers, files, and reading marks in your Zotero libraries. Use it for a list, a count, or an export that takes several steps in Zotero's own search.

Before you startCopy Anchor Link

You need Obsidian desktop with ZotLit loaded and the Obsidian CLI activated. Run the commands from a terminal.

Add vault=<vault-name> after obsidian when more than one vault is open, for example obsidian vault=Research zotlit:query.

How ZotLit Query works explains the records, filters, and groups behind these steps.

Run a queryCopy Anchor Link

obsidian zotlit:query filter='tags.contains("to-read")' fields='title,date.year,creators[0].fullName' limit=20

Filter by a Collection or TagCopy Anchor Link

A filter matches Collection paths and Tag names exactly, including letter case. List the exact names first with zotlit:query-values, then use them in the filter.

For example, you want the papers in your thesis Collection that have no highlight yet.

obsidian zotlit:query-values kind=collections match=thesis

{
  "ok": true,
  "values": [
    {
      "library": "personal",
      "name": "My Library",
      "totalCount": 2,
      "values": ["Query thesis", "Query thesis/Chapter 1"]
    }
  ]
}

obsidian zotlit:query filter='collections.within("Query thesis") && annotations.filter(value.type == "highlight").isEmpty()' fields=title,citationKey

A path that no library holds gives no rows and an unknown-collection warning. For example, collections.within("query thesis") has the wrong letter case. The answer suggests the exact path (shortened):

{
  "ok": true,
  "returnedCount": 0,
  "rows": [],
  "warnings": [
    {
      "code": "unknown-collection",
      "message": "Collection path \"query thesis\" was not found in the selected Libraries. List the Collection paths with zotlit:query-values kind=collections.",
      "suggestions": ["Query thesis"]
    }
  ]
}

When another library holds the path, the suggestions also include a library value, such as library=group:4815. Add it to the query to read that library.

Tags work the same way. List them with kind=tags, and add library=all to list the tags of every library:

obsidian zotlit:query-values kind=tags match=method

Each Tag value has a name and a type: manual for a tag that you added, or auto for a tag that Zotero added automatically. Use the name in a filter, such as tags.contains("methods").

Count papers, files, or marksCopy Anchor Link

Add group to count records by one value. The answer has one group for each value. Each group has its value, its count, and its first rows up to limit. totalCount is the number of matching records.

Count papers per year, with one example paper in each group:

obsidian zotlit:query group=date.year limit=1 fields=title,date.year

count is exact before the limit, so limit=1 keeps the answer short. To count many groups, such as every tag in a library, also add fields='[]'. Each row then holds only the record's key:

obsidian zotlit:query group='tags[].name' fields='[]' limit=1

The answer looks like this (shortened, rows left out):

{
  "ok": true,
  "totalCount": 3,
  "groups": [
    { "value": "methods", "count": 2 },
    { "value": "review", "count": 1 },
    { "value": null, "count": 1 }
  ]
}

[] groups by each element of a list. A paper with the tags methods and review counts in both groups, so the group counts can add up to more than totalCount. Papers with no tag form the null group.

Other lists work the same way:

A paper with two PDF files counts once in the pdf group.

To count marks, start from Annotations. This command returns the three most recent marks on each paper:

obsidian zotlit:query from=annotations group=item.indexedKey sort=-dateModified limit=3 fields=text,item.title

limit applies inside each group. The group's count gives the number of marks on that paper.

Check files and their locationsCopy Anchor Link

fileType sorts files into four kinds: pdf, epub, web for snapshots and links to web pages, and other.

Start from Attachments to find linked files that are missing on this computer:

obsidian zotlit:query from=attachments filter='linkMode == "linked_file" && !exists' fields=item.title,path

Find papers with no PDF that ZotLit can open on this computer:

obsidian zotlit:query filter='attachments.filter(value.fileType == "pdf" && value.exists).isEmpty()' fields=title,citationKey

List each paper with the kind and location of every file:

obsidian zotlit:query filter='tags.contains("to-read")' fields='title,library,attachments[].fileType,attachments[].path'

attachments[].path returns one location for each file of the paper, in the same order as attachments[].fileType. A link to a web page has no location on this computer, so its path is null.

These fields identify a record and its library:

Use indexedKey to select the files of one paper:

obsidian zotlit:query from=attachments filter='item.indexedKey == "ABCD2345"' fields=title,fileType,path

Replace ABCD2345 with the paper's Indexed Key. Explore template data shows how to copy it.

Compute a value with a formulaCopy Anchor Link

A formula computes one value for each record, in the same language as filter. Pass formulas as a JSON object in formulas: each key is a name, and each value is an expression. Read a formula as formula.<name> in fields, in filter, or in another formula.

This command lists the papers from 2020 on, with the year and the number of creators of each:

obsidian zotlit:query formulas='{"year":"date.year","authors":"creators.length"}' filter='formula.year >= 2020' fields='title,formula.year,formula.authors' limit=3

Each row holds the formula values under their paths (shortened):

{
  "ok": true,
  "returnedCount": 3,
  "truncated": true,
  "warnings": [],
  "rows": [
    {
      "indexedKey": "AAAAAAAA",
      "values": {
        "title": "Alpha of the personal library",
        "formula.year": 2024,
        "formula.authors": 3
      }
    },
    {
      "indexedKey": "BBBB2222",
      "values": {
        "title": "Within-library duplicate, first item",
        "formula.year": 2020,
        "formula.authors": 1
      }
    },
    {
      "indexedKey": "CCCC3333",
      "values": {
        "title": "Within-library duplicate, second item",
        "formula.year": 2020,
        "formula.authors": 1
      }
    }
  ]
}

A formula name has letters, digits, and _, and starts with a letter or _. Letter case counts.

A formula that no field, filter, or other formula uses does not run. The answer then has an unused-formula warning that names it.

A mistake in a formula fails the query. diagnostic.location.path names the formula, and diagnostic.report marks the mistake. For example, formula.yaer + 1 names a formula that the request does not define (shortened):

{
  "ok": false,
  "diagnostic": {
    "code": "unknown-formula",
    "report": [
      "In formula.next: formula.yaer reads the Formula \"yaer\", which the request does not define.",
      "formula.yaer + 1",
      "^^^^^^^^^^^^",
      "Read a Formula of the request: formula.year, formula.next."
    ]
  }
}

A formula that works for most records can fail on one record, such as number(volume) on a volume that is text. That value is an error object with a code and a message. Error Values describes it.

Export a large resultCopy Anchor Link

An answer in the terminal holds at most 1 MB. For a complete export, add output with the absolute path of a new file in an existing folder:

obsidian zotlit:query limit=all fields='title,citationKey,date.year,creators[0].fullName' output="$HOME/Documents/zotlit-export.json"

ZotLit writes the complete answer to that file. The terminal shows the counts and file.path in place of the rows. ZotLit keeps an existing file intact, so choose a new name for each export.

To open the result in a spreadsheet such as Excel, add format=csv, or format=tsv for tab-separated text:

obsidian zotlit:query limit=all fields='title,citationKey,date.year,creators' format=csv output="$HOME/Documents/zotlit-export.csv"

The file has a header row, then one row for each result: its Indexed Key, then each field in the order of fields. A grouped query adds a group column first. Each cell holds a value as text, so a list of creators reads Ada Lovelace, Alan Turing. The header and the cells keep the names that the query uses: a column is named by its field, such as date.year, and an item type reads as its Zotero name, such as journalArticle. CSV and TSV need output, because the terminal answer is always JSON.

Cancel a long queryCopy Anchor Link

Give a long query a name with id when you start it:

obsidian zotlit:query id=export-1 limit=all fields='[]' output="$HOME/Documents/zotlit-keys.json"

To stop it, run this command in a second terminal:

obsidian zotlit:query-cancel id=export-1

The answer has cancelRequested: true when the query was running. The first terminal then shows Error: The query 'export-1' was cancelled by zotlit:query-cancel. and ZotLit removes the unfinished export. cancelRequested: false means that the query had already finished.

An id has 1 to 128 letters, digits, ., _, or -.

Ask an AI agentCopy Anchor Link

The zotlit-query agent skill lets an AI agent, such as Claude Code or Codex, run these commands for you. Install it with the other ZotLit skills, as Install the ZotLit skill describes. Then ask your question in plain language:

Use the ZotLit query skill to count the papers in my thesis collection by tag.

The agent reads the live guide and schema from ZotLit, lists the exact Collection names, runs the query, and reports the counts with their scope.

To read the full guide yourself, run obsidian zotlit:query-guide. Add a topic, such as topic=group, to print one section.

See alsoCopy Anchor Link