docs: update postgres, mysql and mssql documentation

Due to changes closing #11306

docs: update postgres, mysql and mssql documentation
Due to changes closing #11306
403c64ab · Marcus Efraimsson · c318f7bb · 403c64ab · 403c64ab · 403c64ab
Commit 403c64ab authored Mar 23, 2018 by Marcus Efraimsson
Hide whitespace changes
Inline Side-by-side

Showing with 119 additions and 69 deletions

docs/sources/features/datasources/mssql.md
+8 -9

docs/sources/features/datasources/mysql.md
+67 -41

docs/sources/features/datasources/postgres.md
+44 -19

No files found.
--- a/docs/sources/features/datasources/mssql.md
+++ b/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, '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).
 *$__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

--- a/docs/sources/features/datasources/mysql.md
+++ b/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
+## 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.
- Must be a column named `time_sec` representing a 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.
- Must be a column named `value` representing the time series value.
+Any column except `time` and `metric` is treated as a value column.
- Must be a column named `metric` representing the time series name.
+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,
+  $__timeGroup(time_date_time,'5m'),
-  max(value_double) as value,
+  min(value_double),
-  metric1 as metric
+  'min' as metric
 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
 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
-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
-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.
@@ -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,
+  epoch_time as time,
-  value as text,
+  metric1 as text,
  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
 ------------ | -------------
-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.

--- a/docs/sources/features/datasources/postgres.md
+++ b/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'),
+  $__timeGroup("time_date_time",'5m'),
-  min(value_double),
+  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'),
+  $__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
-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,
+  native_date_time as time,
- metric1 as text,
+  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.