102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
Live Queries enable a (quasi) live view on various data sources, usually [[Objects]], and renders their results inline via [[Live Preview]] either as a template, or using [[Templates]].
|
||
|
||
## Syntax
|
||
The syntax of live queries are inspired by [SQL](https://en.wikipedia.org/wiki/SQL). Below is a query that demonstrates some of the supported clauses, hover over the result and click the edit icon to shows the code that generates the view:
|
||
```query
|
||
page
|
||
order by lastModified desc
|
||
where size > 100
|
||
select name
|
||
limit 10
|
||
render [[template/page]]
|
||
```
|
||
It’s most convenient to use `/query` [[Slash Commands]] to insert a query in a page.
|
||
|
||
For those comfortable reading such things [here you can find the full query grammar](https://github.com/silverbulletmd/silverbullet/blob/main/common/markdown_parser/query.grammar).
|
||
|
||
The general syntax is to specify a `querySource` followed by a number of clauses that modify or restrict. If you haven’t already, check out how [[Objects]] work in SilverBullet.
|
||
|
||
## Clauses
|
||
## `where` [[@expression]]
|
||
A `where` clause filters out all objects that do not match a certain condition. You can have multiple `where` clauses if you like, which will have the same effect as combining them with the `and` keyword.
|
||
|
||
Here is a simple example based on a custom tag `#person` (see [[Objects]] on how this works):
|
||
|
||
```#person
|
||
name: John
|
||
age: 7
|
||
---
|
||
name: Pete
|
||
age: 25
|
||
```
|
||
|
||
To query all `person`s that are above age 21, we can use the following `where` clause:
|
||
|
||
```query
|
||
person where page = "{{@page.name}}" and age > 21
|
||
```
|
||
## `order by` [[@expression]]
|
||
In order to sort results, a `order by` clause can be used, optionally with `desc` to order in descending order (ascending is the default):
|
||
|
||
```query
|
||
person where page = "{{@page.name}}" order by age desc
|
||
```
|
||
## `limit` [[@expression]]
|
||
To limit the number of results, you can use a `limit` clause:
|
||
|
||
```query
|
||
person where page = "{{@page.name}}" limit 1
|
||
```
|
||
### `select`
|
||
To select only specific attributes from the result set, you can use the `select` clause. You can use it either simply as `select attribute1, attribute2` but also select the value of certain expressions and give them a name via the `select age + 1 as nextYear` syntax:
|
||
|
||
```query
|
||
person
|
||
where page = "{{@page.name}}"
|
||
select name, age, age + 1 as nextYear
|
||
```
|
||
### `render [[template]]`
|
||
By default results are rendered as a table, to instead render each result item using [[Templates|a template]], use the `render` clause:
|
||
|
||
```query
|
||
person
|
||
where page = "{{@page.name}}"
|
||
render [[template/person]]
|
||
```
|
||
## Expressions
|
||
$expression
|
||
|
||
Primitives:
|
||
|
||
* strings: `"a string"`
|
||
* numbers: `10`
|
||
* booleans: `true` or `false`
|
||
* regular expressions: `/[a-z]+/`
|
||
* null: `null`
|
||
* lists: `["value 1", 10, false]`
|
||
|
||
Attributes can be accessed via the `attribute` syntax, and nested attributes via `attribute.subattribute.subsubattribute`.
|
||
|
||
Logical expressions:
|
||
|
||
* and: `name = "this" and age > 10`
|
||
* or: `name = "this" or age > 10`
|
||
|
||
Binary expressions:
|
||
- `=` equals, e.g. `name = "Pete"`
|
||
- `!=` not equals, e.g. `name != "Pete"`
|
||
- `<` less than, e.g. `age < 10`
|
||
- `<=` less than or equals, e.g. `age <= 10`
|
||
- `>` greater than, e.g. `age > 10`
|
||
- `>=` greater than or equals, e.g. `age >= 10`
|
||
- `=~` to match against a regular expression, e.g. `name =~ /^template\//`
|
||
- `!=~` to not match a regular expression, e.g. `name !=~ /^template\//`
|
||
- `in` member of a list (e.g. `prop in ["foo", "bar"]`)
|
||
* `+` addition (can also concatenate strings), e.g. `10 + 12` or `name + "!!!"`
|
||
* `-` subtraction, e.g. `10 - 12`
|
||
* `/` addition, e.g. `10 / 12`
|
||
* `*` multiplication, e.g. `10 * 12`
|
||
* `%` modulo, e.g. `10 % 12`
|
||
|
||
Operator precedence follows standard rules, use parentheses when in doubt, e.g. `(age > 10) or (name = "Pete")`
|