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 119 additions and 69 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
Macro example | Description
------------ | -------------
*$__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, {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+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+DATEDIFF(second,GETUTCDATE(),GETDATE()), '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(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second, GETDATE(), GETUTCDATE()), column))/300 as int)*300 as int)*.
*$__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*
*$__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')*
*$__timeFrom()* | Will be replaced by the start 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, 1494410783, '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', 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*
*$__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
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.
tags | Optional field name to use for event tags as a comma separated string.
......@@ -349,7 +348,7 @@ CREATE TABLE [events] (
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
SELECT
......@@ -363,7 +362,7 @@ WHERE
ORDER BY 1
```
**Example query using time column of type datetime:**
**Example query using time column of native sql date/time data type:**
```sql
SELECT
......
docs/sources/features/datasources/mysql.md
......@@ -12,6 +12,8 @@ weight = 7
# Using MySQL in Grafana
> 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
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.
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!)
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
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*
*$__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)*
*$__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)*
*$__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).
*$__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*
......@@ -85,52 +99,50 @@ The resulting table panel:
![](/img/docs/v43/mysql_table.png)
### Time series queries
If you set `Format as` to `Time series`, for use in Graph panel for example, then there are some requirements for
what your query returns.
## Time series queries
- Must be a column named `time_sec` representing a unix epoch in seconds.
- Must be a column named `value` representing the time series value.
- Must be a column named `metric` representing the time series name.
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.
Example:
**Example with `metric` column:**
```sql
SELECT
min(UNIX_TIMESTAMP(time_date_time)) as time_sec,
max(value_double) as value,
metric1 as metric
$__timeGroup(time_date_time,'5m'),
min(value_double),
'min' as metric
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY metric1, UNIX_TIMESTAMP(time_date_time) DIV 300
ORDER BY time_sec asc
WHERE $__timeFilter(time_date_time)
GROUP BY time
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
SELECT
$__timeGroup(time_date_time,'5m') as time_sec,
min(value_double) as value,
metric_name as metric
$__timeGroup(createdAt,'5m',0),
sum(value_double) as value,
measurement
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY 1, metric_name
ORDER BY 1
WHERE
$__timeFilter(createdAt)
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
SELECT
$__timeGroup(atimestamp,'24h',0) as time_sec,
avg(afloat) as value,
avarchar as metric
FROM testdata.grafana_metrics
WHERE $__timeFilter(atimestamp)
GROUP BY 1, avarchar
ORDER BY 1
SELECT
$__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 time
ORDER BY time
```
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:
```sql
SELECT
UNIX_TIMESTAMP(atimestamp) as time_sec,
UNIX_TIMESTAMP(atimestamp) as time,
aint as value,
avarchar as metric
FROM my_table
......@@ -206,7 +218,7 @@ ORDER BY atimestamp ASC
```sql
SELECT
UNIX_TIMESTAMP(atimestamp) as time_sec,
UNIX_TIMESTAMP(atimestamp) as time,
aint as value,
avarchar as metric
FROM my_table
......@@ -216,23 +228,37 @@ ORDER BY atimestamp ASC
## 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
SELECT
UNIX_TIMESTAMP(atimestamp) as time_sec,
value as text,
epoch_time as time,
metric1 as text,
CONCAT(tag1, ',', tag2) as tags
FROM my_table
WHERE $__timeFilter(atimestamp)
ORDER BY atimestamp ASC
FROM
public.test_data
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
------------ | -------------
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.
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
3. Click the `+ Add data source` button in the top header.
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!)
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
Macro example | Description
------------ | -------------
*$__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*
*$__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)*
......@@ -85,48 +97,48 @@ The resulting table panel:
![](/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.
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
SELECT
$__timeGroup(time_date_time,'5m'),
min(value_double),
$__timeGroup("time_date_time",'5m'),
min("value_double"),
'min' as metric
FROM test_data
WHERE $__timeFilter(time_date_time)
WHERE $__timeFilter("time_date_time")
GROUP 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
SELECT
$__timeGroup("createdAt",'5m',0),
sum(value) as value,
measurement
FROM public.grafana_metric
FROM test_data
WHERE
$__timeFilter("createdAt")
GROUP BY time, measurement
ORDER BY time
```
Example with multiple columns:
**Example with multiple columns:**
```sql
SELECT
$__timeGroup(time_date_time,'5m'),
min(value_double) as min_value,
max(value_double) as max_value
$__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)
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time
```
......@@ -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.
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
SELECT
extract(epoch from time_date_time) AS time,
metric1 as text,
native_date_time as time,
metric1 as text,
concat_ws(', ', metric1::text, metric2::text) as tags
FROM
public.test_data
WHERE
$__timeFilter(time_date_time)
$__timeFilter(native_date_time)
```
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.
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