IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Add InfluxDB SQL query language docs (#79591)

Browse Source 
* update sql docs

* add note

* add macro docs

* prettier

* prettier again
This commit is contained in:
ismail simsek
2023-12-19 13:27:16 +01:00
committed by GitHub
parent 217084941d
commit 8c7639738d
2 changed files with 128 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/sources/datasources/influxdb/_index.md
View File

@@ -25,26 +25,31 @@ weight: 700
{{< docs/shared lookup="influxdb/intro.md" source="grafana" version="<GRAFANA VERSION>" >}}
Grafana includes built-in support for InfluxDB.
This topic explains options, variables, querying, and other features specific to the InfluxDB data source, which include its [feature-rich code editor for queries and visual query builder]({{< relref "./query-editor" >}}).
This topic explains options, variables, querying, and other features specific to the InfluxDB data source, which include
its [feature-rich code editor for queries and visual query builder]({{< relref "./query-editor" >}}).
For instructions on how to add a data source to Grafana, refer to the [administration documentation][data-source-management].
For instructions on how to add a data source to Grafana, refer to
the [administration documentation][data-source-management].
Only users with the organization administrator role can add data sources.
Administrators can also [configure the data source via YAML](#provision-the-data-source) with Grafana's provisioning system.
Administrators can also [configure the data source via YAML](#provision-the-data-source) with Grafana's provisioning
system.
Once you've added the InfluxDB data source, you can [configure it](#configure-the-data-source) so that your Grafana instance's users can create queries in its [query editor]({{< relref "./query-editor" >}}) when they [build dashboards][build-dashboards] and use [Explore][explore].
Once you've added the InfluxDB data source, you can [configure it](#configure-the-data-source) so that your Grafana
instance's users can create queries in its [query editor]({{< relref "./query-editor" >}}) when
they [build dashboards][build-dashboards] and use [Explore][explore].
## Configure the data source
To configure basic settings for the data source, complete the following steps:
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `InfluxDB` in the search bar.
1. Select **InfluxDB**.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `InfluxDB` in the search bar.
1. Select **InfluxDB**.
The **Settings** tab of the data source is displayed.
The **Settings** tab of the data source is displayed.
1. Set the data source's basic configuration options carefully:
1. Set the data source's basic configuration options carefully:
| Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -82,17 +87,25 @@ You can also override this setting in a dashboard panel under its data source op
InfluxDB data source options differ depending on which query language you select:
- [InfluxQL](https://docs.influxdata.com/influxdb/v1.8/query_language/explore-data/), a SQL-like language for querying InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users.
- [InfluxQL](https://docs.influxdata.com/influxdb/v1.8/query_language/explore-data/), a SQL-like language for querying
InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users.
InfluxQL is available in InfluxDB 1.0 onwards.
- [Flux](https://docs.influxdata.com/influxdb/v2.0/query-data/get-started/), which provides significantly broader functionality than InfluxQL. It supports not only queries but also built-in functions for data shaping, string manipulation, and joining to non-InfluxDB data sources, but also processing time-series data.
- [SQL](https://www.influxdata.com/products/sql/) native SQL language with
support [FlightSQL](https://www.influxdata.com/glossary/apache-arrow-flight-sql/).
- [Flux](https://docs.influxdata.com/influxdb/v2.0/query-data/get-started/), which provides significantly broader
functionality than InfluxQL. It supports not only queries but also built-in functions for data shaping, string
manipulation, and joining to non-InfluxDB data sources, but also processing time-series data.
It's similar to JavaScript with a functional style.
To help choose the best language for your needs, refer to a [comparison of Flux vs InfluxQL](https://docs.influxdata.com/influxdb/v1.8/flux/flux-vs-influxql/) and [why InfluxData created Flux](https://www.influxdata.com/blog/why-were-building-flux-a-new-data-scripting-and-query-language/).
To help choose the best language for your needs, refer to
a [comparison of Flux vs InfluxQL](https://docs.influxdata.com/influxdb/v1.8/flux/flux-vs-influxql/)
and [why InfluxData created Flux](https://www.influxdata.com/blog/why-were-building-flux-a-new-data-scripting-and-query-language/).
{{% admonition type="note" %}}
Though not required, we recommend that you append your query language choice to the data source's **Name** setting:
- InfluxDB-InfluxQL
- InfluxDB-SQL
- InfluxDB-Flux
{{% /admonition %}}
@@ -109,6 +122,15 @@ Configure these options if you select the InfluxQL (classic InfluxDB) query lang
| **Password** | Defines the token you use to query the bucket defined in **Database**. Copy this from the [Tokens page](https://docs.influxdata.com/influxdb/v2.0/security/tokens/view-tokens/) of the InfluxDB UI. |
| **HTTP mode** | Sets the HTTP method used to query your data source. The POST verb allows for larger queries that would return an error using the GET verb. Defaults to GET. |
### Configure SQL
Configure these options if you select the SQL query language:
| Name | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Database** | Sets the ID of the bucket to query. Copy this from the Buckets page of the InfluxDB UI. |
| **Token** | API token used for SQL queries. It can be generated on InfluxDB Cloud dashboard under [Load Data > API Tokens](https://docs.influxdata.com/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) menu. |
### Configure Flux
Configure these options if you select the Flux query language:
@@ -122,7 +144,8 @@ Configure these options if you select the Flux query language:
### Provision the data source
You can define and configure the data source in YAML files as part of Grafana's provisioning system.
For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana][provisioning-data-sources].
For more information about provisioning, and for available configuration options, refer
to [Provisioning Grafana][provisioning-data-sources].
{{% admonition type="note" %}}
`database` [field is deprecated](https://github.com/grafana/grafana/pull/58647).
@@ -180,24 +203,42 @@ datasources:
access: proxy
url: http://localhost:8086
jsonData:
# This database should be mapped to a bucket
dbName: site
httpMode: GET
httpHeaderName1: 'Authorization'
version: SQL
metadata:
- database: <bucket-name>
secureJsonData:
httpHeaderValue1: 'Token <token>'
```
**InfluxDB 3.x for SQL example:**
```yaml
apiVersion: 1
datasources:
- name: InfluxDB_v2_InfluxQL
type: influxdb
access: proxy
url: http://localhost:8086
jsonData:
dbName: site
httpMode: POST
secureJsonData:
token: '<api-token>'
```
## Query the data source
The InfluxDB data source's query editor has two modes, InfluxQL and Flux, depending on your choice of query language in the [data source configuration](#configure-the-data-source):
The InfluxDB data source's query editor has two modes, InfluxQL and Flux, depending on your choice of query language in
the [data source configuration](#configure-the-data-source):
For details, refer to the [query editor documentation]({{< relref "./query-editor" >}}).
## Use template variables
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed
in your dashboard.
Grafana refers to such variables as template variables.
For details, see the [template variables documentation]({{< relref "./template-variables" >}}).
@@ -207,11 +248,14 @@ For details, see the [template variables documentation]({{< relref "./template-v
[build-dashboards]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/build-dashboards"
[data-source-management]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/administration/data-source-management"
[data-source-management]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/administration/data-source-management"
[data-source-management]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>
/administration/data-source-management"
[explore]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/explore"
[explore]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/explore"
[provisioning-data-sources]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/administration/provisioning#data-sources"
[provisioning-data-sources]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/administration/provisioning#data-sources"
[provisioning-data-sources]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>
/administration/provisioning#data-sources"
[provisioning-data-sources]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>
/administration/provisioning#data-sources"
{{% /docs/reference %}}

74
docs/sources/datasources/influxdb/query-editor/index.md
View File

@@ -8,7 +8,7 @@ labels:
- cloud
- enterprise
- oss
title: Flux support in Grafana
title: Query Editor
weight: 200
---
@@ -19,9 +19,11 @@ For general documentation on querying data sources in Grafana, see [Query and tr
## Choose a query editing mode
The InfluxDB data source's query editor has two modes depending on your choice of query language in the [data source configuration]({{< relref "../#configure-the-data-source" >}}):
The InfluxDB data source's query editor has two modes depending on your choice of query language in
the [data source configuration]({{< relref "../#configure-the-data-source" >}}):
- [InfluxQL](#influxql-query-editor)
- [SQL](#sql-query-editor)
- [Flux](#flux-query-editor)
You also use the query editor to retrieve [log data](#query-logs) and [annotate](#apply-annotations) visualizations.
@@ -65,7 +67,8 @@ For example:
This query editor input generates an InfluxDB `SELECT` clause:
```sql
SELECT derivative(mean("value"), 10s) /10 AS "REQ/s" FROM ....
SELECT derivative(mean("value"), 10s) / 10 AS "REQ/s"
FROM....
```
**To select multiple fields:**
@@ -116,15 +119,51 @@ Otherwise, InfluxDB can easily return hundreds of thousands of data points that
You can also use `[[tag_hostname]]` pattern replacement syntax.
For example, entering the value `Host: [[tag_hostname]]` in the ALIAS BY field replaces it with the `hostname` tag value for each legend value.
For example, entering the value `Host: [[tag_hostname]]` in the ALIAS BY field replaces it with the `hostname` tag value
for each legend value.
An example legend value would be `Host: server1`.
## SQL query editor
Grafana support [SQL querying language](https://docs.influxdata.com/influxdb/cloud-serverless/query-data/sql/)
with [InfluxDB v3.0](https://www.influxdata.com/blog/introducing-influxdb-3-0/) and higher.
### Macros
You can use macros within the query to replace them with the values from Grafana's context.
| Macro example | Replaced with |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$__timeFrom` | The start of the currently active time selection, such as `2020-06-11T13:31:00Z`. |
| `$__timeTo` | The end of the currently active time selection, such as `2020-06-11T14:31:00Z`. |
| `$__timeFilter` | The time range that applies the start and the end of currently active time selection. |
| `$__interval` | An interval string that corresponds to Grafana's calculated interval based on the time range of the active time selection, such as `5s`. |
| `$__dateBin(<column>)` | Applies [date_bin](https://docs.influxdata.com/influxdb/cloud-serverless/reference/sql/functions/time-and-date/#date_bin) function. Column must be timestamp. |
| `$__dateBinAlias(<column>)` | Applies [date_bin](https://docs.influxdata.com/influxdb/cloud-serverless/reference/sql/functions/time-and-date/#date_bin) function with suffix `_binned`. Column must be timestamp. |
Examples:
```
// with macro
1. SELECT * FROM cpu WHERE time >= $__timeFrom AND time <= $__timeTo
2. SELECT * FROM cpu WHERE $__timeFilter(time)
3. SELECT $__dateBin(time) from cpu
// interpolated
1. SELECT * FROM iox.cpu WHERE time >= cast('2023-12-15T12:38:30Z' as timestamp) AND time <= cast('2023-12-15T18:38:30Z' as timestamp)
2. SELECT * FROM cpu WHERE time >= '2023-12-15T12:41:28Z' AND time <= '2023-12-15T18:41:28Z'
3. SELECT date_bin(interval '15 second', time, timestamp '1970-01-01T00:00:00Z') from cpu
```
## Flux query editor
Grafana supports Flux when running InfluxDB v1.8 and higher.
If your data source is [configured for Flux]({{< relref "./#configure-the-data-source" >}}), you can use the [Flux query and scripting language](https://www.influxdata.com/products/flux/) in the query editor, which serves as a text editor for raw Flux queries with macro support.
If your data source is [configured for Flux]({{< relref "./#configure-the-data-source" >}}), you can use
the [Flux query and scripting language](https://www.influxdata.com/products/flux/) in the query editor, which serves as
a text editor for raw Flux queries with macro support.
For more information and connection details, refer to [1.8 compatibility](https://github.com/influxdata/influxdb-client-go/#influxdb-18-api-compatibility).
For more information and connection details, refer
to [1.8 compatibility](https://github.com/influxdata/influxdb-client-go/#influxdb-18-api-compatibility).
### Use macros
@@ -150,7 +189,8 @@ from(bucket: v.defaultBucket)
|> yield(name: "mean")
```
Into this query to send to InfluxDB, with interval and time period values changing according to the active time selection:
Into this query to send to InfluxDB, with interval and time period values changing according to the active time
selection:
```flux
from(bucket: "grafana")
@@ -171,10 +211,12 @@ Select the InfluxDB data source, then enter a query to display your logs.
### Create log queries
The Logs Explorer next to the query field, accessed by the **Measurements/Fields** button, lists measurements and fields.
The Logs Explorer next to the query field, accessed by the **Measurements/Fields** button, lists measurements and
fields.
Choose the desired measurement that contains your log data, then choose which field to use to display the log message.
Once InfluxDB returns the result, the log panel lists log rows and displays a bar chart, where the x axis represents the time and the y axis represents the frequency/count.
Once InfluxDB returns the result, the log panel lists log rows and displays a bar chart, where the x axis represents the
time and the y axis represents the frequency/count.
### Filter search
@@ -196,12 +238,17 @@ The **Tags** field's value can be a comma-separated string.
### Annotation query example
```sql
SELECT title, description from events WHERE $timeFilter ORDER BY time ASC
SELECT title, description
from events
WHERE $timeFilter
ORDER BY time ASC
```
{{% docs/reference %}}
[annotate-visualizations]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/build-dashboards/annotate-visualizations"
[annotate-visualizations]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/build-dashboards/annotate-visualizations"
[annotate-visualizations]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>
/dashboards/build-dashboards/annotate-visualizations"
[annotate-visualizations]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>
/dashboards/build-dashboards/annotate-visualizations"
[explore]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/explore"
[explore]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/explore"
@@ -213,5 +260,6 @@ SELECT title, description from events WHERE $timeFilter ORDER BY time ASC
[panel-inspector]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/panel-inspector"
[query-transform-data]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data"
[query-transform-data]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data"
[query-transform-data]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>
/panels-visualizations/query-transform-data"
{{% /docs/reference %}}