diff --git a/content/v2.0/reference/flux/stdlib/built-in/outputs/to.md b/content/v2.0/reference/flux/stdlib/built-in/outputs/to.md index 97a62a776..63ec618b5 100644 --- a/content/v2.0/reference/flux/stdlib/built-in/outputs/to.md +++ b/content/v2.0/reference/flux/stdlib/built-in/outputs/to.md @@ -52,38 +52,30 @@ All output data must include the following columns: ## Parameters {{% note %}} -`bucket` OR `bucketID` is **required**. +You must provide a `bucket` or `bucketID` and an `org` or `orgID`. {{% /note %}} ### bucket - -The bucket to which data is written. Mutually exclusive with `bucketID`. +The bucket to write data to. +`bucket` and `bucketID` are mutually exclusive. _**Data type:** String_ ### bucketID - -The ID of the bucket to which data is written. Mutually exclusive with `bucket`. +The ID of the bucket to write data to. +`bucketID` and `bucket` are mutually exclusive. _**Data type:** String_ ### org - The organization name of the specified [`bucket`](#bucket). -Only required when writing to a remote host. -Mutually exclusive with `orgID` +`org` and `orgID` are mutually exclusive. _**Data type:** String_ -{{% note %}} -Specify either an `org` or an `orgID`, but not both. -{{% /note %}} - ### orgID - The organization ID of the specified [`bucket`](#bucket). -Only required when writing to a remote host. -Mutually exclusive with `org`. +`orgID` and `org` are mutually exclusive. _**Data type:** String_ @@ -109,21 +101,24 @@ _**Data type:** String_ ### tagColumns The tag columns of the output. -Defaults to all columns with type `string`, excluding all value columns and the `_field` column if present. +Defaults to all columns with type `string`, excluding all value columns and the +`_field` column if present. _**Data type:** Array of strings_ ### fieldFn Function that takes a record from the input table and returns an object. -For each record from the input table, `fieldFn` returns an object that maps output the field key to the output value. +For each record from the input table, `fieldFn` returns an object that maps output +the field key to the output value. Default is `(r) => ({ [r._field]: r._value })` _**Data type:** Function_ _**Output data type:** Object_ {{% note %}} -Make sure `fieldFn` parameter names match each specified parameter. To learn why, see [Match parameter names](/v2.0/reference/flux/language/data-model/#match-parameter-names). +Make sure `fieldFn` parameter names match each specified parameter. +To learn why, see [Match parameter names](/v2.0/reference/flux/language/data-model/#match-parameter-names). {{% /note %}} ## Examples diff --git a/content/v2.0/reference/flux/stdlib/experimental/_index.md b/content/v2.0/reference/flux/stdlib/experimental/_index.md new file mode 100644 index 000000000..678830f89 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/_index.md @@ -0,0 +1,43 @@ +--- +title: Flux Experimental package +list_title: Experimental package +description: > + The Flux Experimental package includes experimental functions that perform various tasks. + Experimental functions are subject to change at any time and are not recommended for production use. +menu: + v2_0_ref: + name: Experimental + parent: Flux standard library +weight: 202 +v2.0/tags: [functions, experimental, package] +--- + +The Flux Experimental package includes experimental functions that perform various tasks. + +{{% warn %}} +### Use experimental functions at your own risk +Experimental functions are subject to change and are **not recommended for production use**. +At any time, experimental functions and packages may: + +- be moved or promoted to a permanent location +- undergo API changes +- stop working with no planned fixes +- be removed without warning nor published explanation + +**By using experimental functions and packages, you agree to these risks.** +{{% /warn %}} + +## Experimental functions +The following functions are part of the base experimental package. +To use them, import the `experimental` package. + +```js +import "experimental" +``` + +{{< children type="functions" show="pages" >}} + +## Experimental packages +Experimental packages require different import paths than base experimental functions. + +{{< children show="sections" >}} diff --git a/content/v2.0/reference/flux/stdlib/experimental/addduration.md b/content/v2.0/reference/flux/stdlib/experimental/addduration.md new file mode 100644 index 000000000..656e796c2 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/addduration.md @@ -0,0 +1,59 @@ +--- +title: experimental.addDuration() function +description: > + The `experimental.addDuration()` function adds a duration to a time value and + returns the resulting time. +menu: + v2_0_ref: + name: experimental.addDuration + parent: Experimental +weight: 201 +related: + - /v2.0/reference/flux/stdlib/experimental/subduration/ +--- + +The `experimental.addDuration()` function adds a duration to a time value and +returns the resulting time value. + +_**Function type:** Transformation_ + +{{% warn %}} +The `experimental.addDuration()` function is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). + +This specific function will be removed once duration vectors are implemented. +See [influxdata/flux#413](https://github.com/influxdata/flux/issues/413). +{{% /warn %}} + +```js +import "experimental" + +experimental.addDuration( + d: 12h, + to: now(), +) +``` + +## Parameters + +### d +The duration to add. + +_**Data type: Duration**_ + +### to +The time to add the [duration](#d) to. + +## Examples + +### Add six hours to a timestamp +```js +import "experimental" + +experimental.addDuration( + d: 6h, + to: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T18:00:00.000000000Z +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/bigtable/_index.md b/content/v2.0/reference/flux/stdlib/experimental/bigtable/_index.md new file mode 100644 index 000000000..73fa1244d --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/bigtable/_index.md @@ -0,0 +1,29 @@ +--- +title: Flux Bigtable package +list_title: Bigtable package +description: > + The Flux Bigtable package provides tools for working with data in Google Cloud Bigtable databases. + Import the `experimental/bigtable` package. +menu: + v2_0_ref: + name: Bigtable + parent: Experimental +weight: 201 +v2.0/tags: [functions, bigtable, package, google] +--- + +The Flux Bigtable package provides tools for working with data in +[Google Cloud Bigtable](https://cloud.google.com/bigtable/) databases. + +{{% warn %}} +The Bigtable package is currently experimental and is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +Import the `experimental/bigtable` package: + +```js +import "experimental/bigtable" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/v2.0/reference/flux/stdlib/experimental/bigtable/from.md b/content/v2.0/reference/flux/stdlib/experimental/bigtable/from.md new file mode 100644 index 000000000..af10c5e2b --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/bigtable/from.md @@ -0,0 +1,59 @@ +--- +title: bigtable.from() function +description: > + The `bigtable.from()` function retrieves data from a Google Cloud Bigtable data source. +menu: + v2_0_ref: + name: bigtable.from + parent: Bigtable +weight: 301 +--- + +The `bigtable.from()` function retrieves data from a [Google Cloud Bigtable](https://cloud.google.com/bigtable/) +data source. + +_**Function type:** Input_ + +{{% warn %}} +The `bigtable.from()` function is currently experimental and is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +```js +import "experimental/bigtable" + +bigtable.from( + token: "mySuPeRseCretTokEn", + project: "exampleProjectID", + instance: "exampleInstanceID", + table: "example-table" +) +``` + +## Parameters + +### token +The Google Cloud IAM token to use to access the Cloud Bigtable database. + +_For more information, see the following:_ + +- [Cloud Bigtable Access Control](https://cloud.google.com/bigtable/docs/access-control) +- [Google Cloud IAM How-to guides](https://cloud.google.com/iam/docs/how-to) +- [Setting Up Authentication for Server to Server Production Applications on Google Cloud](https://cloud.google.com/docs/authentication/production) + +_**Data type: String**_ + +### project +The project ID of the Cloud Bigtable project to retrieve data from. + +_**Data type: String**_ + +### instance +The instance ID of the Cloud Bigtable instance to retrieve data from. + +_**Data type: String**_ + +### table +The name of the Cloud Bigtable table to retrieve data from. + +_**Data type: String**_ diff --git a/content/v2.0/reference/flux/stdlib/experimental/group.md b/content/v2.0/reference/flux/stdlib/experimental/group.md new file mode 100644 index 000000000..69c73889c --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/group.md @@ -0,0 +1,61 @@ +--- +title: experimental.group() function +description: > + The `experimental.group()` function introduces an `extend` mode to the existing + `group()` function. +menu: + v2_0_ref: + name: experimental.group + parent: Experimental +weight: 201 +related: + - /v2.0/reference/flux/stdlib/built-in/transformations/group/ +--- + +The `experimental.group()` function introduces an `extend` mode to the existing +[`group()`](/v2.0/reference/flux/stdlib/built-in/transformations/group/) function. + +_**Function type:** Transformation_ + +{{% warn %}} +The `experimental.group()` function is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). + +This specific function will be removed once the proposed `extend` mode is sufficiently vetted. +{{% /warn %}} + +```js +import "experimental" + +experimental.group(columns: ["host", "_measurement"], mode:"extend") +``` + +## Parameters + +### columns +List of columns to use in the grouping operation. +Defaults to `[]`. + +_**Data type:** Array of strings_ + +### mode +The mode used to group columns. + +_**Data type:** String_ + +{{% note %}} +`extend` is the only mode available to `experimental.group()`. +{{% /note %}} + +#### extend +Appends columns defined in the [`columns` parameter](#columns) to all existing +[group keys](/v2.0/query-data/get-started/#group-keys). + +## Examples + +###### Include the value column in each groups' group key +```js +from(bucket: "example-bucket") + |> range(start: -1m) + |> group(columns: ["_value"], mode: "extend") +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/mqtt/_index.md b/content/v2.0/reference/flux/stdlib/experimental/mqtt/_index.md new file mode 100644 index 000000000..2b80764d6 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/mqtt/_index.md @@ -0,0 +1,28 @@ +--- +title: Flux MQTT package +list_title: MQTT package +description: > + The Flux MQTT package provides functions for working with MQTT protocol. + Import the `experimental/mqtt` package. +menu: + v2_0_ref: + name: MQTT + parent: Experimental +weight: 201 +v2.0/tags: [functions, mqtt, package] +--- + +Flux MQTT functions provide tools for working with Message Queuing Telemetry Transport (MQTT) protocol. + +{{% warn %}} +The MQTT package is currently experimental and is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +Import the `experimental/mqtt` package: + +```js +import "experimental/mqtt" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/v2.0/reference/flux/stdlib/mqtt/to.md b/content/v2.0/reference/flux/stdlib/experimental/mqtt/to.md similarity index 88% rename from content/v2.0/reference/flux/stdlib/mqtt/to.md rename to content/v2.0/reference/flux/stdlib/experimental/mqtt/to.md index e67566895..8b55904da 100644 --- a/content/v2.0/reference/flux/stdlib/mqtt/to.md +++ b/content/v2.0/reference/flux/stdlib/experimental/mqtt/to.md @@ -6,16 +6,20 @@ menu: v2_0_ref: name: mqtt.to parent: MQTT -weight: 202 -draft: true +weight: 301 --- The `mqtt.to()` function outputs data to an MQTT broker using MQTT protocol. _**Function type:** Output_ +{{% warn %}} +The `mqtt.to()` function is currently experimental and is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + ```js -import "mqtt" +import "experimental/mqtt" mqtt.to( broker: "tcp://localhost:8883", @@ -115,7 +119,7 @@ _**Data type: Array of strings**_ ### Send data to an MQTT endpoint ```js -import "mqtt" +import "experimental/mqtt" from(bucket: "example-bucket") |> range(start: -5m) diff --git a/content/v2.0/reference/flux/stdlib/experimental/objectkeys.md b/content/v2.0/reference/flux/stdlib/experimental/objectkeys.md new file mode 100644 index 000000000..a40b5dd02 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/objectkeys.md @@ -0,0 +1,53 @@ +--- +title: experimental.objectKeys() function +description: > + The `experimental.objectKeys()` function returns an array of keys in a specified object. +menu: + v2_0_ref: + name: experimental.objectKeys + parent: Experimental +weight: 201 +--- + +The `experimental.objectKeys()` function returns an array of keys in a specified object. + +_**Function type:** Transformation_ + +{{% warn %}} +The `experimental.objectKeys()` function is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +```js +import "experimental" + +experimental.objectKeys( + o: {key1: "value1", key2: "value2"} +) + +// Returns [key1, key2] +``` + +## Parameters + +### o +The object to return keys from. + +_**Data type: Object**_ + +## Examples + +### Return all keys in an object +```js +import "experimental" + +user = { + firstName: "John", + lastName: "Doe", + age: 42 +} + +experimental.objectKeys(o: user) + +// Returns [firstName, lastName, age] +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/set.md b/content/v2.0/reference/flux/stdlib/experimental/set.md new file mode 100644 index 000000000..33c6ce380 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/set.md @@ -0,0 +1,75 @@ +--- +title: experimental.set() function +description: > + The `experimental.set()` function sets multiple static column values on all records. +menu: + v2_0_ref: + name: experimental.set + parent: Experimental +weight: 201 +related: + - /v2.0/reference/flux/stdlib/built-in/transformations/set/ +--- + +The `experimental.set()` function sets multiple static column values on all records. +If a column already exists, the function updates the existing value. +If a column does not exist, the function adds it with the specified value. + +_Once sufficiently vetted, `experimental.set()` will replace the existing +[`set()` function](/v2.0/reference/flux/stdlib/built-in/transformations/set/)._ + +_**Function type:** Transformation_ + +{{% warn %}} +The `experimental.set()` function is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +```js +import "experimental" + +experimental.set( + o: {column1: "value1", column2: "value2"} +) +``` + +## Parameters + +### o +An object that defines the columns and values to set. +The key of each key-value pair defines the column name. +The value of each key-value pair defines the column value. + +_**Data type: Object**_ + +## Examples + +### Set values for multiple columns + +##### Example input table +| _time | _field | _value | +|:----- |:------ | ------:| +| 2019-09-16T12:00:00Z | temp | 71.2 | +| 2019-09-17T12:00:00Z | temp | 68.4 | +| 2019-09-18T12:00:00Z | temp | 70.8 | + +##### Example query +```js +import "experimental" + +data + |> experimental.set( + o: { + _field: "temperature", + unit: "°F", + location: "San Francisco" + } + ) +``` + +##### Example output table +| _time | _field | _value | unit | location | +|:----- |:------ | ------:|:----:| -------- | +| 2019-09-16T12:00:00Z | temperature | 71.2 | °F | San Francisco | +| 2019-09-17T12:00:00Z | temperature | 68.4 | °F | San Francisco | +| 2019-09-18T12:00:00Z | temperature | 70.8 | °F | San Francisco | diff --git a/content/v2.0/reference/flux/stdlib/experimental/subduration.md b/content/v2.0/reference/flux/stdlib/experimental/subduration.md new file mode 100644 index 000000000..060227568 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/subduration.md @@ -0,0 +1,59 @@ +--- +title: experimental.subDuration() function +description: > + The `experimental.subDuration()` function subtracts a duration from a time value and + returns a the resulting time value. +menu: + v2_0_ref: + name: experimental.subDuration + parent: Experimental +weight: 201 +related: + - /v2.0/reference/flux/stdlib/experimental/addduration/ +--- + +The `experimental.subDuration()` function subtracts a duration from a time value and +returns the resulting time value. + +_**Function type:** Transformation_ + +{{% warn %}} +The `experimental.subDuration()` function is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). + +This specific function will be removed once duration vectors are implemented. +See [influxdata/flux#413](https://github.com/influxdata/flux/issues/413). +{{% /warn %}} + +```js +import "experimental" + +experimental.subDuration( + d: 12h, + from: now(), +) +``` + +## Parameters + +### d +The duration to subtract. + +_**Data type: Duration**_ + +### from +The time to subtract the [duration](#d) from. + +## Examples + +### Subtract six hours from a timestamp +```js +import "experimental" + +experimental.subDuration( + d: 6h, + from: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T06:00:00.000000000Z +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/to.md b/content/v2.0/reference/flux/stdlib/experimental/to.md new file mode 100644 index 000000000..2eece5f3d --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/to.md @@ -0,0 +1,110 @@ +--- +title: experimental.to() function +description: > + The `experimental.to()` function writes data to an InfluxDB v2.0 bucket. + The function structures data differently than the built-in `to()` function. +menu: + v2_0_ref: + name: experimental.to + parent: Experimental +weight: 201 +related: + - /v2.0/reference/flux/stdlib/built-in/outputs/to/ +--- + +The `experimental.to()` function writes data to an InfluxDB v2.0 bucket, but in +a [different structure](#expected-data-structure) than the +[built-in `to()` function](/v2.0/reference/flux/stdlib/built-in/outputs/to/). + +_**Function type:** Output_ + +{{% warn %}} +The `experimental.to()` function is subject to change at any time. +By using it, you accept the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +```js +import "experimental" + +experimental.to( + bucket: "my-bucket", + org: "my-org" +) + +// OR + +experimental.to( + bucketID: "1234567890", + orgID: "0987654321" +) +``` + +### Expected data structure + +#### Data structure expected by built-in to() +The built-in `to()` function requires `_time`, `_measurement`, `_field`, and `_value` columns. +The `_field` column stores the **field key** and the `_value` column stores the **field value**. + +| _time | _measurement | _field | _value | +| ----- | ------------ | ------ | ------ | +| timestamp | measurement-name | field key | field value | + +#### Data structure expected by experimental to() +`experimental.to()` requires `_time` and `measurement` columns, but field keys +and values are stored in single columns with the **field key** as the **column name** and +the **field value** as the **column value**. + +| _time | _measurement | field_key | +| ----- | ------------ | --------- | +| timestamp | measurement-name | field value | + +If using the built-in `from()` function, use [`pivot()`](/v2.0/reference/flux/stdlib/transformations/pivot/) +to transform data into the structure `experimetnal.to()` expects. +_[See the example below](#use-pivot-to-shape-data-for-experimental-to)._ + +## Parameters + +### bucket +The bucket to write data to. +`bucket` and `bucketID` are mutually exclusive. + +_**Data type: String**_ + +### bucketID +The ID of the bucket to write data to. +`bucketID` and `bucket` are mutually exclusive. + +_**Data type: String**_ + +### org +The organization name of the specified [`bucket`](#bucket). +Only required when writing to a different organization or a remote host. +`org` and `orgID` are mutually exclusive. + +_**Data type: String**_ + +### orgID +The organization ID of the specified [`bucket`](#bucket). +Only required when writing to a different organization or a remote host. +`orgID` and `org` are mutually exclusive. + +_**Data type: String**_ + + +## Examples + +##### Use pivot() to shape data for experimental.to() +```js +import "experimental" + +from(bucket: "example-bucket") + |> range(start: -1h) + |> pivot( + rowKey:["_time"], + columnKey: ["_field"], + valueColumn: "_value") + |> experimental.to( + bucket: "bucket-name", + org: "org-name" + ) +``` diff --git a/content/v2.0/reference/flux/stdlib/mqtt/_index.md b/content/v2.0/reference/flux/stdlib/mqtt/_index.md deleted file mode 100644 index 4c9232f67..000000000 --- a/content/v2.0/reference/flux/stdlib/mqtt/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Flux MQTT package -list_title: MQTT package -description: > - The Flux MQTT package provides functions for working with MQTT protocol. - Import the `mqtt` package. -menu: - v2_0_ref: - name: MQTT - parent: Flux standard library -weight: 202 -v2.0/tags: [functions, mqtt, package] -draft: true ---- - -MQTT Flux functions provide tools for working with Message Queuing Telemetry Transport (MQTT) protocol. -Import the `mqtt` package: - -```js -import "mqtt" -``` - -{{< children type="functions" show="pages" >}} diff --git a/content/v2.0/reference/release-notes/flux.md b/content/v2.0/reference/release-notes/flux.md index 87ad2ec31..e45836164 100644 --- a/content/v2.0/reference/release-notes/flux.md +++ b/content/v2.0/reference/release-notes/flux.md @@ -16,8 +16,6 @@ Though newer versions of Flux may be available, they will not be included with InfluxDB until the next InfluxDB v2.0 release._ {{% /note %}} ---- - ## v0.45.1 [2019-09-09] ### Bug fixes