diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index 11772cf..f6af57e 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -5,4 +5,156 @@ repo: https://github.com/silverbulletmd/silverbullet author: Silver Bullet Authors ``` -The query plug is a built-in plug implementing the `` mechanism. \ No newline at end of file +### 1. What? +The query plug is a built-in plug implementing the `` mechanism. You can use query plug to automatically receive information from your pages. + +### 2. Syntax +1. _start with_: `` +2. _end with_: `` +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](https://github.com/silverbulletmd/silverbullet/blob/main/packages/plugs/query/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. Plug’s data sources + +Best part about data sources: there is an auto completion. πŸŽ‰ + +Start writing ` 20 and country = "Italy" --> +|name|age|city |country|page |pos | +|----|--|-----|-----|---------------|----| +|John|50|Milan|Italy|πŸ”Œ Query |2198| +|Jane|53|Rome |Italy|πŸ”Œ Query |2244| + + +#### 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 | +|--|--|--|--|--|--|--|--| +|index |1659178324000|rw|undefined|undefined|undefined |undefined |undefined | +|Mattermost Plugin|1659108035000|rw|undefined|undefined|undefined |undefined |undefined | +|PLUGS |1659108634000|rw|undefined|undefined|undefined |undefined |undefined | +|Test Data Query |1659179547000|rw|undefined|undefined|undefined |undefined |undefined | +|template/plug |1659108035000|rw|undefined|undefined|undefined |undefined |undefined | +|template/tasks |1659108035000|rw|#each|undefined|undefined |undefined |undefined | +|πŸ’‘ Inspiration |1659108035000|rw|undefined|undefined|undefined |undefined |undefined | +|πŸ”Œ Backlinks |1659108035000|rw|undefined|plug|ghr:Willyfrog/silverbullet-backlinks |https://github.com/Willyfrog/silverbullet-backlinks |Guillermo VayΓ‘| +|πŸ”Œ Ghost |1659108035000|rw|undefined|plug|github:silverbulletmd/silverbullet-ghost/ghost.plug.json |https://github.com/silverbulletmd/silverbullet-ghost |Zef Hemel | +|πŸ”Œ Git |1659108035000|rw|undefined|plug|github:silverbulletmd/silverbullet-github/github.plug.json|https://github.com/silverbulletmd/silverbullet-github|Zef Hemel | + + +#### 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 |1659194185345|rw|plug|core:query |https://github.com/silverbulletmd/silverbullet |Silver Bullet Authors| +|πŸ”Œ Mattermost|1659111156000|rw|plug|github:silverbulletmd/silverbullet-mattermost/mattermost.plug.json|https://github.com/silverbulletmd/silverbullet-mattermost|Zef Hemel | +|πŸ”Œ Backlinks |1659108035000|rw|plug|ghr:Willyfrog/silverbullet-backlinks |https://github.com/Willyfrog/silverbullet-backlinks |Guillermo VayΓ‘ | +|πŸ”Œ Ghost |1659108035000|rw|plug|github:silverbulletmd/silverbullet-ghost/ghost.plug.json |https://github.com/silverbulletmd/silverbullet-ghost |Zef Hemel | +|πŸ”Œ Git |1659108035000|rw|plug|github:silverbulletmd/silverbullet-github/github.plug.json |https://github.com/silverbulletmd/silverbullet-github |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 | +|πŸ”Œ Mattermost|Zef Hemel |https://github.com/silverbulletmd/silverbullet-mattermost| +|πŸ”Œ Backlinks |Guillermo VayΓ‘ |https://github.com/Willyfrog/silverbullet-backlinks | +|πŸ”Œ Ghost |Zef Hemel |https://github.com/silverbulletmd/silverbullet-ghost | +|πŸ”Œ Git |Zef Hemel |https://github.com/silverbulletmd/silverbullet-github | + + +#### 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? πŸš€ + + +* [[πŸ”Œ Query]] by **Silver Bullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet)) +* [[πŸ”Œ Mattermost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-mattermost)) +* [[πŸ”Œ Backlinks]] by **Guillermo VayΓ‘** ([repo](https://github.com/Willyfrog/silverbullet-backlinks)) +* [[πŸ”Œ Ghost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-ghost)) +* [[πŸ”Œ Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github)) + + +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. + +```yaml + +``` + +```yaml + +```