docs: built-in variables, $__interval

Fixes #8344. Documents the $__interval, $__interval_ms and $timeFilter
variables.

docs/sources/reference/templating.md

@@ -141,6 +141,42 @@ Use the `Interval` type to create a variable that represents a time span (eg. `1
 
 This variable type is useful as a parameter to group by time (for InfluxDB), Date histogram interval (for Elasticsearch) or as a *summarize* function parameter (for Graphite).
 
+Example using the template variable `myinterval` of type `Interval` in a graphite function:
+
+```
+summarize($myinterval, sum, false)
+```
+
+## Global Built-in Variables
+
+Grafana has global built-in variables that can be used in expressions in the query editor.
+
+### The $__interval Variable
+
+This $__interval variable is similar to the `auto` interval variable that is described above. It can be used as a parameter to group by time (for InfluxDB), Date histogram interval (for Elasticsearch) or as a *summarize* function parameter (for Graphite).
+
+Grafana automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph then queries can be made more efficient by grouping by a larger interval. It is more efficient to group by 1 day than by 10s when looking at 3 months of data and the graph will look the same and the query will be faster. The `$__interval` is calculated using the time range and the width of the graph (the number of pixels).
+
+Approximate Calculation: `(from - to) / resolution`
+
+For example, when the time range is 1 hour and the graph is full screen, then the interval might be calculated to `2m` - points are grouped in 2 minute intervals. If the time range is 6 months and the graph is full screen, then the interval might be `1d` (1 day) - points are grouped by day.
+
+In the InfluxDB data source, the legacy variable `$interval` is the same variable. `$__interval` should be used instead.
+
+The InfluxDB and Elasticsearch data sources have `Group by time interval` fields that are used as the minimum limit for the `$__interval` variable.
+
+### The $__interval_ms Variable
+
+This variable is the `$__interval` variable in milliseconds (and not a time interval formatted string). For example, if the `$__interval` is `20m` then the `$__interval_ms` is `1200000`.
+
+### The $timeFilter or $__timeFilter Variable
+
+The `$timeFilter` variable returns the currently selected time range as an expression. For example, the time range interval `Last 7 days` expression is `time > now() - 7d`.
+
+This is used in the WHERE clause for the InfluxDB data source. Grafana adds it automatically to InfluxDB queries when in Query Editor Mode. It has to be added manually in Text Editor Mode: `WHERE $timeFilter`.
+
+The `$__timeFilter` is used in the MySQL data source.
+
 ## Repeating Panels
 
 Template variables can be very useful to dynamically change your queries across a whole dashboard. If you want