From 3c8b07cda7e3d3f117ce1fc7f83aa3ba0cd60505 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 4 Aug 2020 11:27:40 -0600 Subject: [PATCH 1/2] added user-contributed influxdb package and influxdb.select function --- .../flux/stdlib/built-in/inputs/from.md | 64 ++++++- .../flux/stdlib/contrib/influxdb/_index.md | 29 +++ .../flux/stdlib/contrib/influxdb/select.md | 180 ++++++++++++++++++ 3 files changed, 268 insertions(+), 5 deletions(-) create mode 100644 content/v2.0/reference/flux/stdlib/contrib/influxdb/_index.md create mode 100644 content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md diff --git a/content/v2.0/reference/flux/stdlib/built-in/inputs/from.md b/content/v2.0/reference/flux/stdlib/built-in/inputs/from.md index b01bfdb7b..fae11188c 100644 --- a/content/v2.0/reference/flux/stdlib/built-in/inputs/from.md +++ b/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 +) +``` diff --git a/content/v2.0/reference/flux/stdlib/contrib/influxdb/_index.md b/content/v2.0/reference/flux/stdlib/contrib/influxdb/_index.md new file mode 100644 index 000000000..6e26e0a5f --- /dev/null +++ b/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 %}} diff --git a/content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md b/content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md new file mode 100644 index 000000000..0b455f2f1 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md @@ -0,0 +1,180 @@ +--- +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/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 `_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 +Required Name of the bucket to query. + +_**Data type:** String_ + +### start +Required 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 +Required Name of the measurement to query. + +_**Data type:** String_ + +### fields +List of fields to query. + +_**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. +Those 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 %}} From c48a8147cf1535698f86732fddcad0e9d066194f Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 4 Aug 2020 12:56:48 -0600 Subject: [PATCH 2/2] updated influxdb.select to address PR feedback --- .../reference/flux/stdlib/contrib/influxdb/select.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md b/content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md index 0b455f2f1..46861a530 100644 --- a/content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md +++ b/content/v2.0/reference/flux/stdlib/contrib/influxdb/select.md @@ -14,11 +14,12 @@ 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 `_start` and `_stop` columns. +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_ @@ -77,13 +78,15 @@ _**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. -Those that evaluate to true are included in the output tables. +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`.