diff --git a/docs/sources/datasources/influxdb/_index.md b/docs/sources/datasources/influxdb/_index.md index bf35526d132..d6421c22871 100644 --- a/docs/sources/datasources/influxdb/_index.md +++ b/docs/sources/datasources/influxdb/_index.md @@ -25,26 +25,31 @@ weight: 700 {{< docs/shared lookup="influxdb/intro.md" source="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: secureJsonData: httpHeaderValue1: '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: '' +``` + ## 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//dashboards/build-dashboards" [data-source-management]: "/docs/grafana/ -> /docs/grafana//administration/data-source-management" -[data-source-management]: "/docs/grafana-cloud/ -> /docs/grafana//administration/data-source-management" +[data-source-management]: "/docs/grafana-cloud/ -> /docs/grafana/ +/administration/data-source-management" [explore]: "/docs/grafana/ -> /docs/grafana//explore" [explore]: "/docs/grafana-cloud/ -> /docs/grafana//explore" -[provisioning-data-sources]: "/docs/grafana/ -> /docs/grafana//administration/provisioning#data-sources" -[provisioning-data-sources]: "/docs/grafana-cloud/ -> /docs/grafana//administration/provisioning#data-sources" +[provisioning-data-sources]: "/docs/grafana/ -> /docs/grafana/ +/administration/provisioning#data-sources" +[provisioning-data-sources]: "/docs/grafana-cloud/ -> /docs/grafana/ +/administration/provisioning#data-sources" {{% /docs/reference %}} diff --git a/docs/sources/datasources/influxdb/query-editor/index.md b/docs/sources/datasources/influxdb/query-editor/index.md index 3889b2d4ee2..61252dac5d2 100644 --- a/docs/sources/datasources/influxdb/query-editor/index.md +++ b/docs/sources/datasources/influxdb/query-editor/index.md @@ -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()` | Applies [date_bin](https://docs.influxdata.com/influxdb/cloud-serverless/reference/sql/functions/time-and-date/#date_bin) function. Column must be timestamp. | +| `$__dateBinAlias()` | 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//dashboards/build-dashboards/annotate-visualizations" -[annotate-visualizations]: "/docs/grafana-cloud/ -> /docs/grafana//dashboards/build-dashboards/annotate-visualizations" +[annotate-visualizations]: "/docs/grafana/ -> /docs/grafana/ +/dashboards/build-dashboards/annotate-visualizations" +[annotate-visualizations]: "/docs/grafana-cloud/ -> /docs/grafana/ +/dashboards/build-dashboards/annotate-visualizations" [explore]: "/docs/grafana/ -> /docs/grafana//explore" [explore]: "/docs/grafana-cloud/ -> /docs/grafana//explore" @@ -213,5 +260,6 @@ SELECT title, description from events WHERE $timeFilter ORDER BY time ASC [panel-inspector]: "/docs/grafana-cloud/ -> /docs/grafana//panels-visualizations/panel-inspector" [query-transform-data]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/query-transform-data" -[query-transform-data]: "/docs/grafana-cloud/ -> /docs/grafana//panels-visualizations/query-transform-data" +[query-transform-data]: "/docs/grafana-cloud/ -> /docs/grafana/ +/panels-visualizations/query-transform-data" {{% /docs/reference %}}