Skip to content

N
nexpie-grafana-theme
Commit 403c64ab by Marcus Efraimsson
Options

docs: update postgres, mysql and mssql documentation 

Due to changes closing #11306
parent c318f7bb
Showing with 116 additions and 66 deletions
docs/sources/features/datasources/mssql.md
...@@ -70,12 +70,11 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the ...@@ -70,12 +70,11 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the
Macro example | Description Macro example | Description
------------ | ------------- ------------ | -------------
*$__time(dateColumn)* | Will be replaced by an expression to rename the column to *time*. For example, *dateColumn as time* *$__time(dateColumn)* | Will be replaced by an expression to rename the column to *time*. For example, *dateColumn as time*
*$__utcTime(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to UTC depending on the server's local timeoffset and rename it to *time*. <br/>For example, *DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time* *$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to unix timestamp and rename it to *time*. <br/>For example, *DATEDIFF(second, '1970-01-01', dateColumn) AS time*
*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to unix timestamp and rename it to *time*. <br/>For example, *DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time* *$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. <br/>For example, *dateColumn >= DATEADD(s, 1494410783, '1970-01-01') AND dateColumn <= DATEADD(s, 1494410783, '1970-01-01')*
*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. <br/>For example, *dateColumn >= DATEADD(s, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01') AND dateColumn <= DATEADD(s, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* *$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *DATEADD(second, 1494410783, '1970-01-01')*
*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *DATEADD(second, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* *$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *DATEADD(second, 1494410783, '1970-01-01')*
*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *DATEADD(second, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* *$__timeGroup(dateColumn,'5m'[, fillvalue])* | Will be replaced by an expression usable in GROUP BY clause. Providing a *fillValue* of *NULL* or *floating value* will automatically fill empty series in timerange with that value. <br/>For example, *CAST(ROUND(DATEDIFF(second, '1970-01-01', time_column)/300.0, 0) as bigint)\*300*.
*$__timeGroup(dateColumn,'5m'[, fillvalue])* | Will be replaced by an expression usable in GROUP BY clause. Providing a *fillValue* of *NULL* or *floating value* will automatically fill empty series in timerange with that value. <br/>For example, *cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second, GETDATE(), GETUTCDATE()), column))/300 as int)*300 as int)*.
*$__timeGroup(dateColumn,'5m', 0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). *$__timeGroup(dateColumn,'5m', 0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example).
*$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* *$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183*
*$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* *$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783*
...@@ -333,7 +332,7 @@ ORDER BY atimestamp ...@@ -333,7 +332,7 @@ ORDER BY atimestamp
Name | Description Name | Description
------------ | ------------- ------------ | -------------
time | The name of the date/time field. Could be in a native sql time datatype or epoch seconds. time | The name of the date/time field. Could be a column with a native sql date/time data type or epoch value.
text | Event description field. text | Event description field.
tags | Optional field name to use for event tags as a comma separated string. tags | Optional field name to use for event tags as a comma separated string.
...@@ -349,7 +348,7 @@ CREATE TABLE [events] ( ...@@ -349,7 +348,7 @@ CREATE TABLE [events] (
We also use the database table defined in [Time series queries](#time-series-queries). We also use the database table defined in [Time series queries](#time-series-queries).
**Example query using time column of type epoch seconds:** **Example query using time column with epoch values:**
```sql ```sql
SELECT SELECT
...@@ -363,7 +362,7 @@ WHERE ...@@ -363,7 +362,7 @@ WHERE
ORDER BY 1 ORDER BY 1
``` ```
**Example query using time column of type datetime:** **Example query using time column of native sql date/time data type:**
```sql ```sql
SELECT SELECT
......
docs/sources/features/datasources/mysql.md
...@@ -12,6 +12,8 @@ weight = 7 ...@@ -12,6 +12,8 @@ weight = 7
# Using MySQL in Grafana # Using MySQL in Grafana
> Only available in Grafana v4.3+. > Only available in Grafana v4.3+.
>
> Starting from Grafana v5.1 you can name the time column *time* in addition to earlier supported *time_sec*. Usage of *time_sec* will eventually be deprecated.
Grafana ships with a built-in MySQL data source plugin that allow you to query any visualize Grafana ships with a built-in MySQL data source plugin that allow you to query any visualize
data from a MySQL compatible database. data from a MySQL compatible database.
...@@ -23,6 +25,17 @@ data from a MySQL compatible database. ...@@ -23,6 +25,17 @@ data from a MySQL compatible database.
3. Click the `+ Add data source` button in the top header. 3. Click the `+ Add data source` button in the top header.
4. Select *MySQL* from the *Type* dropdown. 4. Select *MySQL* from the *Type* dropdown.
### Data source options
Name | Description
------------ | -------------
*Name* | The data source name. This is how you refer to the data source in panels & queries.
*Default* | Default data source means that it will be pre-selected for new panels.
*Host* | The IP address/hostname and optional port of your MySQL instance.
*Database* | Name of your MySQL database.
*User* | Database user's login/username
*Password* | Database user's password
### Database User Permissions (Important!) ### Database User Permissions (Important!)
The database user you specify when you add the data source should only be granted SELECT permissions on The database user you specify when you add the data source should only be granted SELECT permissions on
...@@ -46,10 +59,11 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the ...@@ -46,10 +59,11 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the
Macro example | Description Macro example | Description
------------ | ------------- ------------ | -------------
*$__time(dateColumn)* | Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, *UNIX_TIMESTAMP(dateColumn) as time_sec* *$__time(dateColumn)* | Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, *UNIX_TIMESTAMP(dateColumn) as time_sec*
*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, *UNIX_TIMESTAMP(dateColumn) as time_sec*
*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *dateColumn > FROM_UNIXTIME(1494410783) AND dateColumn < FROM_UNIXTIME(1494497183)* *$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *dateColumn > FROM_UNIXTIME(1494410783) AND dateColumn < FROM_UNIXTIME(1494497183)*
*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *FROM_UNIXTIME(1494410783)* *$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *FROM_UNIXTIME(1494410783)*
*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *FROM_UNIXTIME(1494497183)* *$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *FROM_UNIXTIME(1494497183)*
*$__timeGroup(dateColumn,'5m')* | Will be replaced by an expression usable in GROUP BY clause. For example, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed) as time_sec,* *$__timeGroup(dateColumn,'5m')* | Will be replaced by an expression usable in GROUP BY clause. For example, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed),*
*$__timeGroup(dateColumn,'5m',0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). *$__timeGroup(dateColumn,'5m',0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example).
*$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* *$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183*
*$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* *$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783*
...@@ -85,52 +99,50 @@ The resulting table panel: ...@@ -85,52 +99,50 @@ The resulting table panel:
![](/img/docs/v43/mysql_table.png) ![](/img/docs/v43/mysql_table.png)
### Time series queries ## Time series queries
If you set `Format as` to `Time series`, for use in Graph panel for example, then there are some requirements for 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.
what your query returns. 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.
- Must be a column named `time_sec` representing a unix epoch in seconds. **Example with `metric` column:**
- Must be a column named `value` representing the time series value.
- Must be a column named `metric` representing the time series name.
Example:
```sql ```sql
SELECT SELECT
min(UNIX_TIMESTAMP(time_date_time)) as time_sec, $__timeGroup(time_date_time,'5m'),
max(value_double) as value, min(value_double),
metric1 as metric 'min' as metric
FROM test_data FROM test_data
WHERE $__timeFilter(time_date_time) WHERE $__timeFilter(time_date_time)
GROUP BY metric1, UNIX_TIMESTAMP(time_date_time) DIV 300 GROUP BY time
ORDER BY time_sec asc ORDER BY time
``` ```
Example with $__timeGroup macro: **Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead:**
```sql ```sql
SELECT SELECT
$__timeGroup(time_date_time,'5m') as time_sec, $__timeGroup(createdAt,'5m',0),
min(value_double) as value, sum(value_double) as value,
metric_name as metric measurement
FROM test_data FROM test_data
WHERE $__timeFilter(time_date_time) WHERE
GROUP BY 1, metric_name $__timeFilter(createdAt)
ORDER BY 1 GROUP BY time, measurement
ORDER BY time
``` ```
Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead: **Example with multiple columns:**
```sql ```sql
SELECT SELECT
$__timeGroup(atimestamp,'24h',0) as time_sec, $__timeGroup(time_date_time,'5m'),
avg(afloat) as value, min(value_double) as min_value,
avarchar as metric max(value_double) as max_value
FROM testdata.grafana_metrics FROM test_data
WHERE $__timeFilter(atimestamp) WHERE $__timeFilter(time_date_time)
GROUP BY 1, avarchar GROUP BY time
ORDER BY 1 ORDER BY time
``` ```
Currently, there is no support for a dynamic group by time based on time range & panel width. Currently, there is no support for a dynamic group by time based on time range & panel width.
...@@ -194,7 +206,7 @@ There are two syntaxes: ...@@ -194,7 +206,7 @@ There are two syntaxes:
```sql ```sql
SELECT SELECT
UNIX_TIMESTAMP(atimestamp) as time_sec, UNIX_TIMESTAMP(atimestamp) as time,
aint as value, aint as value,
avarchar as metric avarchar as metric
FROM my_table FROM my_table
...@@ -206,7 +218,7 @@ ORDER BY atimestamp ASC ...@@ -206,7 +218,7 @@ ORDER BY atimestamp ASC
```sql ```sql
SELECT SELECT
UNIX_TIMESTAMP(atimestamp) as time_sec, UNIX_TIMESTAMP(atimestamp) as time,
aint as value, aint as value,
avarchar as metric avarchar as metric
FROM my_table FROM my_table
...@@ -216,23 +228,37 @@ ORDER BY atimestamp ASC ...@@ -216,23 +228,37 @@ ORDER BY atimestamp ASC
## Annotations ## Annotations
[Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. [Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.
An example query: **Example query using time column with epoch values:**
```sql ```sql
SELECT SELECT
UNIX_TIMESTAMP(atimestamp) as time_sec, epoch_time as time,
value as text, metric1 as text,
CONCAT(tag1, ',', tag2) as tags CONCAT(tag1, ',', tag2) as tags
FROM my_table FROM
WHERE $__timeFilter(atimestamp) public.test_data
ORDER BY atimestamp ASC WHERE
$__unixEpochFilter(epoch_time)
```
**Example query using time column of native sql date/time data type:**
```sql
SELECT
native_date_time as time,
metric1 as text,
CONCAT(tag1, ',', tag2) as tags
FROM
public.test_data
WHERE
$__timeFilter(native_date_time)
``` ```
Name | Description Name | Description
------------ | ------------- ------------ | -------------
time_sec | The name of the date/time field. time | The name of the date/time field. Could be a column with a native sql date/time data type or epoch value.
text | Event description field. text | Event description field.
tags | Optional field name to use for event tags as a comma separated string. tags | Optional field name to use for event tags as a comma separated string.
......
docs/sources/features/datasources/postgres.md
...@@ -20,6 +20,18 @@ Grafana ships with a built-in PostgreSQL data source plugin that allows you to q ...@@ -20,6 +20,18 @@ Grafana ships with a built-in PostgreSQL data source plugin that allows you to q
3. Click the `+ Add data source` button in the top header. 3. Click the `+ Add data source` button in the top header.
4. Select *PostgreSQL* from the *Type* dropdown. 4. Select *PostgreSQL* from the *Type* dropdown.
### Data source options
Name | Description
------------ | -------------
*Name* | The data source name. This is how you refer to the data source in panels & queries.
*Default* | Default data source means that it will be pre-selected for new panels.
*Host* | The IP address/hostname and optional port of your PostgreSQL instance.
*Database* | Name of your PostgreSQL database.
*User* | Database user's login/username
*Password* | Database user's password
*SSL Mode* | This option determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
### Database User Permissions (Important!) ### Database User Permissions (Important!)
The database user you specify when you add the data source should only be granted SELECT permissions on The database user you specify when you add the data source should only be granted SELECT permissions on
...@@ -44,7 +56,7 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the ...@@ -44,7 +56,7 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the
Macro example | Description Macro example | Description
------------ | ------------- ------------ | -------------
*$__time(dateColumn)* | Will be replaced by an expression to rename the column to `time`. For example, *dateColumn as time* *$__time(dateColumn)* | Will be replaced by an expression to rename the column to `time`. For example, *dateColumn as time*
*$__timeSec(dateColumn)* | Will be replaced by an expression to rename the column to `time` and converting the value to unix timestamp. For example, *extract(epoch from dateColumn) as time* *$__timeEpoch(dateColumn)* | Will be replaced by an expression to rename the column to `time` and converting the value to unix timestamp. For example, *extract(epoch from dateColumn) as time*
*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *extract(epoch from dateColumn) BETWEEN 1494410783 AND 1494497183* *$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *extract(epoch from dateColumn) BETWEEN 1494410783 AND 1494497183*
*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *to_timestamp(1494410783)* *$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *to_timestamp(1494410783)*
*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *to_timestamp(1494497183)* *$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *to_timestamp(1494497183)*
...@@ -85,48 +97,48 @@ The resulting table panel: ...@@ -85,48 +97,48 @@ The resulting table panel:
![](/img/docs/v46/postgres_table.png) ![](/img/docs/v46/postgres_table.png)
### Time series queries ## 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 in seconds. 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. 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. You may return a column named `metric` that is used as metric name for the value column.
Example with `metric` column **Example with `metric` column:**
```sql ```sql
SELECT SELECT
$__timeGroup(time_date_time,'5m'), $__timeGroup("time_date_time",'5m'),
min(value_double), min("value_double"),
'min' as metric 'min' as metric
FROM test_data FROM test_data
WHERE $__timeFilter(time_date_time) WHERE $__timeFilter("time_date_time")
GROUP BY time GROUP BY time
ORDER BY time ORDER BY time
``` ```
Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead: **Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead:**
```sql ```sql
SELECT SELECT
$__timeGroup("createdAt",'5m',0), $__timeGroup("createdAt",'5m',0),
sum(value) as value, sum(value) as value,
measurement measurement
FROM public.grafana_metric FROM test_data
WHERE WHERE
$__timeFilter("createdAt") $__timeFilter("createdAt")
GROUP BY time, measurement GROUP BY time, measurement
ORDER BY time ORDER BY time
``` ```
Example with multiple columns: **Example with multiple columns:**
```sql ```sql
SELECT SELECT
$__timeGroup(time_date_time,'5m'), $__timeGroup("time_date_time",'5m'),
min(value_double) as min_value, min("value_double") as "min_value",
max(value_double) as max_value max("value_double") as "max_value"
FROM test_data FROM test_data
WHERE $__timeFilter(time_date_time) WHERE $__timeFilter("time_date_time")
GROUP BY time GROUP BY time
ORDER BY time ORDER BY time
``` ```
...@@ -209,22 +221,35 @@ ORDER BY atimestamp ASC ...@@ -209,22 +221,35 @@ ORDER BY atimestamp ASC
[Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. [Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.
An example query: **Example query using time column with epoch values:**
```sql
SELECT
epoch_time as time,
metric1 as text,
concat_ws(', ', metric1::text, metric2::text) as tags
FROM
public.test_data
WHERE
$__unixEpochFilter(epoch_time)
```
**Example query using time column of native sql date/time data type:**
```sql ```sql
SELECT SELECT
extract(epoch from time_date_time) AS time, native_date_time as time,
metric1 as text, metric1 as text,
concat_ws(', ', metric1::text, metric2::text) as tags concat_ws(', ', metric1::text, metric2::text) as tags
FROM FROM
public.test_data public.test_data
WHERE WHERE
$__timeFilter(time_date_time) $__timeFilter(native_date_time)
``` ```
Name | Description Name | Description
------------ | ------------- ------------ | -------------
time | The name of the date/time field. time | The name of the date/time field. Could be a column with a native sql date/time data type or epoch value.
text | Event description field. text | Event description field.
tags | Optional field name to use for event tags as a comma separated string. tags | Optional field name to use for event tags as a comma separated string.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment