From f816149e6bd11c646cef550087ea266dc1f80245 Mon Sep 17 00:00:00 2001 From: "Sinan Sonmez (Chaush)" Date: Sun, 21 Aug 2022 20:23:30 +0000 Subject: [PATCH 1/6] operators are added --- website/πŸ”Œ Query.md | 71 +++++++++++++++++++++++++++------------------ 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index db366b6..0f468b5 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -12,7 +12,7 @@ The query plug is a built-in plug implementing the `` mechanism. 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 +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` @@ -21,6 +21,19 @@ The query plug is a built-in plug implementing the `` mechanism. 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). +#### 2.1. Available query operators: +* `=` equals +* `!=` not equals +* `<` less than +* `<=` less than or equals +* `>` greater than +* `>=` greater than or equals +* `=~` to match against a regular expression +* `!=~` does not match this regular expression +* `in` to specify multiple values in a `WHERE` clause + +Further, you can combine multiple of these with `and`. Example `prop =~ /something/ and prop != β€œsomething”`. + ### 3. How to run a query? After writing the query, there are three options: * Open the **command palette** and run **Materialized Queries: Update** @@ -71,7 +84,7 @@ country: Germany #### 4.2 Plugs’ data sources -Certain plugs can also provide special data sources 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 @@ -91,16 +104,16 @@ For the sake of simplicity, we will use `page` data source and limit the results |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Γ‘| +|SETTINGS |1661112513714|rw|undefined|undefined|undefined |undefined |undefined | +|Silver Bullet |1661112513714|rw|undefined|undefined|undefined |undefined |undefined | +|CHANGELOG |1661112513714|rw|undefined|undefined|undefined |undefined |undefined | +|Mattermost Plugin|1661112513714|rw|undefined|undefined|undefined |undefined |undefined | +|PLUGS |1661112513714|rw|undefined|undefined|undefined |undefined |undefined | +|index |1661112513714|rw|undefined|undefined|undefined |undefined |undefined | +|template/plug |1661112513718|rw|undefined|undefined|undefined |undefined |undefined | +|template/tasks |1661112513718|rw|#each|undefined|undefined |undefined |undefined | +|πŸ’‘ Inspiration |1661112513718|rw|undefined|undefined|undefined |undefined |undefined | +|πŸ”Œ Backlinks |1661112513718|rw|undefined|plug|ghr:Willyfrog/silverbullet-backlinks|https://github.com/Willyfrog/silverbullet-backlinks|Guillermo VayΓ‘| #### 5.2 Simple query with a condition @@ -109,13 +122,13 @@ For the sake of simplicity, we will use `page` data source and limit the results **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 | +|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 | +|πŸ”Œ Backlinks|1661112513718|rw|plug|ghr:Willyfrog/silverbullet-backlinks |https://github.com/Willyfrog/silverbullet-backlinks |Guillermo VayΓ‘ | +|πŸ”Œ Core |1661112513718|rw|plug|builtin:core |https://github.com/silverbulletmd/silverbullet |Silver Bullet Authors| +|πŸ”Œ Ghost |1661112513718|rw|plug|github:silverbulletmd/silverbullet-ghost/ghost.plug.json |https://github.com/silverbulletmd/silverbullet-ghost |Zef Hemel | +|πŸ”Œ Git |1661112513718|rw|plug|github:silverbulletmd/silverbullet-github/github.plug.json|https://github.com/silverbulletmd/silverbullet-github|Zef Hemel | +|πŸ”Œ Github |1661112513718|rw|plug|github:silverbulletmd/silverbullet-github/github.plug.json|https://github.com/silverbulletmd/silverbullet-github|Zef Hemel | @@ -125,13 +138,13 @@ For the sake of simplicity, we will use `page` data source and limit the results **Result:** Okay, this is much better. However, I believe this needs a touch from a visual perspective. -|name |author |repo | +|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 | +|πŸ”Œ Backlinks|Guillermo VayΓ‘ |https://github.com/Willyfrog/silverbullet-backlinks | +|πŸ”Œ Core |Silver Bullet Authors|https://github.com/silverbulletmd/silverbullet | +|πŸ”Œ Ghost |Zef Hemel |https://github.com/silverbulletmd/silverbullet-ghost | +|πŸ”Œ Git |Zef Hemel |https://github.com/silverbulletmd/silverbullet-github| +|πŸ”Œ Github |Zef Hemel |https://github.com/silverbulletmd/silverbullet-github| #### 5.4 Display the data in a format defined by a template @@ -141,14 +154,14 @@ For the sake of simplicity, we will use `page` data source and limit the results **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)) -* [[πŸ”Œ Github]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github)) -* [[πŸ”Œ Mount]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-mount)) -* [[πŸ”Œ Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github)) +* [[πŸ”Œ Backlinks]] by **Guillermo VayΓ‘** ([repo](https://github.com/Willyfrog/silverbullet-backlinks)) +* [[πŸ”Œ Core]] by **Silver Bullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet)) * [[πŸ”Œ Ghost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-ghost)) +* [[πŸ”Œ Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github)) +* [[πŸ”Œ Github]] 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. +PS: You don't need to 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 From e3ddc660e2eab1f2fd5c12f287db5caa872f90fc Mon Sep 17 00:00:00 2001 From: "Sinan Sonmez (Chaush)" Date: Sun, 21 Aug 2022 20:35:32 +0000 Subject: [PATCH 2/6] how to create a template --- website/πŸ”Œ Query.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index 0f468b5..82ecc95 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -30,7 +30,7 @@ P.S.: If you are a developer or have a technical knowledge to read a code and wo * `>=` greater than or equals * `=~` to match against a regular expression * `!=~` does not match this regular expression -* `in` to specify multiple values in a `WHERE` clause +* `in` to specify multiple values in a `where` clause Further, you can combine multiple of these with `and`. Example `prop =~ /something/ and prop != β€œsomething”`. @@ -88,16 +88,23 @@ Certain plugs can also provide special data sources to query a certain data. Som * [[πŸ”Œ 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 a complete list of data sources, please check plugs’ pages. -### 5. Examples +### 5. Templates +Templates are predefined formats to render the body of the query. + +#### 5.1 How to create a template? +It is pretty easy. You just need to create a new page. However, it is recommended to create your templates using `template/[TEMPLATE_NAME]` convention. For this guide, we will create `template/plug` which we will use in the example 6.4 below. + + +### 6. 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 +#### 6.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. @@ -116,7 +123,7 @@ For the sake of simplicity, we will use `page` data source and limit the results |πŸ”Œ Backlinks |1661112513718|rw|undefined|plug|ghr:Willyfrog/silverbullet-backlinks|https://github.com/Willyfrog/silverbullet-backlinks|Guillermo VayΓ‘| -#### 5.2 Simple query with a condition +#### 6.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. @@ -132,7 +139,7 @@ For the sake of simplicity, we will use `page` data source and limit the results -#### 5.3 Query to select only certain fields +#### 6.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. @@ -147,7 +154,7 @@ For the sake of simplicity, we will use `page` data source and limit the results |πŸ”Œ Github |Zef Hemel |https://github.com/silverbulletmd/silverbullet-github| -#### 5.4 Display the data in a format defined by a template +#### 6.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. From af16ff97ac7d3a2a874efdb3ca1d71d3f656e4b7 Mon Sep 17 00:00:00 2001 From: "Sinan Sonmez (Chaush)" Date: Sun, 21 Aug 2022 20:45:32 +0000 Subject: [PATCH 3/6] What is the syntax --- website/πŸ”Œ Query.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index 82ecc95..d63bab3 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -79,8 +79,8 @@ country: Germany |name|age|city |country|page |pos | |----|--|-----|-----|--------|----| -|John|50|Milan|Italy|πŸ”Œ Query|2277| -|Jane|53|Rome |Italy|πŸ”Œ Query|2323| +|John|50|Milan|Italy|πŸ”Œ Query|2696| +|Jane|53|Rome |Italy|πŸ”Œ Query|2742| #### 4.2 Plugs’ data sources @@ -94,8 +94,20 @@ For a complete list of data sources, please check plugs’ pages. Templates are predefined formats to render the body of the query. #### 5.1 How to create a template? -It is pretty easy. You just need to create a new page. However, it is recommended to create your templates using `template/[TEMPLATE_NAME]` convention. For this guide, we will create `template/plug` which we will use in the example 6.4 below. +It is pretty easy. You just need to create a new page. However, it is recommended to create your templates using `template/[TEMPLATE_NAME]` convention. For this guide, we will create `template/plug` to display list of Plugs available in Silver Bullet. We will use this template in the example section below. +#### 5.2 What is the syntax? +We are using Handlebars which is a simple templating language. It is using double curly braces and name of parameter to be injected. For our `template/plug`, we are using simple template like below. + +`* [[{{name}}]] by **{{author}}** ([repo]({{repo}}))` + +Let me explain the each part +* `* ` is creating a bullet point for each item in Silver Bullet +* `[[{{name}}]]` is injecting the name of Plug and creating an internal link to the page of the Plug +* `**{{author}}**` is injecting the author of the Plug and making it bold +* `([repo]({{repo}}))` is injecting the name of the Plug and creating an external link to GitHub page of the Plug + +For more information on the Handlebars syntax, you can read the [official documentation](https://handlebarsjs.com/). ### 6. Examples We will walk you through a set of examples starting from very basic one until to format the data using templates. @@ -131,11 +143,11 @@ For the sake of simplicity, we will use `page` data source and limit the results |name |lastModified |perm|type|uri |repo |author | |--|--|--|--|--|--|--| +|πŸ”Œ Query |1661114193972|rw|plug|core:query |https://github.com/silverbulletmd/silverbullet |Silver Bullet Authors| |πŸ”Œ Backlinks|1661112513718|rw|plug|ghr:Willyfrog/silverbullet-backlinks |https://github.com/Willyfrog/silverbullet-backlinks |Guillermo VayΓ‘ | |πŸ”Œ Core |1661112513718|rw|plug|builtin:core |https://github.com/silverbulletmd/silverbullet |Silver Bullet Authors| |πŸ”Œ Ghost |1661112513718|rw|plug|github:silverbulletmd/silverbullet-ghost/ghost.plug.json |https://github.com/silverbulletmd/silverbullet-ghost |Zef Hemel | |πŸ”Œ Git |1661112513718|rw|plug|github:silverbulletmd/silverbullet-github/github.plug.json|https://github.com/silverbulletmd/silverbullet-github|Zef Hemel | -|πŸ”Œ Github |1661112513718|rw|plug|github:silverbulletmd/silverbullet-github/github.plug.json|https://github.com/silverbulletmd/silverbullet-github|Zef Hemel | @@ -147,11 +159,11 @@ For the sake of simplicity, we will use `page` data source and limit the results |name |author |repo | |--|--|--| +|πŸ”Œ Query |Silver Bullet Authors|https://github.com/silverbulletmd/silverbullet | |πŸ”Œ Backlinks|Guillermo VayΓ‘ |https://github.com/Willyfrog/silverbullet-backlinks | |πŸ”Œ Core |Silver Bullet Authors|https://github.com/silverbulletmd/silverbullet | |πŸ”Œ Ghost |Zef Hemel |https://github.com/silverbulletmd/silverbullet-ghost | |πŸ”Œ Git |Zef Hemel |https://github.com/silverbulletmd/silverbullet-github| -|πŸ”Œ Github |Zef Hemel |https://github.com/silverbulletmd/silverbullet-github| #### 6.4 Display the data in a format defined by a template @@ -161,11 +173,11 @@ For the sake of simplicity, we will use `page` data source and limit the results **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)) * [[πŸ”Œ Backlinks]] by **Guillermo VayΓ‘** ([repo](https://github.com/Willyfrog/silverbullet-backlinks)) * [[πŸ”Œ Core]] by **Silver Bullet Authors** ([repo](https://github.com/silverbulletmd/silverbullet)) * [[πŸ”Œ Ghost]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-ghost)) * [[πŸ”Œ Git]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github)) -* [[πŸ”Œ Github]] by **Zef Hemel** ([repo](https://github.com/silverbulletmd/silverbullet-github)) PS: You don't need to select only certain fields to use templates. Templates are smart enough to get only the information needed to render the data. From 03547ca9d0e003490965658c4a1d58f87c3a4d8e Mon Sep 17 00:00:00 2001 From: "Sinan Sonmez (Chaush)" Date: Sun, 21 Aug 2022 20:49:49 +0000 Subject: [PATCH 4/6] How to use the template? --- website/πŸ”Œ Query.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index d63bab3..bec5982 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -94,14 +94,14 @@ For a complete list of data sources, please check plugs’ pages. Templates are predefined formats to render the body of the query. #### 5.1 How to create a template? -It is pretty easy. You just need to create a new page. However, it is recommended to create your templates using `template/[TEMPLATE_NAME]` convention. For this guide, we will create `template/plug` to display list of Plugs available in Silver Bullet. We will use this template in the example section below. +It is pretty easy. You just need to create a new page. However, it is recommended to create your templates using `template/[TEMPLATE_NAME]` convention. For this guide, we will create `template/plug` to display list of Plugs available in Silver Bullet. We will use this template in the Examples section below. #### 5.2 What is the syntax? We are using Handlebars which is a simple templating language. It is using double curly braces and name of parameter to be injected. For our `template/plug`, we are using simple template like below. `* [[{{name}}]] by **{{author}}** ([repo]({{repo}}))` -Let me explain the each part +Let me break it down for you * `* ` is creating a bullet point for each item in Silver Bullet * `[[{{name}}]]` is injecting the name of Plug and creating an internal link to the page of the Plug * `**{{author}}**` is injecting the author of the Plug and making it bold @@ -109,6 +109,13 @@ Let me explain the each part For more information on the Handlebars syntax, you can read the [official documentation](https://handlebarsjs.com/). +#### 5.3 How to use the template? +You just need to add `render` keyword followed by the link of the template to the query like below: + +`#query page where type = "plug" render [[template/plug]]` + +You can see the usage of our template in the example 6.4 below. + ### 6. Examples We will walk you through a set of examples starting from very basic one until to format the data using templates. From 3b3be20cd80e7a6fe92d635682b03c2baaddd4b0 Mon Sep 17 00:00:00 2001 From: "Sinan Sonmez (Chaush)" <37421564+sinansonmez@users.noreply.github.com> Date: Mon, 22 Aug 2022 12:25:17 +0200 Subject: [PATCH 5/6] =?UTF-8?q?Update=20website/=F0=9F=94=8C=20Query.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Guillermo VayΓ‘ --- website/πŸ”Œ Query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index bec5982..866e948 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -88,7 +88,7 @@ Certain plugs can also provide special data sources to query a certain data. Som * [[πŸ”Œ Github]] provides `gh-pull` to query PRs for selected repo * [[πŸ”Œ Mattermost]] provides `mm-saved` to fetch (by default 15) saved posts in Mattermost -For a complete list of data sources, please check plugs’ pages. +For a complete list of data sources, please check plugs’ own pages. ### 5. Templates Templates are predefined formats to render the body of the query. From a93170036444befc7705e1ede0252aa59628c0a5 Mon Sep 17 00:00:00 2001 From: "Sinan Sonmez (Chaush)" <37421564+sinansonmez@users.noreply.github.com> Date: Mon, 22 Aug 2022 17:13:45 +0200 Subject: [PATCH 6/6] delete `in` operator --- website/πŸ”Œ Query.md | 1 - 1 file changed, 1 deletion(-) diff --git a/website/πŸ”Œ Query.md b/website/πŸ”Œ Query.md index 866e948..14033d1 100644 --- a/website/πŸ”Œ Query.md +++ b/website/πŸ”Œ Query.md @@ -30,7 +30,6 @@ P.S.: If you are a developer or have a technical knowledge to read a code and wo * `>=` greater than or equals * `=~` to match against a regular expression * `!=~` does not match this regular expression -* `in` to specify multiple values in a `where` clause Further, you can combine multiple of these with `and`. Example `prop =~ /something/ and prop != β€œsomething”`.