Use query files and query blocks
Create a query file, filter, sort, and group its views, add formulas, embed it in notes, and save the annotation sidebar as a query file.
A query file shows live annotations, files, or papers from your Zotero library in a tab or in a note. This page shows how to create one, change its views, and embed it. Query files and query blocks explains the ideas behind them.
Create a query file
Use one of these:
- Open the command palette and run ZotLit: Create new query file. The file goes in the folder where Obsidian puts new notes.
- In the file explorer, right-click a folder, or a file in that folder, and select New query file.
ZotLit creates a file named Untitled.zotquery and opens it in a tab. Hold Ctrl (Windows and Linux) or Command (macOS) when you select the menu item to open it in a new tab. Rename the file as you rename any note.
The new file has two views:
- Items is the default view. It is a Table of the papers in your whole library, newest first by date modified, at most 100 at a time. It shows the Title, Creators, Year, and Literature note columns.
- Annotations shows the annotations of your whole library, grouped by paper, at most 100 at a time.
To see the annotations, select the view menu and select Annotations. See Switch, add, and arrange views.
Work with views
The toolbar at the top of the file has these controls, from left to right:
| Control | What it does |
|---|---|
| The view menu | Shows the view on screen. Switch, add, and configure views here. |
| The result count | Shows how many records match. Opens the Results menu. |
| Filter | Chooses which records the view shows. |
| Sort | Sets the order of the rows. |
| Group | Collects the rows under headings. |
| Properties | Chooses the values that each row shows. |
| Search | Finds text in the rows on screen. |
On a narrow pane, the toolbar shows icons without labels.
Switch, add, and arrange views
Select the view menu to see the views of the file. Type in Search views… to find a view by name, then select it.
- To add a view, select Add view. ZotLit opens Configure view so that you can name it.
- To change the order of the views, drag a view in the list.
- To make a view the default, open its Configure view page, select More options (…), and select Default view. The default view moves to the top of the list. An embed without a view name shows it.
- To copy or remove a view, open its Configure view page, select More options (…), and select Duplicate view or Delete view.
Configure a view
Select the view menu. On the row of a view, select the chevron button, tooltipped Configure view. You can also right-click the row, or right-click the view menu button to configure the view on screen. The Configure view page opens in the same menu. Each change saves at once. The view name saves when you leave the field.
| Setting | What it does |
|---|---|
| View name | The name in the view menu and after # in an embed. |
| Rows | What each row is: one annotation, one attachment, or one item. |
| Layout | How the view draws the rows. The list offers only the layouts that can show the chosen records. |
When you change the rows, the sort, grouping, and properties stay in the file. The view ignores the ones that the new rows do not have. Sort, Group, and Properties mark each of them Not used, and a note under the toolbar names them. When you switch back to rows that have them, the view uses them again.
Each layout adds its own options:
| Layout | Options |
|---|---|
| Annotations | Card width, Show comment, Show tags, Show page |
| List | Markers, Indent properties, Property separator |
| Cards | Card size |
| Table | Column order and widths are adjusted directly on table headers (see Use the Table layout). |
Filter the rows
Select Filter. The filter editor has two parts:
- All views: conditions for every view of the file that shows the same kind of rows as the first view.
- This view: conditions for the view on screen only.
Add a condition
Select Add condition. A new row reads Empty and filters nothing until it has a value. Choose a property, an operator, and a value. For example, choose Color, is, and Yellow to find key highlights. In an items view, choose Year, is on or after, and enter 2020 to find recent publications.
Combine conditions
Choose All the following are true to show records that match every condition, Any of the following are true to show records that match at least one, or None of the following are true to hide records that match any condition in the group. Select Add group to nest a group of conditions inside another group (for example, to find yellow highlights that also have either the tag #theory or #method).
Arrange conditions
Drag the handle (Drag to reorder) on any condition or group to move it up or down. You can drag a condition within a group, into a nested group, or out to a parent group. You can also select the handle and press Alt+Arrow Up or Alt+Arrow Down to move the row.
To remove a condition, delete its row. When you delete the last row of a nested group, the group goes too. When you delete the last row of the filter, the filter goes too.
Check the result
The view refreshes as you edit. The result count shows the new number of records.
The properties depend on the records of the view. An annotations view offers the color, Tags, comment, text, page, and dates of each annotation. Every view offers the paper's title, creators, first author, year, item type, Collection, and library. Annotations and attachments views also offer the file's title and file type. An items view also offers the properties of your Literature Notes, as Track reading status shows.
To write a condition as a Filter Expression, select Edit as expression on its row. The expression is colored to make its parts easy to read. Select Edit visually to return to the visual row.
When a condition has an error, its row shows the reason. The view keeps the rows it showed last and shows The filter has an error. The view shows the last results.
Sort and group the rows
Sort
Select Sort, then Add sort. Choose a property and a direction, such as New to old for dates. Add more properties to break ties. Drag a property to change its priority: the first property sorts first.
The properties depend on the records of the view:
| Rows | Sort properties |
|---|---|
| Annotations | Position in the file, page, dates, color, annotation type, and the paper's title, first author, and dates, and the file's title and date added |
| Attachments | Title, dates, and the paper's title, first author, and date |
| Items | Title, first author, date, dates added and modified, item type, and the properties of your Literature Notes |
Group
Select Group, then choose a property in Group by:
| Rows | Group properties |
|---|---|
| Annotations | Item, Attachment, Color, Tag, Collection |
| Attachments | Item, Tag, Collection |
| Items | Item type, Tag, Collection |
Then choose the order of the groups:
- A → Z or Z → A sorts the groups by their value.
- Manual lists the groups. Select the checkbox of a group to show or hide it, and drag a group to change its place. For example, show only the yellow and red groups for one writing task.
A record with several Tags or Collections shows in the group of each one. Records with no value show under No value. In the Annotations, List, and Cards layouts, select a group heading to collapse its rows.
Choose the properties
Select Properties. Select the checkbox of a property to show or hide it, and drag a property to change its place. Type in Find or create… to find a property. To add a property that the list does not have, type its path, such as item.citationKey, and select the row that adds it. In an items view, the menu also offers to add a property of your Literature Notes. See Track reading status.
Select the chevron button on any property row (or press the Right arrow key) to open its settings page, where you can set a display name or edit a formula.
The Table, List, and Cards layouts show these properties in this order. Copy and CSV export use them as columns.
Add a formula
A formula is a property that ZotLit computes for each row from other properties. It uses the same Filter Expression language as a filter condition. For example, a formula can show the year of each paper, or the number of its authors.
To show the year of each paper in an items view:
Open the formula page
Select Properties, then Add formula. The page for the new formula opens in the same menu.
Name the formula
In Name, type year. A name has letters, digits, and underscores, and starts with a letter or an underscore. Letter case counts. The view names the property formula.year.
Write the expression
In Formula, type date.year. A check mark next to the label shows that the text has no syntax errors. When the text has a syntax error, a warning icon shows in its place and the reason shows under the field.
Save
Select Save. The view shows the new property after its other properties, with the year of each paper. The page changes to the page of the new formula.
The file saves the formula under its top-level formulas key, and every view of the file can show it. To filter by a formula, select Edit as expression on a condition in the filter editor and type, for example, formula.year >= 2020. One formula can also use another, for example formula.year + 1.
To change a formula, select Properties. On its row, select the chevron button, tooltipped Edit property, or press the Right arrow key. The page of the formula opens in the same menu. Change the text in Formula. The text saves shortly after you stop typing, when it has no syntax errors. The name stays as it is: to use a new name, remove the formula and add it again. Select Back to return to the list.
To remove a formula, open its page, select More options (…), and select Remove formula. ZotLit removes the formula from every view of the file and returns to the list. A filter condition that still uses it shows an error until you change it.
When a formula has a mistake
A formula that ZotLit Query cannot run, such as title * 2, shows a warning icon on its row in Properties and on its column header in the Table layout. Hover over the icon to read the reason. The other properties of the view stay on screen. A formula that uses the wrong one shows the name of the formula with the mistake. When a filter condition of the view uses the wrong formula, the view shows the error and no rows until you correct it.
A formula can work for most rows and fail on one row. For example, number(volume) fails on a paper whose volume is text, such as "Spring". That row shows a warning icon in its cell, with the reason in a tooltip. Copy and CSV export write Error: and the reason in that cell. A paper with no volume shows an empty cell. Error Values explains the difference.
Rename a property
A display name replaces the path of a property in the view. For example, the property formula.year can show as "Year of source".
Open the property page
Select Properties. On the row of formula.year, select the chevron button, tooltipped Edit property.
Type the name
In Display name, type Year of source. The name saves when you leave the field, press Enter, select Back, or close the menu.
The Table header, the Cards labels, the rows in Properties, and the header row of copy and CSV export show "Year of source". The display name applies to every view of the file. For a new formula, you can also set it in Display name when you add the formula.
To return to the default name, clear the field. Without a display name, a property shows its field name, such as Title, or its path.
Limit, copy, and export the results
Select the result count to open the Results menu:
- Limit number of results: sets the maximum number of rows to show. Clear the field or select Show all (250) to show every match. When more records match than the view shows, the result count displays both numbers, such as 100 of 250 results.
- Copy to clipboard: copies the visible columns of the shown rows to your clipboard as a table. Paste it into an Obsidian note as a Markdown table, or into spreadsheets such as Microsoft Excel, Google Sheets, or Apple Numbers.
- Export CSV…: saves the visible columns of the shown rows as a CSV file. The file uses UTF-8 encoding with a byte order mark so Excel and statistical software such as R or SPSS open international titles and author names cleanly.
Both copy and CSV export include only the properties shown in the view, in their visible order. Interface buttons, such as the Literature note column, are omitted.
Search the rows
Select Search and type. The view shows only the rows on screen that contain the text. Search does not change the file. Clear the field to see every row again.
Use the Table layout
The Table layout displays papers in a grid, similar to the main item list in Zotero. To use it, set the rows to items in Configure view, then choose Table.
View files, notes, and annotations
Select Expand on any paper to reveal its attached files, child notes, and annotations. Expand an attachment to see its individual annotations.
Attachment titles and annotation text in table cells are clickable links:
- Select a PDF attachment to open the file in Obsidian's PDF viewer.
- Select an annotation to open the PDF directly to that page and highlight the mark.
- Select any other file type to open it in Zotero.
Hold Ctrl (Windows and Linux) or Command (macOS) while selecting a link to open it in a new tab.
Arrange and resize columns
You can adjust table columns directly in the view:
- Drag a column header left or right to change column order.
- Drag the boundary between two headers to resize a column width.
- Double-click the boundary between two headers to return the column to its automatic width.
- Select or right-click any column header to open its menu. The menu offers Move left, Move right, and Reset column width.
Resized column widths save automatically in the query file.
Literature note column
The Literature note column opens the paper's Literature Note in Obsidian. When the paper does not have a Literature Note yet, select Create to create one.
This column behaves like any other property: you can show, hide, move, or rename it in Properties. Copy and CSV export leave this column out.
Embed a query file in a note
Type an embed link in any note:
![[Figures.zotquery]]The embed shows the default view. To show another view, add its name after #:
![[Figures.zotquery#Yellow highlights]]The embed has the same toolbar as the tab. A change in the embed saves to the query file, so every note that embeds the file shows it. Select Open query file to open the file in a tab. Embeds work in Reading view, Live Preview, and hover popovers.
To show the annotations of the note's own paper, use this.item in the filter of the view:
filters: item == this.itemIn a Literature Note, this.item is the paper that the note's zotero-key property names. When that paper's library is outside your Library scope setting, the embed shows This item's library is not in the library scope, so the view cannot show it. Add the library to the library scope in ZotLit settings. See this: the paper of the note.
When a view uses this.item or this.attachment without an active context (for example, in a standalone query file tab or an unlinked note), the view displays a suggestion explaining where to open it.
Add a query block to a note
A query block keeps a live view inside one note without creating a separate file. Type a code block with the language zotquery:
```zotquery
views:
- type: annotations
name: Yellow highlights
from: annotations
filters: item == this.item && colorName == "yellow"
```The block shows the view and its toolbar. Any change you make in the toolbar, such as changing sort order, adding filters, or selecting properties, rewrites the block text in your note automatically. This also works when the block shows through a section embed or a hover popover. When the note text changed in the meantime, the block shows The query block could not save. Its text in the note changed; reopen the note and try again. Reopen the note to refresh the view.
Query file format lists every key that you can write.
The block in Literature Notes
The default Literature Note template puts a query block under the Annotations heading. The block shows the annotations of the note's paper. A Literature Note that you made with an earlier version gets the block on its next update. A paper in the Zotero trash shows no annotations there. See Default templates.
Save the annotation sidebar as a query file
The sidebar Zotero annotations has more view controls in its More options menu (⋮):
| Menu item | What it does |
|---|---|
| Sort | Sorts the cards by one property of the annotation, in either direction. |
| Group by | Groups the cards by color or Tag, or None. |
| Filter… | Opens the filter editor for the sidebar. |
| Save as query file… | Saves what the sidebar shows as a new query file. Available while the sidebar shows an item. |
To keep a sidebar filter as a file:
Open the dialog
In the sidebar, open More options and select Save as query file….
Name the file
Type a Name and choose a Folder.
Choose which annotations the file shows
Under Show the annotations of, choose one:
- This item only: the annotations of the attachment that the sidebar shows. When the sidebar shows an item with no attachment chosen, the file shows the annotations of that item.
- The item of the note that shows it: the annotations of the paper of each note that embeds the file. Use this for a file that you embed in many Literature Notes.
Save
Select Save. ZotLit creates the file and opens it in a tab. The file keeps the sidebar's sort, grouping, and filters, including the colors, Tags, and search text that you chose in the sidebar.
See also
Last updated on