Merge pull request #113 from influxdata/alpha-7-variables

Alpha 7 variables

content/v2.0/visualize-data/variables/_index.md

@@ -0,0 +1,68 @@
+---
+title: Use and manage variables
+seotitle: Use and manage dashboard variables
+description: >
+  Dashboard variables allow you to alter specific components of cells' queries
+  without having to edit the queries, making it easy to interact with your dashboard cells and explore your data.
+menu:
+  v2_0:
+    parent: Visualize data
+weight: 101
+"v2.0/tags": [variables]
+---
+
+Dashboard variables allow you to alter specific components of cells' queries
+without having to edit the queries, making it easy to interact with your dashboard cells and explore your data.
+
+Variables are scoped by organization.
+
+## Use dashboard variables
+Both [custom dashboard variables](#manage-custom-variables) and [predefined dashboard variables](#predefined-dashboard-variables)
+are stored in a `v` object associated with each dashboard.
+Reference each variable using dot-notation (e.g. `v.variableName`).
+
+```js
+from(bucket: v.bucket)
+  |> range(start: v.timeRangeStart, stop: v.timeRangeStart)
+  |> filter(fn (r) => r._measurement == v.measurement and r._field == v.field)
+  |> aggregateWindow(every: v.windowPeriod, fn: mean)
+```
+
+When building Flux queries for dashboard cells, view available dashboard variables
+in the **Variables** tab next to the Functions tab.
+
+{{< img-hd src="/img/2-0-variables-data-explorer-view.png" />}}
+
+Click on a variable name to add it to your query and select a value from the **Value** dropdown.
+
+## Predefined dashboard variables
+The InfluxDB provides the following predefined dashboard variables:
+
+#### v.timeRangeStart
+Specifies the beginning of the queried time range.
+This variable is typically used to define the [`start` parameter](/v2.0/reference/flux/functions/built-in/transformations/range#start)
+of the `range()` function.
+
+The **Time Range** selector defines the value of this variable.
+
+#### v.timeRangeStop
+Specifies the end of the queried time range.
+This variable is typically used to define the [`stop` parameter](/v2.0/reference/flux/functions/built-in/transformations/range#stop)
+of the `range()` function.
+
+The **Time Range** selector defines the value of this variable.
+It defaults to `now`.
+
+#### v.windowPeriod
+Specifies the period of windowed data.
+This variable is typically used to define the `every` or `period` parameter of the
+[`window()` function](/v2.0/reference/flux/functions/built-in/transformations/window)
+in data aggregation operations.
+
+The value of this variable is calculated by dividing the total time within the displayed
+time range by the dashboard refresh interval (defined by the **Refresh** dropdown).
+
+## Custom dashboard variables
+Create, manage, and use custom dashboard variables in the InfluxDB user interface (UI).
+
+{{< children >}}

content/v2.0/visualize-data/variables/common-variables.md

@@ -0,0 +1,46 @@
+---
+title: Common variable queries
+description: Useful queries to use to populate values in common dashboard variable use cases.
+menu:
+  v2_0:
+    parent: Use and manage variables
+    name: Common variable queries
+weight: 208
+"v2.0/tags": [variables]
+---
+
+### List buckets
+List all buckets in the current organization.
+```js
+buckets()
+  |> rename(columns: {"name": "_value"})
+  |> keep(columns: ["_value"])
+```
+
+### List measurements
+List all measurements in a specified bucket.
+
+```js
+import "influxdata/influxdb/v1"
+v1.measurements(bucket: "bucket-name")
+```
+
+### List hosts
+List all `host` tag values in a specified bucket.
+
+```js
+import "influxdata/influxdb/v1"
+v1.tagValues(bucket: "bucket-name", tag: "host")
+```
+
+### List fields in a measurement
+List all fields in a specified bucket and measurement.
+
+```js
+import "influxdata/influxdb/v1"
+v1.measurementTagValues(
+  bucket: "bucket-name",
+  measurement: "measurment-name",
+  tag: "_field"
+)
+```

content/v2.0/visualize-data/variables/create-variable.md

@@ -0,0 +1,55 @@
+---
+title: Create a variable
+seotitle: Create a dashboard variable
+description: Create dashboard variables in the Data Explorer, from the Organization page, or import a variable.
+menu:
+  v2_0:
+    parent: Use and manage variables
+weight: 201
+"v2.0/tags": [variables]
+---
+
+Create dashboard variables in the Data Explorer, from the Organization page, or import a variable.
+
+_For information about variable types, see [Variable types](/v2.0/visualize-data/variables/variable-types/)._
+
+### Create a variable in the Data Explorer
+
+1. Click the **Data Explorer** icon in the sidebar.
+
+  {{< nav-icon "data-explorer" >}}
+
+2. Click **Script Editor** on the lower right.
+3. Build the query for your variable using the [Table visualization type](v2.0/visualize-data/visualization-types/#table) or enable the **View Raw Data** option.
+4. Click **Save As** in the upper right.
+5. In the window that appears, select **Variable**.
+6. Enter a name for your variable in the **Name** field.
+7. Click **Create**.
+
+### Create a variable in the Organizations page
+
+1. Click the **Organizations** icon in the navigation bar.
+
+  {{< nav-icon "orgs" >}}
+
+2. Select an organization from the list.
+3. Select the **Variables** tab.
+4. Click **+Create Variable**.
+5. Enter a name for your variable.
+6. Enter your variable.
+7. Click **Create**.
+
+## Import a variable
+
+1. Click the **Organizations** icon in the navigation bar.
+
+  {{< nav-icon "orgs" >}}
+
+2. Select an organization from the list.
+3. Select the **Variables** tab.
+4. Click the **+Create Variable** dropdown menu and select **Import Variable**.
+3. In the window that appears:
+  * Select **Upload File** to drag-and-drop or select a file.
+  * Select **Paste JSON** to paste in JSON.
+4. Select an organization from the **Destination Organization** dropdown.
+5. Click **Import JSON as Variable**.

content/v2.0/visualize-data/variables/delete-variable.md

@@ -0,0 +1,21 @@
+---
+title: Delete a variable
+seotitle: Delete a dashboard variable
+description: Delete a dashboard variable in the InfluxDB user interface.
+menu:
+  v2_0:
+    parent: Use and manage variables
+weight: 205
+"v2.0/tags": [variables]
+---
+Delete an existing variable in the InfluxDB user interface (UI).
+
+### Delete a variable
+
+1. Click in the **Organizations** icon in the navigation bar.
+
+  {{< nav-icon "orgs" >}}
+
+2. Select an organization from the list.
+3. Select the **Variables** tab.
+4. Hover over a variable and click the trash can icon.

content/v2.0/visualize-data/variables/export-variable.md

@@ -0,0 +1,27 @@
+---
+title: Export a variable
+seotitle: Export a dashboard variable
+description: Export a dashboard variable in the InfluxDB user interface.
+menu:
+  v2_0:
+    parent: Use and manage variables
+weight: 204
+"v2.0/tags": [variables]
+---
+Export dashboard variables from the InfluxDB user interface (UI).
+Variables are exported as downloadable JSON files.
+
+### Export a variable
+
+1. Click the **Organizations** icon in the navigation bar.
+
+  {{< nav-icon "orgs" >}}
+
+2. Select an organization from the list.
+3. Select the **Variables** tab.
+4. Hover over a variable in the list, then click the gear icon ({{< icon "gear" >}}) and select **Export**.
+3. Review the JSON in the window that appears.
+4. Select one of the following options:
+  * **Download JSON**: Download the dashboard as a JSON file.
+  * **Save as template**: Save the JSON as a dashboard template.
+  * **Copy to Clipboard**: Copy the JSON to your clipboard.

content/v2.0/visualize-data/variables/update-variable.md

@@ -0,0 +1,24 @@
+---
+title: Update a variable
+seotitle: Update a dashboard variable
+description: Update a dashboard variable in the InfluxDB user interface.
+menu:
+  v2_0:
+    parent: Use and manage variables
+weight: 203
+"v2.0/tags": [variables]
+---
+
+Update an existing dashboard variable's name or JSON content in the InfluxDB user interface (UI).
+
+### Update a variable
+
+1. Click the **Organizations** icon in the navigation bar.
+
+  {{< nav-icon "orgs" >}}
+
+2. Select an organization from the list.  
+3. Select the **Variables** tab.
+4. Click on a variable's name from the list.
+5. Update the variable's name and query.
+6. Click **Submit**.

content/v2.0/visualize-data/variables/variable-types.md

@@ -0,0 +1,42 @@
+---
+title: Variable types
+seotitle: Dashboard variable types
+description: Overview of the types of dashboard variables available in InfluxDB
+menu:
+  v2_0:
+    parent: Use and manage variables
+weight: 207
+"v2.0/tags": [variables]
+---
+
+{{% note %}}
+In the current version of InfluxDB v2.0 alpha, only [query-populated variables](#query) are available.
+{{% /note %}}
+
+Variable types determine how the list of possible values is populated.
+
+## Query
+Variable values are populated using the results of a Flux query.
+All values in the `_value` column are possible values for the variable.
+
+##### Variable query example
+```js
+// List all buckets
+buckets()
+	|> rename(columns: {"name": "_value"})
+  |> keep(columns: ["_value"])
+```
+
+_For examples of dashboard variable queries, see [Common variable queries](/v2.0/visualize-data/variables/common-variables)._
+
+
+#### Important things to note about variable queries
+- The variable will only use values from the `_value` column.
+  If the data you’re looking for is in a column other than `_value`, use the
+  [`rename()`](/v2.0/reference/flux/functions/built-in/transformations/rename/) or
+  [`map()`](/v2.0/reference/flux/functions/built-in/transformations/map/) functions
+  to change the name of that column to `_value`.
+- The variable will only use the first table in the output stream.
+  Use the [`group()` function](/v2.0/reference/flux/functions/built-in/transformations/group)
+  to group everything into a single table.
+- Do not use any [predefined dashboard variables](/v2.0/visualize-data/variables/#predefined-dashboard-variables) in variable queries.

content/v2.0/visualize-data/variables/view-variables.md

@@ -0,0 +1,32 @@
+---
+title: View variables
+seotitle: View dashboard variables
+description: View dashboard variables in the InfluxDB user interface.
+menu:
+  v2_0:
+    parent: Use and manage variables
+weight: 203
+"v2.0/tags": [variables]
+---
+
+View a list of dashboard variables in the InfluxDB user interface (UI) from an organization or from the Data Explorer.
+
+## View variables in the organization
+
+1. Click the **Organizations** icon in the navigation bar.
+
+  {{< nav-icon "orgs" >}}
+
+2. Select an organization from the list.  
+3. Select the **Variables** tab.
+
+## View variables in the Data Explorer
+
+1. Click the **Data Explorer** icon in the navigation bar.
+
+  {{< nav-icon "data-explorer" >}}
+
+2. Switch to **Script Editor**.
+3. Click the **Variables** tab to the right of the script editor.
+
+  {{< img-hd src="/img/2-0-variables-data-explorer-view.png" />}}