{
 "metadata": {
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.2-final"
  },
  "orig_nbformat": 2,
  "kernelspec": {
   "name": "python3",
   "display_name": "Python 3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2,
 "cells": [
  {
   "source": [
    "# Dashboard variables in InfluxDB"
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "source": [
    "## Variables\n",
    "\n",
    "Dashboard variables are useful when you would like to modify dashboard cells without editing the original queries based on which the dashboard is built. You can also use Flux to build queries for dashboard cells.\n",
    "\n",
    "Dashboard variables can be\n",
    "\n",
    "- Predefined: `v.timeRangeStart`, `v.timeRangeStop`, `v.windowPeriod`\n",
    "- Custom: defined in the user interface\n",
    "\n",
    "## Quering a variable\n",
    "\n",
    "Variables are stored in a `v` standing for a particular dashboard\n",
    "\n",
    "```\n",
    "from(bucket: v.bucket)\n",
    "  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)\n",
    "  |> filter(fn: (r) => r._measurement == v._measurement and r.field == v.field)\n",
    "  |> aggregateWindow(every: v.windowPeriod, fn: mean)\n",
    "```\n",
    "\n",
    "## Adding a variable\n",
    "\n",
    "1. Check available variables on the right hand side under the **Variables** tab\n",
    "2. Select the name of the variable you would like to add\n",
    "3. Select a value from the **Value** dropdown\n",
    "\n",
    "## Linking a dashboard with variables\n",
    "\n",
    "After adding the variable, the dashboard's url will have the following structure appended to its end `&vars[variable_name]=value`. This allows you to directly share the dashboard with the variable included with a simple url.\n",
    "\n",
    "## Custom variables\n",
    "\n",
    "You can create variables for your dashboard in the following ways:\n",
    "- in the **Data Explorer**\n",
    "- in **Settings**\n",
    "- via import\n",
    "\n",
    "\n",
    "### Naming restrictions\n",
    "\n",
    "Variable names has to\n",
    "- be unique\n",
    "- start with and underscore '`_`'\n",
    "- they cannot be one of the Flux reserved keywords: and, import, not, return, option, test, empty, in, or, package, and builtin.\n",
    "\n"
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "source": [],
   "cell_type": "markdown",
   "metadata": {}
  }
 ]
}