Skip to content

Expressions

Dataview query language expressions are anything that yields a value - all fields are expressions, as are literal values (like 6), as are computed values (like field - 9). For a very high level summary:

# Literals
1                   (number)
true/false          (boolean)
"text"              (text)
date(2021-04-18)    (date)
dur(1 day)          (duration)
[[Link]]            (link)
[1, 2, 3]           (list)
{ a: 1, b: 2 }      (object)

# Lambdas
(x1, x2) => ...     (lambda)

# References
field               (directly refer to a field)
simple-field        (refer to fields with spaces/punctuation in them like "Simple Field!")
a.b                 (if a is an object, retrieve field named 'b')
a[expr]             (if a is an object or array, retrieve field with name specified by expression 'expr')
f(a, b, ...)        (call a function called `f` on arguments a, b, ...)

# Arithmetic
a + b               (addition)
a - b               (subtraction)
a * b               (multiplication)
a / b               (division)

# Comparison
a > b               (check if a is greater than b)
a < b               (check if a is less than b)
a = b               (check if a equals b)
a != b              (check if a does not equal b)
a <= b              (check if a is less than or equal to b)
a >= b              (check if a is greater than or equal to b)

# Special Operations
[[Link]].value      (fetch `value` from page `Link`)

More detailed explanations of each follow.

Expression Types

Fields as Expressions

The simplest expression is one that just directly refers to a field. If you have a field called "field", then you can refer to it directly by name - field. If the field name has spaces, punctuation, or other non-letter/number characters, then you can refer to it using Dataview's simplified name, which is all lower case with spaces replaced with "-". For example, this is a field becomes this-is-a-field; Hello! becomes hello, and so on.

Literals

Constant values - things like 1 or "hello" or date(som) ("start of month"). There are literals for each data type that dataview supports; you can see the reference above for examples of what each literal type looks like.

Arithmetic

You can use standard arithmetic operators to combine fields: addition (+), subtraction (-), multiplication (*), and division (/). For example field1 + field2 is an expression which computes the sum of the two fields.

Comparisons

You can compare most values using the various comparison operators: <, >, <=, >=, =, !=. This yields a boolean true or false value which can be used in WHERE blocks in queries.

Array/Object Indexing

You can retrieve data from arrays via the index operator array[<index>], where <index> is any computed expression. Arrays are 0-indexed, so the first element is index 0, the second element is index 1, and so on. For example list(1, 2, 3)[0] = 1.

You can retrieve data from objects (which map text to data values) also using the index operator, where indexes are now strings/text instead of numbers. You can also use the shorthand object.<name>, where <name> is the name of the value to retrieve. For example object("yes", 1).yes = 1.

Function Calls

Dataview supports various functions for manipulating data, which are described in full in the functions documentation. They have the general syntax function(arg1, arg2, ...) - i.e., lower("yes") or regexmatch("text", ".+").

Lambdas

Lambdas are advanced literals which let you define a function that takes some number of inputs, and produces an output. They have the general form:

(arg1, arg2, arg3, ...) => <expression using args>

Lambdas are used in several advanced operators like reduce and map to allow for complex transformations of data. A few examples:

(x, y) => x + y                 (sum x and y)
(x) => 2 * x                    (double x)
(value) => length(value) = 4    (return true if value is length 4)

Type-specific Interactions & Values

Most dataview types have special interactions with operators, or have additional fields that can be retrieved using the index operator.

Dates

You can retrieve various components of a date via indexing: date.year, date.month, date.day, date.hour, date.minute, date.second, date.week, date.weekyear. You can also add durations to dates to get new dates.

Durations

Durations can be added to each other or to dates. You can retrieve various components of a duration via indexing: duration.years, duration.months, duration.days, duration.hours, duration.minutes, duration.seconds.

You can "index through" a link to get values on the corresponding page. For example [[Link]].value would get the value value from page Link.

Link Indexing in Expressions

If your link is a field that you defined in an inline field or in front-matter, like Key:: [[Link]], then you should index into it by just writing Key.value; Using [[Key]].value would look up the page literally called Key, which is probably not what you want!