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
.
Links
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!