Skip to content

Expressions

Dataview query language expressions are anything that yields a value:

Basically, everything that is not a Query Type, nor a data command is an expression.

For a very high level summary, following is considered an expression in DQL:

# 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)
a % b               (modulo / remainder of 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)

# Strings

a + b               (string concatenation)
a * num             (repeat string <num> times)

# 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 "duedate", then you can refer to it directly by name - duedate. 

```dataview
TABLE duedate, class, field-with-space
```

Field names with spaces and punctuations

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. Read more under Field names

Literals

Constant values - things like 1 or "hello" or date(som) ("start of month"). There are literals for each data type that dataview supports; read more about them here.

```dataview
LIST
WHERE file.name = "Scribble"
```

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.

```dataview
TABLE start, end, (end - start) - dur(8 h) AS "Overtime" 
FROM #work
```

```dataview
TABLE hrs / 24 AS "days"
FROM "30 Projects"
```

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.

```dataview
LIST
FROM "Games"
WHERE price > 10
```

```dataview
TASK
WHERE due <= date(today)
```

```dataview
LIST
FROM #homework
WHERE status != "done"
```

Comparing different types

Comparing different data types with each other can lead to unexpected results. Take the second example: If due is not set (neither on page nor task level), it is null and null <= date(today) returns true, including tasks without any due date. If this is not wanted, add a type check to make sure you're always comparing the same types: 

```dataview
TASK
WHERE typeof(due) = "date" AND due <= date(today)
```
Most often, it is sufficient to check if the meta data is available via WHERE due AND due <= date(today), but checking the type is the safer way to get foreseeable results.

List/Object Indexing

You can retrieve data from lists/arrays via the index operator list[<index>], where <index> is any computed expression. Lists are 0-indexed, so the first element is index 0, the second element is index 1, and so on. For example list("A", "B", "C")[0] = "A".

A similar notation style works for objects. You can use field["nestedfield"] to reference fields inside an object or otherwise similarly nested. For example, in the YAML defined below, we can reference previous via episode_metadata["previous"]. 

---
aliases:
  - "ABC"
current_episode: "S01E03"
episode_metadata:
  previous: "S01E02"
  next: "S01E04"
---

You can also 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 the previous frontmatter example, we could also use episode_metadata.previous to obtain the same value.

Index expressions also work on objects which have fields that are not directly supported by the query language. A good example is where, since it is a keyword. If your frontmatter/metadata contains a field where, you can reference it via the row syntax: row["where"]. See the note in the FAQ and the corresponding issue for further information.

```dataview
TABLE id, episode_metadata.next, aliases[0]
```

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(file.name) or regexmatch("A.+", file.folder).

```dataview
LIST
WHERE contains(file.name, "WIP")
```

```dataview
LIST
WHERE string(file.day.year) = split(this.file.name, "-W")[0]
```

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) => x.field                  (return field of x, often used for map)
(x, y) => x + y                 (sum x and y)
(x) => 2 * x                    (double x)
(value) => length(value) = 4    (return true if value is length 4)

```dataview
CALENDAR file.day
FLATTEN all(map(file.tasks, (x) => x.completed)) AS "allCompleted"
WHERE !allCompleted
```

Type-specific Interactions & Values

Most dataview types have special interactions with operators, or have additional fields that can be retrieved using the index operator. This is true for dates and durations and as well for links. Read more about date and durations on their respective section in Types of Metadata.

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

Link Indexing in Expressions

If your link is a field that you defined in an inline field or in front-matter, like Class:: [[Math]] and you want to get the field timetable, then you index into it by writing Class.timetable. Using [[Class]].timetable would look up the page literally called Class, and not Math!