feat: add docs for WITH templates

README.md

@@ -2,6 +2,15 @@
 The VictoriaMetrics data source plugin allows you to query and visualize VictoriaMetrics
 data from within Grafana.
 
+* [Motivation](#motivation)
+* [Installation](#installation)
+* [Configure the Datasource with Provisioning](#configure-the-datasource-with-provisioning)
+* [Getting started development](#configure-the-datasource-with-provisioning)
+* [How to make new release](#how-to-make-new-release)
+* [How to use WITH templates](#how-to-make-new-release)
+* [Learn more](#learn-more)
+* [License](#license)
+
 ## Motivation
 
 VictoriaMetrics always recommended using [Prometheus datasource](https://docs.victoriametrics.com/#grafana-setup)
@@ -240,6 +249,53 @@ parts into `dist` folder.
    and this release contains all the needed binaries and checksums.
 5. Remove the `draft` checkbox for the `TAG` release and manually publish it.
 
+## How to use WITH templates
+
+The `WITH` templates feature simplifies the construction and management of complex queries.
+You can try this feature in the [WITH templates playground](https://play.victoriametrics.com/select/accounting/1/6a716b0f-38bc-4856-90ce-448fd713e3fe/expand-with-exprs).
+
+The "WITH templates" settings section allows you to create expressions with templates that can be used in dashboards.
+
+### Defining WITH Expressions
+
+1. Open the datasource settings. Scroll to the bottom of the page and find the "WITH templates" section.
+2. Find the dashboard for which you want to add a `WITH` template expression.
+3. Enter the expression in the input field. Once done, press the `Save` button on the datasource to apply the changes. For example:
+   ```
+   commonFilters = {instance=~"$node:$port",job=~"$job"},
+   
+   # `cpuCount` is the number of CPUs on the node
+   cpuCount = count(count(node_cpu_seconds_total{commonFilters}) by (cpu)),
+   
+   # `cpuIdle` is the sum of idle CPU cores
+   cpuIdle = sum(rate(node_cpu_seconds_total{mode='idle',commonFilters}[5m]))
+   ```
+
+You can specify a comment before the variable and use markdown in it. The comment will be displayed as a hint during auto-completion. The comment can span multiple lines.
+
+The expression will be validated when the input field loses focus and the validation result will be displayed below the input field.
+
+### Using WITH Expressions
+
+1. Open the panel inside the dashboard for which you created the expression. As you type your query, auto-complete hints will appear, including the expressions you've defined.
+2. You can also see all the defined expressions for the current panel by clicking on the `WITH templates` button on the page.
+3. Enter the query in the input field:
+   ```
+   ((cpuCount - cpuIdle) * 100) / cpuCount
+   ```
+
+   Thus, the entire query will look as follows:
+
+   ```
+   WITH (
+    commonFilters = {instance=~"$node:$port",job=~"$job"},
+    cpuCount = count(count(node_cpu_seconds_total{commonFilters}) by (cpu)),
+    cpuIdle = sum(rate(node_cpu_seconds_total{mode='idle',commonFilters}[5m]))
+   )
+   ((cpuCount - cpuIdle) * 100) / cpuCount
+   ```
+   To view the raw query in the interface, enable the `Raw` toggle.
+
 ## Learn more
 
 - [Configure Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/)