From 6535413f652eebc3d187da792cfbabf2e2000264 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 20 Feb 2020 09:25:08 -0700 Subject: [PATCH] added experimental query package, resolves #767 --- .../flux/stdlib/experimental/query/_index.md | 39 +++++++ .../stdlib/experimental/query/filterfields.md | 53 +++++++++ .../experimental/query/filtermeasurement.md | 50 ++++++++ .../stdlib/experimental/query/fromrange.md | 72 ++++++++++++ .../stdlib/experimental/query/inbucket.md | 109 ++++++++++++++++++ .../partials/article/flux-experimental.html | 2 +- 6 files changed, 324 insertions(+), 1 deletion(-) create mode 100644 content/v2.0/reference/flux/stdlib/experimental/query/_index.md create mode 100644 content/v2.0/reference/flux/stdlib/experimental/query/filterfields.md create mode 100644 content/v2.0/reference/flux/stdlib/experimental/query/filtermeasurement.md create mode 100644 content/v2.0/reference/flux/stdlib/experimental/query/fromrange.md create mode 100644 content/v2.0/reference/flux/stdlib/experimental/query/inbucket.md diff --git a/content/v2.0/reference/flux/stdlib/experimental/query/_index.md b/content/v2.0/reference/flux/stdlib/experimental/query/_index.md new file mode 100644 index 000000000..c650b044c --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/query/_index.md @@ -0,0 +1,39 @@ +--- +title: Flux Query package +list_title: Query package +description: > + The Flux Query package provides functions meant to simplify common InfluxDB queries. + Import the `experimental/query` package. +menu: + v2_0_ref: + name: Query + parent: Experimental +weight: 201 +v2.0/tags: [package] +--- + +Flux Query functions provide functions meant to simplify common InfluxDB queries. +Import the `experimental/query` package: + +```js +import "experimental/query" +``` + +{{< children type="functions" show="pages" >}} + +## inBucket() +The primary function in this package is [`query.inBucket()`](/v2.0/reference/flux/stdlib/experimental/query/inbucket/), +which utilizes all other functions in this package. + +```js +import "experimental/query" + +query.inBucket( + bucket: "example-bucket", + start: -1h, + stop: now(), + measurement: "example-measurement", + fields: ["exampleField1", "exampleField2"], + predicate: (r) => true +) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/query/filterfields.md b/content/v2.0/reference/flux/stdlib/experimental/query/filterfields.md new file mode 100644 index 000000000..9b9bab2c2 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/query/filterfields.md @@ -0,0 +1,53 @@ +--- +title: query.filterFields() function +description: > + The `query.filterFields()` function filters input data by field. +menu: + v2_0_ref: + name: query.filterFields + parent: Query +weight: 301 +--- + +The `query.filterFields()` function filters input data by field. + +_**Function type:** Transformation_ + +```js +import "experimental/query" + +query.filterFields( + fields: ["exampleField1", "exampleField2"] +) +``` + +## Parameters + +### fields +Fields to filter by. +Must be exact string matches. + +_**Data type:** Array of strings_ + +## Examples + +```js +import "experimental/query" + +query.fromRange(bucket: "telegraf", start: -1h) + |> query.filterFields( + fields: ["used_percent", "available_percent"] + ) +``` + +## Function definition +```js +package query + +filterFields = (tables=<-, fields=[]) => + if length(arr: fields) == 0 then + tables + else + tables + |> filter(fn: (r) => contains(value: r._field, set: fields)) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/query/filtermeasurement.md b/content/v2.0/reference/flux/stdlib/experimental/query/filtermeasurement.md new file mode 100644 index 000000000..345983951 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/query/filtermeasurement.md @@ -0,0 +1,50 @@ +--- +title: query.filterMeasurement() function +description: > + The `query.filterMeasurement()` function filters input data by measurement. +menu: + v2_0_ref: + name: query.filterMeasurement + parent: Query +weight: 301 +--- + +The `query.filterMeasurement()` function filters input data by measurement. + +_**Function type:** Transformation_ + +```js +import "experimental/query" + +query.filterMeasurement( + measurement: "example-measurement" +) +``` + +## Parameters + +### measurement +The name of the measurement to filter by. +Must be an exact string match. + +_**Data type:** String_ + +## Examples + +```js +import "experimental/query" + +query.fromRange(bucket: "example-bucket", start: -1h) + |> query.filterMeasurement( + measurement: "example-measurement" + ) +``` + +## Function definition +```js +package query + +filterMeasurement = (tables=<-, measurement) => + tables + |> filter(fn: (r) => r._measurement == measurement) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/query/fromrange.md b/content/v2.0/reference/flux/stdlib/experimental/query/fromrange.md new file mode 100644 index 000000000..45bc5395a --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/query/fromrange.md @@ -0,0 +1,72 @@ +--- +title: query.fromRange() function +description: > + The `query.fromRange()` function returns all data from a specified bucket within + given time bounds. +menu: + v2_0_ref: + name: query.fromRange + parent: Query +weight: 301 +--- + +The `query.fromRange()` function returns all data from a specified bucket within +given time bounds. + +_**Function type:** Output_ + +```js +import "experimental/query" + +query.fromRange( + bucket: "example-bucket", + start: -1h, + stop: now() +) +``` + +## Parameters + +### bucket +The name of the bucket to query. + +_**Data type:** String_ + +### start +The 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 +The 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_ + +## Examples + +```js +import "experimental/query" + +query.fromRange( + bucket: "example-bucket", + start: 2020-01-01T00:00:00Z +) +``` + +## Function definition +```js +package query + +fromRange = (bucket, start, stop=now()) => + from(bucket: bucket) + |> range(start: start, stop: stop) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/query/inbucket.md b/content/v2.0/reference/flux/stdlib/experimental/query/inbucket.md new file mode 100644 index 000000000..3b25cb577 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/query/inbucket.md @@ -0,0 +1,109 @@ +--- +title: query.inBucket() function +description: > + The `query.inBucket()` function queries data from a specified bucket within given + time bounds, filters data my measurement, field, and other column values. +menu: + v2_0_ref: + name: query.inBucket + parent: Query +weight: 301 +--- + +The `query.inBucket()` function queries data from a specified bucket within given +time bounds, filters data my measurement, field, and other column values. + +_**Function type:** Input_ + +```js +import "experimental/query" + +query.inBucket( + bucket: "example-bucket", + start: -1h, + stop: now(), + measurement: "example-measurement", + fields: ["exampleField1", "exampleField2"], + predicate: (r) => true +) +``` + +## Parameters + +### bucket +The name of the bucket to query. + +_**Data type:** String_ + +### start +The 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 +The 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_ + +### measurement +The name of the measurement to filter by. +Must be an exact string match. + +_**Data type:** String_ + +### fields +Fields to filter by. +Must be exact string matches. + +_**Data type:** Array of strings_ + +### predicate +A single argument predicate function that evaluates true or false. +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. +Default is `(r) => true`. + +_**Data type:** Function_ + +## Examples + +##### Query memory data from host1 +```js +import "experimental/query" + +query.inBucket( + bucket: "telegraf", + start: -1h, + measurement: "mem", + fields: ["used_percent", "available_percent"], + predicate: (r) => r.host == "host1" +) +``` + +## Function definition +```js +package query + +inBucket = ( + bucket, + start, + stop=now(), + measurement, + fields=[], + predicate=(r) => true +) => + fromRange(bucket: bucket, start: start, stop: stop) + |> filterMeasurement(measurement) + |> filter(fn: predicate) + |> filterFields(fields) +``` diff --git a/layouts/partials/article/flux-experimental.html b/layouts/partials/article/flux-experimental.html index 021036367..8a01cc8db 100644 --- a/layouts/partials/article/flux-experimental.html +++ b/layouts/partials/article/flux-experimental.html @@ -16,7 +16,7 @@

The {{ if $.Params.list_title }}{{ $.Params.list_title }}{{ else }}{{ .Title }}{{ end }} is experimental and subject to change at any time. - By using this function, you accept the risks of experimental functions. + By using this package, you accept the risks of experimental functions.

{{ end }}