From 93a5a71e621f742b47fdb49d4f11ae6c0ead27b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E5=9B=BD=E5=BF=A0?= <249032432@qq.com>
Date: Mon, 5 Sep 2022 17:21:26 +0800
Subject: [PATCH] [doc] logql: logql engine support exec vector(0) grama
 (#7044)

<!--  Thanks for sending a pull request!  Before submitting:

1. Read our CONTRIBUTING.md guide
2. Name your PR as `<Feature Area>: Describe your change`.
  a. Do not end the title with punctuation. It will be added in the changelog.
  b. Start with an imperative verb. Example: Fix the latency between System A and System B.
  c. Use sentence case, not title case.
  d. Use a complete phrase or sentence. The PR title will appear in a changelog, so help other people understand what your change will be.
3. Rebase your PR if it gets out of sync with main
-->

**What this PR does / why we need it**:
logql engine support exec vector(0) grama.
new PR of :https://github.com/grafana/loki/pull/7023

**Which issue(s) this PR fixes**:
Fixes #6946

**Special notes for your reviewer**:
preview
![image](https://user-images.githubusercontent.com/9583245/188355186-9a74d1ce-f062-45e8-8516-52c89383eeec.png)

<!--
Note about CHANGELOG entries, if a change adds:
* an important feature
* fixes an issue present in a previous release,
* causes a change in operation that would be useful for an operator of Loki to know
then please add a CHANGELOG entry.

For documentation changes, build changes, simple fixes etc please skip this step. We are attempting to curate a changelog of the most relevant and important changes to be easier to ingest by end users of Loki.

Note about the upgrade guide, if this changes:
* default configuration values
* metric names or label names
* changes existing log lines such as the metrics.go query output line
* configuration parameters
* anything to do with any API
* any other change that would require special attention or extra steps to upgrade
Please document clearly what changed AND what needs to be done in the upgrade guide.
-->
**Checklist**
- [ ] Documentation added
- [ ] Tests updated
- [ ] Is this an important fix or new feature? Add an entry in the `CHANGELOG.md`.
- [ ] Changes that require user attention or interaction to upgrade are documented in `docs/sources/upgrading/_index.md`

Co-authored-by: Danny Kopping <dannykopping@gmail.com>
---
 CHANGELOG.md                         |  1 +
 docs/sources/logql/metric_queries.md | 17 +++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26938816d8..81d0d1328e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 #### Loki
 
 ##### Enhancements
+* [7023](https://github.com/grafana/loki/pull/7023) **liguozhong**: logql engine support exec `vector(0)` grammar.
 * [6983](https://github.com/grafana/loki/pull/6983) **slim-bean**: `__timestamp__` and `__line__` are now available in the logql `label_format` query stage.
 * [6821](https://github.com/grafana/loki/pull/6821) **kavirajk**: Introduce new cache type `embedded-cache` which is an in-process cache system that runs loki without the need for an external cache (like memcached, redis, etc). It can be run in two modes `distributed: false` (default, and same as old `fifocache`) and `distributed: true` which runs cache in distributed fashion sharding keys across peers if Loki is run in microservices or SSD mode.
 * [6691](https://github.com/grafana/loki/pull/6691) **dannykopping**: Update production-ready Loki cluster in docker-compose
diff --git a/docs/sources/logql/metric_queries.md b/docs/sources/logql/metric_queries.md
index a26f668b33..2a2d03bdcd 100644
--- a/docs/sources/logql/metric_queries.md
+++ b/docs/sources/logql/metric_queries.md
@@ -121,3 +121,20 @@ The `without` clause removes the listed labels from the resulting vector, keepin
 The `by` clause does the opposite, dropping labels that are not listed in the clause, even if their label values are identical between all elements of the vector.
 
 See [vector aggregation examples](../query_examples/#vector-aggregation-examples) for query examples that use vector aggregation expressions.
+
+## Functions
+
+LogQL supports a set of built-in functions.
+
+- `vector(s scalar)`: returns the scalar s as a vector with no labels. This behaves identically to the [Prometheus `vector()` function](https://prometheus.io/docs/prometheus/latest/querying/functions/#vector).
+  `vector` is mainly used to return a value for a series that would otherwise return nothing; this can be useful when using LogQL to define an alert.
+
+Examples:
+
+- Count all the log lines within the last five minutes for the traefik namespace.
+
+    ```logql
+    sum(count_over_time({namespace="traefik"}[5m])) # will return nothing
+      or
+    vector(0) # will return 0
+    ```