Merge pull request #1265 from influxdata/contrib-influxdb-select

Added user-contributed 'influxdb' package

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/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 %}}