diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index 9a156bf2..4392bfd4 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -9,43 +9,46 @@ author: Silver Bullet Authors The query plug is a built-in plug implementing the `` mechanism. You can use query plug to automatically receive information from your notes. ### 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 general query language except special render option. Render option is to use display the data in a format that you created in a separate template +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 general query language except special render option. Render option is to use display the data in a format that you created in a separate template * `where` * `order` * `limit` * `select` * `render` -5. 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) + +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 two options +After writing the query, there are three options: * Open the **command palette** and run **Materialized Queries: Update** -* Use shortcut: for windows **Alt-q** and for mac **Option-q** +* 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 data will be displayed. ### 4. Data sources -Available data sources can be categorized as +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 ` #### 4.3 Plugs’ data sources -Certain plugs can also give you special options to query a certain data. Some examples are +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 + +For complete list of data sources, please check plugs’ pages. ### 5. Examples -We will walk you through a set of example starting from very basic one all the way to format the data using templates. +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. @@ -88,7 +92,7 @@ For the sake of simplicity, we will use `page` data source and limit the results #### 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 +**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 | |--|--|--|--|--|--|--|--| @@ -104,15 +108,15 @@ For the sake of simplicity, we will use `page` data source and limit the results |πŸ”Œ Git |1659108035000|rw|undefined|plug|github:silverbulletmd/silverbullet-github/github.plug.json|https://github.com/silverbulletmd/silverbullet-github|Zef Hemel | -#### 5.2 Simple query without a condition -**Goal:** We would like to get all plug pages and sorted by last modified time +#### 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 want to show in the page +**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 |1659180816719|rw|plug|core:query |https://github.com/silverbulletmd/silverbullet |Silver Bullet Authors| +|πŸ”Œ Query |1659181148142|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 | @@ -121,9 +125,9 @@ For the sake of simplicity, we will use `page` data source and limit the results #### 5.3 Query to select only certain fields -**Goal:** We would like to get all plug pages, select only `name` and `uri` column and sort by last modified time and +**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 +**Result:** Okay, this is much better. However, I believe this needs a touch from a visual perspective. |name |author |repo | @@ -137,9 +141,9 @@ For the sake of simplicity, we will use `page` data source and limit the results #### 5.4 Display the data in a format defined by a template -**Goal:** We would like to display the data from 5.3 in a nice format using bullet points with links to Plug pages, with author name and link to their GitHub repo. +**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? πŸš€ +**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)) @@ -147,4 +151,15 @@ For the sake of simplicity, we will use `page` data source and limit the results * [[πŸ”Œ 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)) - \ No newline at end of file + + +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 + +```