From dfabc6fdba6fcf0c08de37abe56002386ebdcc3e Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 17 Sep 2019 12:11:56 -0600 Subject: [PATCH] added experimental.to function --- .../flux/stdlib/built-in/outputs/to.md | 31 +++-- .../reference/flux/stdlib/experimental/to.md | 109 ++++++++++++++++++ 2 files changed, 122 insertions(+), 18 deletions(-) create mode 100644 content/v2.0/reference/flux/stdlib/experimental/to.md 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/to.md b/content/v2.0/reference/flux/stdlib/experimental/to.md new file mode 100644 index 000000000..f0863da89 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/to.md @@ -0,0 +1,109 @@ +--- +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. +{{% /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" + ) +```