diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 71baf4bd050..26ba6b31ceb 100644 --- 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*.
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*.
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.
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.
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*.
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.
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.
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 diff --git a/docs/sources/features/datasources/mysql.md b/docs/sources/features/datasources/mysql.md index 6c15006949e..5334f21e178 100644 --- 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. +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. -- 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. - -Example: +**Example with `metric` column:** ```sql SELECT - min(UNIX_TIMESTAMP(time_date_time)) as time_sec, - max(value_double) as value, - metric1 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 -``` - -Example with $__timeGroup macro: - -```sql -SELECT - $__timeGroup(time_date_time,'5m') as time_sec, - min(value_double) as value, - metric_name as metric + $__timeGroup(time_date_time,'5m'), + min(value_double), + 'min' as metric FROM test_data WHERE $__timeFilter(time_date_time) -GROUP BY 1, metric_name -ORDER BY 1 +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(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(createdAt,'5m',0), + sum(value_double) as value, + measurement +FROM test_data +WHERE + $__timeFilter(createdAt) +GROUP BY time, measurement +ORDER BY time +``` + +**Example with multiple columns:** + +```sql +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. diff --git a/docs/sources/features/datasources/postgres.md b/docs/sources/features/datasources/postgres.md index 270640a93dc..d830d8b9ed9 100644 --- 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'), - 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 - extract(epoch from time_date_time) AS time, - metric1 as text, + epoch_time as time, + metric1 as text, concat_ws(', ', metric1::text, metric2::text) as tags FROM public.test_data WHERE - $__timeFilter(time_date_time) + $__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_ws(', ', metric1::text, metric2::text) as tags +FROM + public.test_data +WHERE + $__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.