Summary

This cheatsheet provides a handy reference guide for writing queries using Dataview Query Language (DQL) in the dataview plugin for Obsidian.md note-taking app.

How to use this

I recommend copying this file and including it in your Obsidian vault for easy reference. In this way, you can access the cheatsheet by pulling up the file or searching in your vault for a specific command.

Star and fork this repository to see updates and pull them when more examples are added or the list of commands is expanded.

Table of Contents

• Query Commands
  • LIST
    • Simple List
    • Table
• Data Commands
  • FROM
    • Tags
    • Single Files
    • Folders
    • Excluding Notes
      • Excluding notes with a specific tag
      • Excluding notes from a specific folder
    • Chaining Resources
      • AND operator
      • OR operator
  • WHERE
    • WHERE property is NOT empty
    • WHERE property is equal to something
  • SORT
  • GROUP BY
    • GROUP BY category
  • FLATTEN
    • Multiple properties displayed in its own row
  • Limit results in query
  • Extras
    • Bool property to custom display value
    • Files with outlinks to other files
    • List overdue tasks
• Metadata Reference
  • JSON
  • YAML

Query Cheatsheet

LIST

Simple List

LIST
FROM
  <tag-name>

Example

LIST
FROM
  #library

Table

TABLE
  Title
  Author
FROM
  #library

Back to Contents

Data Commands

• FROM
• WHERE
• SORT
• GROUP BY
• FLATTEN
• LIMIT

FROM

Selecting from different sources such as;

Tags

FROM #tag

Example

TABLE
  file.cday as "Created Date"
FROM
  #my-tag

Single Files

FROM "path/to/file-name"

Example

TABLE
  file.cday as "Created Date"
FROM
  "TopFolder/SubFolder/my-file-name"

Folders

FROM "folder-name"

Example

TABLE
  file.cday as "Created Date"
FROM
  "my-folder-name"

Excluding Notes

Excluding notes with a specific tag

!#tag-name

Example

TABLE
  Title,
  Rating,
  Seen,
  SeenDate as "Seen on"
FROM
  #movie AND !#template

The above example will return all notes with a tag #movie but exclude notes with a tag #template. This is handy if you have a note with pre-populated tags but it's only used as a template so you don't want to see it in your table view.

Excluding notes from a specific folder

FROM #tag AND !"FolderName"

Example

TABLE
  Title,
  Rating,
  Seen,
  SeenDate as "Seen on"
FROM
  #movie AND !"TemplatesFolder"

By including !"FolderName" we specify that we do not want to return any matches if the are located in the specified folder.

Chaining Resources

You can fine tune query parameters utilizing the AND and OR operators

AND

The AND operator queries notes that meet all criteria included in the query:

TABLE
  Title,
  Author,
  Publication
FROM
  "Books" AND "Magazines"

Using in conjunction with exclusion:

TABLE
  Title,
  Author,
  Publication
FROM
  "Books" AND "Books/assets"

OR

The OR operator queries notes that meet any of the provided criteria:

TABLE
  Title,
  Author,
  Publication
FROM
  #horror OR #comedy

Using in conjunction with exclusion:

TABLE
  Title
  Author
  Publication
FROM
  #horror OR #comedy AND !"Books/assets"

Back to Contents

WHERE

Examples of queries containing WHERE clause.

WHERE property is NOT empty

WHERE
  <property-name>

Example

TABLE
  file.cday as "Created",
  Category
FROM
  #books
SORT
  file.cday
WHERE
  Category

The above example ensures to show only results where the meta-data 'Category' is not empty.

WHERE property is equal to something

WHERE
  <string-property-name> = "my-value"

WHERE
  <digit-property-name> = 123

Examples

LIST
WHERE
  category = "my-value"

LIST
WHERE
  digitProperty = 123

Back to Contents

SORT

Dataview offers simple ways to sort results. The most simplistic is by some property in ascending (asc) or descending (desc) order:

TABLE
  Title,
  Author,
  Published,
  Year
FROM
  #library
SORT
  Year asc

This should serve well for most use-cases. More complex sorting mechanisms will added here at a later time.

Back to Contents

GROUP BY

The simplest method is to group by some property included in your frontmatter:

GROUP BY
  <property-name>

Group by category in a table:

TABLE
  rows.file.name as "File"
WHERE
  category
GROUP BY
  category

Group by category in a list:

LIST
  rows.file.name
WHERE
  category = "first-category"
GROUP BY
  category

NOTE: When using GROUP BY, the structure of the results changes. Instead of directly accessing file.name, you must use the rows property to access the file properties within each group. This is because results are now grouped into rows based on the GROUP BY field.

Back to Contents

FLATTEN

Use FLATTEN to display multiple properties in a single row

FLATTEN
  <property-name>

Code example:

TABLE
  Title,
  Action
FLATTEN
  Action

Result example:

Back to Contents

LIMIT

You can limit the results in a query:

LIMIT
  <numerical-value>

Example:

TABLE
  Title,
  Rating
WHERE
  Rating > 3
LIMIT
  10

Extras

Bool property to custom display value

Dataview provides options on how to display various forms of data. For example, Booleans can be displayed as Yes/No instead of True/False:

CHOICE(<bool-property>, "Yes", "No") as "custom-name"

Example

TABLE
  Author as "Author",
  choice(read, "Yes", "No") as "Read",
FROM
  "Books"

Files with outlinks to other files

Should you want to list all files referencing another file using an outlink, you can use contains in the WHERE

contains(file.outlinks, [[Note title]])

Example:

LIST
WHERE
    contains(file.outlinks, [[My books]])

This would list all files which include at least one outlink to [[My books]].

List overdue tasks

To list all the tasks that are past due, we can use due in the WHERE clause:

due > date(today)

However, this would also include the tasks that have no due date, which is not what we want. To avoid this, we can check on the typeof due value:

typeof(due) = "date"

Example:

TASK
WHERE
    !completed
    AND due < date(today)
    AND typeof(due) = "date"

Back to Contents

Metadata Reference

Obsidian allows YAML and JSON for metadata.

JSON

JSON

{
  "Author": "Author Name",
  "Genre": "Fiction",
  "DateRead": "2022-06-01",
  "Read": false,
  "Tags": [
    "Mind-blowing",
    "Interesting",
    "Science"
  ]
}

YAML

YAML

Author: Author Name
Genre: Fiction
DateRead: '2022-06-01'
Read: false
Tags:
- Mind-blowing
- Interesting
- Science