Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: Improve v8 upgrade notes for SQL data sources #38792

Merged
merged 8 commits into from
Sep 10, 2021
Merged

Docs: Improve v8 upgrade notes for SQL data sources #38792

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3a8db4b
Docs: Improve v8 upgrade notes for SQL data sources
marefr Sep 1, 2021
9b4c71f
Apply suggestions from code review
marefr Sep 2, 2021
af1e2fd
Trying to improve mysql docs
marefr Sep 2, 2021
2f86ad4
Updates
marefr Sep 10, 2021
f28bae4
Apply suggestions from code review
marefr Sep 10, 2021
667b05a
Apply suggestions from code review
marefr Sep 10, 2021
6d8111b
Merge remote-tracking branch 'origin/main' into 38666_docs
marefr Sep 10, 2021
4baeef4
Fix spelling
marefr Sep 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
148 changes: 61 additions & 87 deletions docs/sources/datasources/mssql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,122 +168,96 @@ The resulting table panel:

## Time series queries

If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must have a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. You may return a column named `metric` that is used as metric name for the value column. Any column except `time` and `metric` is treated as a value column. If you omit the `metric` column, the name of the value column will be the metric name. You may select multiple value columns, each will have its name as metric.
If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+).
If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result.
marefr marked this conversation as resolved.
Show resolved Hide resolved

Result sets of time series queries need to be sorted by time.
A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result.
marefr marked this conversation as resolved.
Show resolved Hide resolved

**Example database table:**
> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below.
marefr marked this conversation as resolved.
Show resolved Hide resolved

```sql
CREATE TABLE [event] (
time_sec bigint,
description nvarchar(100),
tags nvarchar(100),
)
```

```sql
CREATE TABLE metric_values (
time datetime,
measurement nvarchar(100),
valueOne int,
valueTwo int,
)

INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric A', 62, 6)
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric B', 49, 11)
...
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric A', 14, 25)
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric B', 48, 10)
You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}).

```

{{< figure src="/static/img/docs/v51/mssql_time_series_one.png" class="docs-image--no-shadow docs-image--right" >}}

**Example with one `value` and one `metric` column.**
**Example with `metric` column:**

```sql
SELECT
time,
valueOne,
measurement as metric
FROM
metric_values
WHERE
$__timeFilter(time)
$__timeGroup(time_date_time, '5m') as time,
min("value_double"),
'min' as metric
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY $__timeGroup(time_date_time, '5m')
ORDER BY 1
```

When the above query is used in a graph panel, it will produce two series named `Metric A` and `Metric B` with the values `valueOne` and `valueTwo` plotted over `time`.

<div class="clearfix"></div>

{{< figure src="/static/img/docs/v51/mssql_time_series_two.png" class="docs-image--no-shadow docs-image--right" >}}

**Example with multiple `value` columns:**

```sql
SELECT
time,
valueOne,
valueTwo
FROM
metric_values
WHERE
$__timeFilter(time)
ORDER BY 1
Data frame result:

```text
+---------------------+-----------------+
| Name: time | Name: min |
| Labels: | Labels: |
| Type: []time.Time | Type: []float64 |
+---------------------+-----------------+
| 2020-01-02 03:05:00 | 3 |
| 2020-01-02 03:10:00 | 6 |
+---------------------+-----------------+
```

When the above query is used in a graph panel, it will produce two series named `Metric A` and `Metric B` with the values `valueOne` and `valueTwo` plotted over `time`.

<div class="clearfix"></div>

{{< figure src="/static/img/docs/v51/mssql_time_series_three.png" class="docs-image--no-shadow docs-image--right" >}}

**Example using the \$\_\_timeGroup macro:**
**Example using the fill parameter in the $\_\_timeGroup macro to convert null values to be zero instead:**

```sql
SELECT
$__timeGroup(time, '3m') as time,
measurement as metric,
avg(valueOne)
FROM
metric_values
$__timeGroup(createdAt, '5m', 0) as time,
sum(value) as value,
hostname
FROM test_data
WHERE
$__timeFilter(time)
$__timeFilter(createdAt)
GROUP BY
$__timeGroup(time, '3m'),
measurement
$__timeGroup(createdAt, '5m', 0),
hostname
ORDER BY 1
```

When the above query is used in a graph panel, it will produce two series named `Metric A` and `Metric B` with the values `valueOne` and `valueTwo` plotted over `time`.
Any two series lacking a value in a three-minute window will render a line between those two lines. You'll notice that the graph to the right never goes down to zero.
Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`.
marefr marked this conversation as resolved.
Show resolved Hide resolved

<div class="clearfix"></div>
Data frame result:

{{< figure src="/static/img/docs/v51/mssql_time_series_four.png" class="docs-image--no-shadow docs-image--right" >}}
```text
+---------------------+---------------------------+---------------------------+
| Name: time | Name: value | Name: value |
| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 |
| Type: []time.Time | Type: []float64 | Type: []float64 |
+---------------------+---------------------------+---------------------------+
| 2020-01-02 03:05:00 | 3 | 4 |
| 2020-01-02 03:10:00 | 6 | 7 |
+---------------------+---------------------------+---------------------------+
```

**Example using the \$\_\_timeGroup macro with fill parameter set to zero:**
**Example with multiple columns:**

```sql
SELECT
$__timeGroup(time, '3m', 0) as time,
measurement as metric,
sum(valueTwo)
FROM
metric_values
WHERE
$__timeFilter(time)
GROUP BY
$__timeGroup(time, '3m'),
measurement
$__timeGroup(time_date_time, '5m'),
min(value_double) as min_value,
max(value_double) as max_value
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY $__timeGroup(time_date_time, '5m')
ORDER BY 1
```

When the above query is used in a graph panel, the result is two series named `Metric A` and `Metric B` with a sum of `valueTwo` plotted over `time`.
Any series lacking a value in a 3 minute window will have a value of zero which you'll see rendered in the graph to the right.
Data frame result:

```text
+---------------------+-----------------+-----------------+
| Name: time | Name: min_value | Name: max_value |
| Labels: | Labels: | Labels: |
| Type: []time.Time | Type: []float64 | Type: []float64 |
+---------------------+-----------------+-----------------+
| 2020-01-02 03:04:00 | 3 | 4 |
| 2020-01-02 03:05:00 | 6 | 7 |
+---------------------+-----------------+-----------------+
```

## Templating

Expand Down
56 changes: 49 additions & 7 deletions docs/sources/datasources/mysql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,12 +180,13 @@ The resulting table panel:

## Time series queries

If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must return a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch.
Any column except `time` and `metric` is treated as a value column.
You may return a column named `metric` that is used as metric name for the value column.
If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+).
If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result.
marefr marked this conversation as resolved.
Show resolved Hide resolved

Resultsets of time series queries need to be sorted by time.
A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result.
marefr marked this conversation as resolved.
Show resolved Hide resolved

> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below.
marefr marked this conversation as resolved.
Show resolved Hide resolved

You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}).
marefr marked this conversation as resolved.
Show resolved Hide resolved

**Example with `metric` column:**

Expand All @@ -200,20 +201,48 @@ GROUP BY time
ORDER BY time
```

Data frame result:
marefr marked this conversation as resolved.
Show resolved Hide resolved

```text
+---------------------+-----------------+
| Name: time | Name: min |
| Labels: | Labels: |
| Type: []time.Time | Type: []float64 |
+---------------------+-----------------+
| 2020-01-02 03:05:00 | 3 |
| 2020-01-02 03:10:00 | 6 |
+---------------------+-----------------+
```

**Example using the fill parameter in the $\_\_timeGroup macro to convert null values to be zero instead:**

```sql
SELECT
$__timeGroup(createdAt,'5m',0),
sum(value_double) as value,
measurement
hostname
FROM test_data
WHERE
$__timeFilter(createdAt)
GROUP BY time, measurement
GROUP BY time, hostname
ORDER BY time
```

Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`.
marefr marked this conversation as resolved.
Show resolved Hide resolved

Data frame result:

```text
+---------------------+---------------------------+---------------------------+
| Name: time | Name: value | Name: value |
| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 |
| Type: []time.Time | Type: []float64 | Type: []float64 |
+---------------------+---------------------------+---------------------------+
| 2020-01-02 03:05:00 | 3 | 4 |
| 2020-01-02 03:10:00 | 6 | 7 |
+---------------------+---------------------------+---------------------------+
```

**Example with multiple columns:**

```sql
Expand All @@ -227,6 +256,19 @@ GROUP BY time
ORDER BY time
```

Data frame result:

```text
+---------------------+-----------------+-----------------+
| Name: time | Name: min_value | Name: max_value |
| Labels: | Labels: | Labels: |
| Type: []time.Time | Type: []float64 | Type: []float64 |
+---------------------+-----------------+-----------------+
| 2020-01-02 03:04:00 | 3 | 4 |
| 2020-01-02 03:05:00 | 6 | 7 |
+---------------------+-----------------+-----------------+
```

Currently, there is no support for a dynamic group by time based on time range and panel width.
This is something we plan to add.

Expand Down
56 changes: 49 additions & 7 deletions docs/sources/datasources/postgres.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,12 +185,13 @@ The resulting table panel:

## Time series queries

If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must return a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch.
Any column except `time` and `metric` are treated as a value column.
You may return a column named `metric` that is used as metric name for the value column.
If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+).
If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result.
marefr marked this conversation as resolved.
Show resolved Hide resolved

Resultsets of time series queries need to be sorted by time.
A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result.
marefr marked this conversation as resolved.
Show resolved Hide resolved

> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below.
marefr marked this conversation as resolved.
Show resolved Hide resolved

You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}).

**Example with `metric` column:**

Expand All @@ -205,20 +206,48 @@ GROUP BY time
ORDER BY time
```

Data frame result:

```text
+---------------------+-----------------+
| Name: time | Name: min |
| Labels: | Labels: |
| Type: []time.Time | Type: []float64 |
+---------------------+-----------------+
| 2020-01-02 03:05:00 | 3 |
| 2020-01-02 03:10:00 | 6 |
+---------------------+-----------------+
```

**Example using the fill parameter in the $\_\_timeGroup macro to convert null values to be zero instead:**

```sql
SELECT
$__timeGroup("createdAt",'5m',0),
sum(value) as value,
measurement
hostname
FROM test_data
WHERE
$__timeFilter("createdAt")
GROUP BY time, measurement
GROUP BY time, hostname
ORDER BY time
```

Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`.
marefr marked this conversation as resolved.
Show resolved Hide resolved

Data frame result:

```text
+---------------------+---------------------------+---------------------------+
| Name: time | Name: value | Name: value |
| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 |
| Type: []time.Time | Type: []float64 | Type: []float64 |
+---------------------+---------------------------+---------------------------+
| 2020-01-02 03:05:00 | 3 | 4 |
| 2020-01-02 03:10:00 | 6 | 7 |
+---------------------+---------------------------+---------------------------+
```

**Example with multiple columns:**

```sql
Expand All @@ -232,6 +261,19 @@ GROUP BY time
ORDER BY time
```

Data frame result:

```text
+---------------------+-----------------+-----------------+
| Name: time | Name: min_value | Name: max_value |
| Labels: | Labels: | Labels: |
| Type: []time.Time | Type: []float64 | Type: []float64 |
+---------------------+-----------------+-----------------+
| 2020-01-02 03:04:00 | 3 | 4 |
| 2020-01-02 03:05:00 | 6 | 7 |
+---------------------+-----------------+-----------------+
```

## Templating

Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
Expand Down