Obsidian DataView Readme
Treat your obsidian vault as a database which you can query from. Provides a fully-fledged query language for filtering, sorting, and extracting data from your pages. See the Examples section below for some quick examples, or the full reference.
Examples
Show all games in the game folder, sorted by rating, with some metadata:
|
|
List games which are MOBAs or CRPGs.
|
|
List all tasks in un-completed projects:
|
|
List all of the files in the books
folder, sorted by the last time you modifed the file:
|
|
List all files which have a date in their title (of the form yyyy-mm-dd
), and list them by date order.
|
|
Usage
Note: See the full documentation here.
Dataview allows you to write queries over markdown files which can be filtered by folder, tag, and markdown YAML fields; it can then display the resulting data in various formats. All dataviews are embedded code blocks with the general form:
|
|
The first word in a query is always the view type - currently, either:
list
, which just renders a list of files that pass the query filters.table
, which renders files and any selected fields that pass the query filters.task
, which renders all tasks from any files that pass the query filters.
You can query from either #tags
, from "folder"
, or from [[link]]
. You can freely combine these filters into more complicated boolean expressions using and
and or
; if precedence is important, use parentheses.
Fields can be any YAML front-matter field (currently, strings, numbers, ISO dates and durations are supported, with support for ratings, links, and intervals forthcoming), any custom defined field (using the field as field2
syntax). You can obtain fields inside of YAML objects using the .
operator - i.e., Dates.Birthday
for example. Fields can also be functions of other fields - for example, rating + offset
, is a valid field.
Field Specifics
All files have the following implicit attributes:
file.name
: The file title.file.path
: The full file path.file.size
: The size (in bytes) of the file.file.ctime
: The date that the file was created.file.mtime
: The date that the file was last modified.
If the file has a date inside its title (of form yyyy-mm-dd
), it also obtains the following attributes:
file.day
: The date contained in the file title.
Additionally, all of the fields defined in the YAML front-matter are available for querying. You can query inside nested objects using dot notation (so dates.birthday
would get the birthday
object inside the dates
field). Fields can have the following types:
number
: A number like0
or18
or19.37
.date
: A date and time in ISO8601 format -yyyy-mm-ddThh:mm:ss
. Everything after the year and month is optional, so you can just writeyyyy-mm
oryyyy-mm-dd
oryyyy-mm-ddThh
. If you want to use a date in a query, usedate(<date>)
where<date>
is either a date,today
,tomorrow
,eom
(end of month), oreoy
(end of year).- You can access date fields like ‘years’ and so on via dot-notation (i.e.,
date(today).year
).
- You can access date fields like ‘years’ and so on via dot-notation (i.e.,
duration
: A length of time - can be added/subtracted from dates. Has the format<number> years/months/.../seconds
, where the unit can be years, months, weeks, days, hours, minutes, or seconds. If you want to use a duration in a query, usedur(<duration>)
.- You can access duration fields like ‘years’ and so on via dot-notation (i.e.,
dur(<duration>).years
).
- You can access duration fields like ‘years’ and so on via dot-notation (i.e.,
link
: An obsidian link (in the same format); you can use dot-notation to get fields in the linked file. For example,[[2020-09-20]].file.ctime
would get the creation time of the2020-09-20
note.array
: A list of elements. Automatically created by YAML lists in the frontmatter; can manually be created usinglist(elem1, elem2, ...)
.object
: A mapping of name -> value. Automatically created from YAML objects. You can access elements inside an object using dot-notation or array notation (object.field
orobject["field"]
).string
: Generic fallback; if a field is not a more specific type, it is a string, which is just text. To use a string in a query, use quotes - so"string"
.