Merge pull request #1266 from influxdata/flux-0.77

Flux 0.77

content/v2.0/reference/flux/stdlib/built-in/inputs/from.md

@@ -22,30 +22,84 @@ _**Function type:** Input_
 _**Output data type:** Object_
 
 ```js
-from(bucket: "example-bucket")
+from(
+  bucket: "example-bucket",
+  host: "https://example.com",
+  org: "example-org",
+  token: "MySuP3rSecr3Tt0k3n"
+)
 
 // OR
 
-from(bucketID: "0261d8287f4d6000")
+from(
+  bucketID: "0261d8287f4d6000",
+  host: "https://example.com",
+  orgID: "example-org",
+  token: "MySuP3rSecr3Tt0k3n"
+)
 ```
 
 ## Parameters
 
+{{% note %}}
+[host](#host), [org](#org) or [orgID](#orgid), and [token](#token) parameters
+are only required when querying data from a **different organization** or a
+**remote InfluxDB instance**.
+{{% /note %}}
+
 ### bucket
-The name of the bucket to query.
+Name of the bucket to query.
 
 _**Data type:** String_
 
 ### bucketID
-The string-encoded ID of the bucket to query.
+String-encoded bucket ID to query.
+
+_**Data type:** String_
+
+### host
+URL of the InfluxDB instance to query.
+_See [InfluxDB URLs](/v2.0/reference/urls/)._
+
+_**Data type:** String_
+
+### org
+Organization name.
+
+_**Data type:** String_
+
+### orgID
+String-encoded [organization ID](/v2.0/organizations/view-orgs/#view-your-organization-id) to query.
+
+_**Data type:** String_
+
+### token
+InfluxDB [authentication token](/v2.0/security/tokens/).
 
 _**Data type:** String_
 
 ## Examples
+
+##### Query using the bucket name
 ```js
 from(bucket: "example-bucket")
 ```
+
+##### Query using the bucket ID
 ```js
 from(bucketID: "0261d8287f4d6000")
 ```
-[FROM]()
+
+##### Query a remote InfluxDB Cloud instance
+```js
+import "influxdata/influxdb/secrets"
+
+token = secrets.get(key: "INFLUXDB_CLOUD_TOKEN")
+
+from(
+  bucket: "example-bucket",
+  host: "https://cloud2.influxdata.com",
+  org: "example-org",
+  token: token
+)
+```

content/v2.0/reference/flux/stdlib/built-in/transformations/keyvalues.md

@@ -21,21 +21,25 @@ The `keyValues()` function returns a table with the input table's group key plus
 `_key` and `_value`, that correspond to unique column + value pairs from the input table.
 
 _**Function type:** Transformation_  
-_**Output data type:** Object_
 
 ```js
 keyValues(keyColumns: ["usage_idle", "usage_user"])
+```
 
+<!--
+```js
 // OR
 
 keyValues(fn: (schema) => schema.columns |> filter(fn: (r) =>  r.label =~ /usage_.*/))
-```
+``` -->
 
 ## Parameters
 
+<!--
 {{% note %}}
 `keyColumns` and `fn` are mutually exclusive. Only one may be used at a time.
 {{% /note %}}
+-->
 
 ### keyColumns
 
@@ -45,6 +49,7 @@ Each input table must have all of the columns listed by the `keyColumns` paramet
 
 _**Data type:** Array of strings_
 
+<!--
 ### fn
 
 Function used to identify a set of columns.
@@ -61,6 +66,7 @@ _**Data type:** Function_
 - Only one of `keyColumns` or `fn` may be used in a single call.
 - All columns indicated must be of the same type.
 - Each input table must have all of the columns listed by the `keyColumns` parameter.
+-->
 
 ## Examples
 
@@ -73,6 +79,7 @@ from(bucket: "example-bucket")
   |> keyValues(keyColumns: ["usage_idle", "usage_user"])
 ```
 
+<!--
 ##### Get key values from columns matching a regular expression
 
 ```js
@@ -80,4 +87,5 @@ from(bucket: "example-bucket")
   |> range(start: -30m)
   |> filter(fn: (r) => r._measurement == "cpu")
   |> keyValues(fn: (schema) => schema.columns |> filter(fn: (r) =>  r.label =~ /usage_.*/))
-```  
+```
+ -->

content/v2.0/reference/flux/stdlib/built-in/transformations/map.md

@@ -13,6 +13,7 @@ v2.0/tags: [exists]
 related:
   - /v2.0/query-data/flux/conditional-logic/
   - /v2.0/query-data/flux/mathematic-operations/
+  - /v2.0/reference/flux/stdlib/contrib/rows/map/
 ---
 
 The `map()` function applies a function to each record in the input tables.
@@ -22,8 +23,7 @@ The output tables are the result of applying the map function to each record of
 When the output record contains a different value for the group key, the record is regrouped into the appropriate table.
 When the output record drops a column that was part of the group key, that column is removed from the group key.
 
-_**Function type:** Transformation_  
+_**Function type:** Transformation_
-_**Output data type:** Object_
 
 ```js
 map(fn: (r) => ({ _value: r._value * r._value }))
@@ -37,7 +37,7 @@ Make sure `fn` parameter names match each specified parameter. To learn why, see
 
 ### fn
 
-A single argument function that to apply to each record.
+A single argument function to apply to each record.
 The return value must be an object.
 
 _**Data type:** Function_

content/v2.0/reference/flux/stdlib/built-in/transformations/type-conversions/duration.md

@@ -32,9 +32,15 @@ _**Data type:** Integer | String | Uinteger_
 {{% /note %}}
 
 ## Examples
+
+{{% note %}}
+Flux does not support duration column types.
+The example below converts an integer to a duration and stores the value as a string.
+{{% /note %}}
+
 ```js
 from(bucket: "sensor-data")
   |> range(start: -1m)
   |> filter(fn:(r) => r._measurement == "system" )
-  |> map(fn:(r) => ({ r with uptime: duration(v: r.uptime) }))
+  |> map(fn:(r) => ({ r with uptime: string(v: duration(v: r.uptime)) }))
 ```

content/v2.0/reference/flux/stdlib/contrib/influxdb/_index.md

@@ -0,0 +1,29 @@
+---
+title: Flux InfluxDB package
+list_title: InfluxDB package
+description: >
+  The Flux InfluxDB package provides additional functions for querying data from InfluxDB.
+  Import the `contrib/jsternberg/influxdb` package.
+menu:
+  v2_0_ref:
+    name: InfluxDB
+    identifier: contrib_influxdb
+    parent: Contributed
+weight: 202
+v2.0/tags: [functions, package, query]
+---
+
+The Flux InfluxDB package provides additional functions for querying data from InfluxDB.
+Import the `contrib/jsternberg/influxdb` package:
+
+```js
+import "contrib/jsternberg/influxdb"
+```
+
+{{< children type="functions" show="pages" >}}
+
+{{% note %}}
+#### Package author and maintainer
+**Github:** [@jsternberg](https://github.com/jsternberg)  
+**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack)
+{{% /note %}}

content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md

@@ -0,0 +1,183 @@
+---
+title: influxdb.select() function
+description: >
+  The `influxdb.select()` function is an alternate implementation of `from()`, `range()`, `filter()`
+  and `pivot()` that returns pivoted query results and masks the `_start` and `_stop` column
+  Results are similar to those returned by InfluxQL `SELECT` statements.
+menu:
+  v2_0_ref:
+    name: influxdb.select
+    parent: contrib_influxdb
+weight: 202
+v2.0/tags: [functions, package, query]
+related:
+  - /v2.0/reference/flux/stdlib/built-in/inputs/from/
+  - /v2.0/reference/flux/stdlib/built-in/transformations/range/
+  - /v2.0/reference/flux/stdlib/built-in/transformations/filter/
+  - /v2.0/reference/flux/stdlib/influxdb-v1/fieldsascols/
+  - /v2.0/reference/flux/stdlib/built-in/transformations/pivot/
+---
+
+The `influxdb.select()` function is an alternate implementation of `from()`, `range()`, `filter()`
+and `pivot()` that returns pivoted query results and masks the `_measurement`, `_start`, and `_stop` columns.
+Results are similar to those returned by InfluxQL `SELECT` statements.
+
+_**Function type:** Input_
+
+```js
+import "contrib/jsternberg/influxdb"
+
+influxdb.select(
+  from: "example-bucket",
+  start: -1d,
+  stop: now(),
+  m: "example-measurement",
+  fields: [],
+  where: (r) => true,
+  host: "https://example.com",
+  org: "example-org",
+  token: "MySuP3rSecr3Tt0k3n"
+)
+```
+
+## Parameters
+
+{{% note %}}
+[host](#host), [org](#org), and [token](#token) parameters are only required when
+querying data from a **different organization** or a **remote InfluxDB instance**.
+{{% /note %}}
+
+### from
+<span class="req">Required</span> Name of the bucket to query.
+
+_**Data type:** String_
+
+### start
+<span class="req">Required</span> Earliest time to include in results.
+Results **include** points that match the specified start time.
+Use a relative duration or absolute time.
+For example, `-1h` or `2019-08-28T22:00:00Z`.
+Durations are relative to `now()`.
+
+_**Data type:** Duration | Time_
+
+### stop
+Latest time to include in results.
+Results **exclude** points that match the specified stop time.
+Use a relative duration or absolute time.
+For example, `-1h` or `2019-08-28T22:00:00Z`.
+Durations are relative to `now()`.
+Defaults to `now()`.
+
+_**Data type:** Duration | Time_
+
+### m
+<span class="req">Required</span> Name of the measurement to query.
+
+_**Data type:** String_
+
+### fields
+List of fields to query.
+Returns all fields when list is empty or unspecified.
+Defaults to `[]`.
+
+_**Data type:** Array of Strings_
+
+### where
+A single argument predicate function that evaluates true or false and filters results based on tag values.
+Records are passed to the function **before fields are pivoted into columns**.
+Records that evaluate to true are included in the output tables.
+Records that evaluate to _null_ or false are not included in the output tables.
+Defaults to `(r) => true`.
+
+_**Data type:** Function_
+
+{{% note %}}
+Objects evaluated in `fn` functions are represented by `r`, short for "record" or "row".
+{{% /note %}}
+
+### host
+URL of the InfluxDB instance to query.
+_See [InfluxDB URLs](/v2.0/reference/urls/)._
+
+_**Data type:** String_
+
+### org
+Organization name.
+
+_**Data type:** String_
+
+### token
+InfluxDB [authentication token](/v2.0/security/tokens/).
+
+_**Data type:** String_
+
+
+## Examples
+
+- [Query a single field](#query-a-single-field)
+- [Query multiple fields](#query-multiple-fields)
+- [Query all fields and filter by tags](#query-all-fields-and-filter-by-tags)
+- [Query data from a remote InfluxDB Cloud instance](#query-data-from-a-remote-influxdb-cloud-instance)
+
+##### Query a single field
+```js
+import "contrib/jsternberg/influxdb"
+
+influxdb.select(
+  from: "example-bucket",
+  start: -1d,
+  m: "example-measurement",
+  fields: ["field1"]
+)
+```
+
+##### Query multiple fields
+```js
+import "contrib/jsternberg/influxdb"
+
+influxdb.select(
+  from: "example-bucket",
+  start: -1d,
+  m: "example-measurement",
+  fields: ["field1", "field2", "field3"]
+)
+```
+
+##### Query all fields and filter by tags
+```js
+import "contrib/jsternberg/influxdb"
+
+influxdb.select(
+  from: "example-bucket",
+  start: -1d,
+  m: "example-measurement",
+  where: (r) => r.host == "host1" and r.region == "us-west"
+)
+```
+
+##### Query data from a remote InfluxDB Cloud instance
+```js
+import "contrib/jsternberg/influxdb"
+import "influxdata/influxdb/secrets"
+
+token = secrets.get(key: "INFLUXDB_CLOUD_TOKEN")
+
+influxdb.select(
+  from: "example-bucket",
+  start: -1d,
+  m: "example-measurement",
+  fields: ["field1", "field2"],
+  host: "https://cloud2.influxdata.com",
+  org: "example-org",
+  token: token
+)
+```
+
+---
+
+{{% note %}}
+#### Package author and maintainer
+**Github:** [@jsternberg](https://github.com/jsternberg)  
+**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack)
+{{% /note %}}

content/v2.0/reference/flux/stdlib/contrib/rows/_index.md

@@ -0,0 +1,28 @@
+---
+title: Flux Rows package
+list_title: Rows package
+description: >
+  The Flux Rows package provides additional functions for remapping values in rows.
+  Import the `contrib/jsternberg/rows` package.
+menu:
+  v2_0_ref:
+    name: Rows
+    parent: Contributed
+weight: 202
+v2.0/tags: [functions, package]
+---
+
+The Flux Rows package provides additional functions for remapping values in rows.
+Import the `contrib/jsternberg/rows` package:
+
+```js
+import "contrib/jsternberg/rows"
+```
+
+{{< children type="functions" show="pages" >}}
+
+{{% note %}}
+#### Package author and maintainer
+**Github:** [@jsternberg](https://github.com/jsternberg)  
+**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack)
+{{% /note %}}

content/v2.0/reference/flux/stdlib/contrib/rows/map.md

@@ -0,0 +1,227 @@
+---
+title: rows.map() function
+description: >
+  The `rows.map()` function is an alternate implementation of [`map()`](/v2.0/reference/flux/stdlib/built-in/transformations/map/)
+  that is faster, but more limited than `map()`.
+menu:
+  v2_0_ref:
+    name: rows.map
+    parent: Rows
+weight: 202
+v2.0/tags: [functions, package, map]
+related:
+  - /v2.0/reference/flux/stdlib/built-in/transformations/map/
+---
+
+The `rows.map()` function is an alternate implementation of [`map()`](/v2.0/reference/flux/stdlib/built-in/transformations/map/)
+that is faster, but more limited than `map()`.
+`rows.map()` cannot modify [groups keys](/v2.0/reference/glossary/#group-key) and,
+therefore, does not need to regroup tables.
+**Attempts to change columns in the group key are ignored.**
+
+_**Function type:** Transformation_
+
+```js
+import "contrib/jsternberg/rows"
+
+rows.map( fn: (r) => ({_value: r._value * 100.0}))
+```
+
+## Parameters
+
+### fn
+
+A single argument function to apply to each record.
+The return value must be an object.
+
+_**Data type:** Function_
+
+{{% note %}}
+Use the `with` operator to preserve columns **not** in the group and **not**
+explicitly mapped in the operation.
+{{% /note %}}
+
+## Examples
+
+- [Perform mathemtical operations on column values](#perform-mathemtical-operations-on-column-values)
+- [Preserve all columns in the operation](#preserve-all-columns-in-the-operation)
+- [Attempt to remap columns in the group key](#attempt-to-remap-columns-in-the-group-key)
+
+---
+
+### Perform mathemtical operations on column values
+The following example returns the square of each value in the `_value` column:
+
+```js
+import "contrib/jsternberg/rows"
+
+data
+  |> rows.map(fn: (r) ({ _value: r._value * r._value }))
+```
+
+{{% note %}}
+#### Important notes
+The `_time` column is dropped because:
+
+- It's not in the group key.
+- It's not explicitly mapped in the operation.
+- The `with` operator was not used to include existing columns.
+{{% /note %}}
+
+{{< flex >}}
+{{% flex-content %}}
+#### Input tables
+
+**Group key:** `tag,_field`
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag1 | foo    | 0001  | 1.9    |
+| tag1 | foo    | 0002  | 2.4    |
+| tag1 | foo    | 0003  | 2.1    |
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag2 | bar    | 0001  | 3.1    |
+| tag2 | bar    | 0002  | 3.8    |
+| tag2 | bar    | 0003  | 1.7    |
+{{% /flex-content %}}
+
+{{% flex-content %}}
+#### Output tables
+
+**Group key:** `tag,_field`
+
+| tag  | _field | _value |
+|:---  |:------ | ------:|
+| tag1 | foo    | 3.61   |
+| tag1 | foo    | 5.76   |
+| tag1 | foo    | 4.41   |
+
+| tag  | _field | _value |
+|:---  |:------ | ------:|
+| tag2 | bar    | 9.61   |
+| tag2 | bar    | 14.44  |
+| tag2 | bar    | 2.89   |
+{{% /flex-content %}}
+{{< /flex >}}
+
+---
+
+### Preserve all columns in the operation
+Use the `with` operator in your mapping operation to preserve all columns,
+including those not in the group key, without explicitly remapping them.
+
+```js
+import "contrib/jsternberg/rows"
+
+data
+  |> rows.map(fn: (r) ({ r with _value: r._value * r._value }))
+```
+
+{{% note %}}
+#### Important notes
+- The mapping operation remaps the `_value` column.
+- The `with` operator preserves all other columns not in the group key (`_time`).
+{{% /note %}}
+
+{{< flex >}}
+{{% flex-content %}}
+#### Input tables
+
+**Group key:** `tag,_field`
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag1 | foo    | 0001  | 1.9    |
+| tag1 | foo    | 0002  | 2.4    |
+| tag1 | foo    | 0003  | 2.1    |
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag2 | bar    | 0001  | 3.1    |
+| tag2 | bar    | 0002  | 3.8    |
+| tag2 | bar    | 0003  | 1.7    |
+{{% /flex-content %}}
+
+{{% flex-content %}}
+#### Output tables
+
+**Group key:** `tag,_field`
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag1 | foo    | 0001  | 3.61   |
+| tag1 | foo    | 0002  | 5.76   |
+| tag1 | foo    | 0003  | 4.41   |
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag2 | bar    | 0001  | 9.61   |
+| tag2 | bar    | 0002  | 14.44  |
+| tag2 | bar    | 0003  | 2.89   |
+{{% /flex-content %}}
+{{< /flex >}}
+
+---
+
+### Attempt to remap columns in the group key
+
+```js
+import "contrib/jsternberg/rows"
+
+data
+  |> rows.map(fn: (r) ({ r with tag: "tag3" }))
+```
+
+{{% note %}}
+#### Important notes
+- Remapping the `tag` column to `"tag3"` is ignored because `tag` is part of the group key.
+- The `with` operator preserves columns not in the group key (`_time` and `_value`).
+{{% /note %}}
+
+{{< flex >}}
+{{% flex-content %}}
+#### Input tables
+
+**Group key:** `tag,_field`
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag1 | foo    | 0001  | 1.9    |
+| tag1 | foo    | 0002  | 2.4    |
+| tag1 | foo    | 0003  | 2.1    |
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag2 | bar    | 0001  | 3.1    |
+| tag2 | bar    | 0002  | 3.8    |
+| tag2 | bar    | 0003  | 1.7    |
+{{% /flex-content %}}
+
+{{% flex-content %}}
+#### Output tables
+
+**Group key:** `tag,_field`
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag1 | foo    | 0001  | 1.9    |
+| tag1 | foo    | 0002  | 2.4    |
+| tag1 | foo    | 0003  | 2.1    |
+
+| tag  | _field | _time | _value |
+|:---  |:------ |:----- | ------:|
+| tag2 | bar    | 0001  | 3.1    |
+| tag2 | bar    | 0002  | 3.8    |
+| tag2 | bar    | 0003  | 1.7    |
+{{% /flex-content %}}
+{{< /flex >}}
+
+---
+
+{{% note %}}
+#### Package author and maintainer
+**Github:** [@jsternberg](https://github.com/jsternberg)  
+**InfluxDB Slack:** [@Jonathan Sternberg](https://influxdata.com/slack)
+{{% /note %}}

content/v2.0/reference/release-notes/flux.md

@@ -16,6 +16,30 @@ Though newer versions of Flux may be available, they will not be included with
 InfluxDB until the next InfluxDB v2.0 release._
 {{% /note %}}
 
+## v0.77.1 [2020-08-03]
+
+### Bug fixes
+- Write tests and fix issues with `rows.map`.
+
+---
+
+## v0.77.0 [2020-08-03]
+
+### Features
+- Add a faster [`map()` function](/v2.0/reference/flux/stdlib/contrib/rows/map/) _(user-contributed)_.
+- Add an [`influxdb.select()` function](/v2.0/reference/flux/stdlib/contrib/influxdb/select/) _(user-contributed)_.
+- Flatbuffer deserialization for type expression AST nodes.
+- Flatbuffer types for monotype and type expression AST nodes.
+- Go AST nodes for type expression syntax.
+- Get all options and properties.
+- Add `parse_function` in `parser/mod.rs`.
+- Add an alternative aggregate package to user-contributed packages.
+
+### Bug fixes
+- Fix string interpolation in arrays.
+
+---
+
 ## v0.76.1 [2020-07-27]
 
 ### Bug fixes

layouts/partials/article.html

@@ -4,6 +4,7 @@
     {{ partial "article/product-tags.html" . }}
     {{ partial "article/stable-version.html" . }}
     {{ partial "article/flux-experimental.html" . }}
+    {{ partial "article/flux-contrib.html" . }}
     {{ .Content }}
     {{ partial "article/related.html" . }}
     {{ partial "article/tags.html" . }}

layouts/partials/article/flux-contrib.html

@@ -0,0 +1,25 @@
+{{ $currentVersion := (index (findRE "[^/]+.*?" .RelPermalink) 0) .RelPermalink }}
+{{ $contribPath := print "/" $currentVersion "/reference/flux/stdlib/contrib/" }}
+
+{{ if in .RelPermalink $contribPath }}
+  {{ if not (eq .RelPermalink $contribPath) }}
+    {{ if eq .Kind "page" }}
+      {{ $name := replaceRE `^\w*\.\w*\(\)` "<code>$0</code>" .Title }}
+      <div class="note block">
+        <p>
+          The {{ $name | safeHTML }} is a user-contributed function maintained by
+          the <a href="#package-author-and-maintainer">package author</a> and can
+          be updated or removed at any time.
+        </p>
+      </div>
+    {{ else if eq .Kind "section" }}
+      <div class="note block">
+        <p>
+          The {{ if $.Params.list_title }}{{ $.Params.list_title }}{{ else }}{{ .Title }}{{ end }}
+          is a user-contributed package maintained by the <a href="#package-author-and-maintainer">package author</a>
+          and can be updated or removed at any time.
+        </p>
+      </div>
+    {{ end }}
+  {{ end }}
+{{ end }}