Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #469 from influxdata/flux/experimental-package 

Flux experimental package
pull/472/head
Scott Anderson 2019-09-17 17:13:19 -06:00 committed by GitHub
parent 9aa7a9a6a1 144f83fece
commit fbbc5ddd88
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 597 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
content/v2.0/reference/flux/stdlib/built-in/outputs/to.md
View File

@ -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

43
content/v2.0/reference/flux/stdlib/experimental/_index.md Normal file
View File

@ -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" >}}

59
content/v2.0/reference/flux/stdlib/experimental/addduration.md Normal file
View File

@ -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
```

29
content/v2.0/reference/flux/stdlib/experimental/bigtable/_index.md Normal file
View File

@ -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" >}}

59
content/v2.0/reference/flux/stdlib/experimental/bigtable/from.md Normal file
View File

@ -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**_

61
content/v2.0/reference/flux/stdlib/experimental/group.md Normal file
View File

@ -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")
```

28
content/v2.0/reference/flux/stdlib/experimental/mqtt/_index.md Normal file
View File

@ -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" >}}

12
content/v2.0/reference/flux/stdlib/mqtt/to.md → content/v2.0/reference/flux/stdlib/experimental/mqtt/to.md
View File

@ -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)

53
content/v2.0/reference/flux/stdlib/experimental/objectkeys.md Normal file
View File

@ -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]
```

75
content/v2.0/reference/flux/stdlib/experimental/set.md Normal file
View File

@ -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 |

59
content/v2.0/reference/flux/stdlib/experimental/subduration.md Normal file
View File

@ -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
```

110
content/v2.0/reference/flux/stdlib/experimental/to.md Normal file
View File

@ -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"
)
```

23
content/v2.0/reference/flux/stdlib/mqtt/_index.md
View File

@ -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" >}}

2
content/v2.0/reference/release-notes/flux.md
View File

@ -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