1
0
silverbullet/website/🔌 Query.md
2022-08-09 15:37:47 +02:00

9.1 KiB
Raw Blame History

type: plug
uri: core:query
repo: https://github.com/silverbulletmd/silverbullet
author: Silver Bullet Authors

1. What?

The query plug is a built-in plug implementing the <!-- #query --> mechanism. You can use query plug to automatically receive information from your pages.

2. Syntax

  1. start with: <!-- #query [QUERY GOES HERE] -->
  2. end with: <!-- /query -->
  3. write your query: replace [QUERY GOES HERE] with any query you want using options below
  4. available query options: Usage of options is similar to SQL except special render option. Render option is to use display the data in a format that you created in a separate template
    • where
    • order by
    • limit
    • select
    • render

P.S.: If you are a developer or have a technical knowledge to read a code and would like to know more about syntax, please check out query grammar.

3. How to run a query?

After writing the query, there are three options:

  • Open the command palette and run Materialized Queries: Update
  • Use shortcut: hit Alt-q (Windows, Linux) or Option-q (Mac)
  • Go to another page and come back to the page where query is located

After using one of the options, the “body” of the query is replaced with the new results of the query data will be displayed.

4. Data sources

Available data sources can be categorized as:

  1. Builtin data sources
  2. Data that can be inserted by users
  3. Plugs data sources

Best part about data sources: there is an auto completion. 🎉

Start writing <!— #query or simply use /query slash command, it will show you all available data sources. 🤯

4.1. Available data sources

  • page: list of all pages 📄
  • task: list of all tasks created with [] syntax
  • full-text: use it with where phrase = "SOME_TEXT". List of all pages where SOME_TEXT is mentioned ✍️
  • item: list of ordered and unordered items such as bulleted lists ⏺️
  • tags: list of all hashtags used in all pages
  • link: list of all pages giving a link to the page where query is written 🔗
  • data: You can insert a data using the syntax below 🖥️. You can query the data using data option.
name: John
age: 50
city: Milan
country: Italy
---
name: Jane
age: 53
city: Rome
country: Italy
---
name: Francesco
age: 28
city: Berlin
country: Germany
name age city country page pos
John 50 Milan Italy 🔌 Query 2277
Jane 53 Rome Italy 🔌 Query 2323

4.2 Plugs data sources

Certain plugs can also provide special data sources to query a certain data. Some examples are

  • 🔌 Github provides gh-pull to query PRs for selected repo
  • 🔌 Mattermost provides mm-saved to fetch (by default 15) saved posts in Mattermost

For complete list of data sources, please check plugs pages.

5. Examples

We will walk you through a set of examples starting from very basic one until to format the data using templates.

Our goal in this exercise is to (i) get all plug pages (ii) ordered by last modified time and (iii) display in a nice format.

For the sake of simplicity, we will use page data source and limit the results not to spoil the page.

5.1 Simple query without any condition

Goal: We would like to get the list of all pages.

Result: Look at the data. This is more than we need. The query even gives us template pages. Lets try to limit it in the next step.

name lastModified perm tags type uri repo author
SETTINGS 1659437160849 rw undefined undefined undefined undefined undefined
Silver Bullet 1660051168973 rw undefined undefined undefined undefined undefined
CHANGELOG 1660050383951 rw undefined undefined undefined undefined undefined
Mattermost Plugin 1658755340866 rw undefined undefined undefined undefined undefined
PLUGS 1659437423367 rw undefined undefined undefined undefined undefined
index 1659440751554 rw undefined undefined undefined undefined undefined
template/plug 1658751100952 rw undefined undefined undefined undefined undefined
template/tasks 1657890041936 rw #each undefined undefined undefined undefined
💡 Inspiration 1658133917441 rw undefined undefined undefined undefined undefined
🔌 Backlinks 1658760465195 rw undefined plug ghr:Willyfrog/silverbullet-backlinks https://github.com/Willyfrog/silverbullet-backlinks Guillermo Vayá

5.2 Simple query with a condition

Goal: We would like to get all plug pages and sorted by last modified time.

Result: Okay, this what we wanted but there are also information such as perm, type and lastModified that we don't need.

name lastModified perm type uri repo author
🔌 Query 1660051209241 rw plug core:query https://github.com/silverbulletmd/silverbullet Silver Bullet Authors
🔌 Github 1660050280511 rw plug github:silverbulletmd/silverbullet-github/github.plug.json https://github.com/silverbulletmd/silverbullet-github Zef Hemel
🔌 Mount 1658760601369 rw plug github:silverbulletmd/silverbullet-mount/mount.plug.json https://github.com/silverbulletmd/silverbullet-mount Zef Hemel
🔌 Git 1658760545612 rw plug github:silverbulletmd/silverbullet-github/github.plug.json https://github.com/silverbulletmd/silverbullet-github Zef Hemel
🔌 Ghost 1658760515320 rw plug github:silverbulletmd/silverbullet-ghost/ghost.plug.json https://github.com/silverbulletmd/silverbullet-ghost Zef Hemel

5.3 Query to select only certain fields

Goal: We would like to get all plug pages, select only name, author and repo columns and sort by last modified time.

Result: Okay, this is much better. However, I believe this needs a touch from a visual perspective.

name author repo
🔌 Query Silver Bullet Authors https://github.com/silverbulletmd/silverbullet
🔌 Github Zef Hemel https://github.com/silverbulletmd/silverbullet-github
🔌 Mount Zef Hemel https://github.com/silverbulletmd/silverbullet-mount
🔌 Git Zef Hemel https://github.com/silverbulletmd/silverbullet-github
🔌 Ghost Zef Hemel https://github.com/silverbulletmd/silverbullet-ghost

5.4 Display the data in a format defined by a template

Goal: We would like to display the data from step 5.3 in a nice format using bullet points with links to Plug pages, with author name and link to their GitHub repo.

Result: Here you go. This is the result we would like to achieve 🎉. Did you see how I used render and template/plug in a query? 🚀

PS: You don't need select only certain fields to use templates. Templates are smart enough to get only the information needed to render the data. Therefore, following queries are same in terms of end result when using the templates.

<!-- #query page select name author repo uri where type = "plug" order by lastModified desc limit 5 render [[template/plug]] -->
<!-- #query page where type = "plug" order by lastModified desc limit 5 render [[template/plug]] -->