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 #795 from influxdata/common-queries 

Common queries
pull/800/head
Scott Anderson 2020-03-05 15:22:49 -07:00 committed by GitHub
parent 9a3753acba 8128b25735
commit 3eb71e39ce
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 567 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
CONTRIBUTING.md
View File

@ -509,6 +509,38 @@ The following options are available:
{{< ui-message color="green" text="The message displayed in the notification.">}}
```
### Flexbox-formatted content blocks
CSS Flexbox formatting lets you create columns in article content that adjust and
flow based on the viewable width.
In article content, this helps if you have narrow tables that could be displayed
side-by-side, rather than stacked vertically.
Use the `{{< flex >}}` shortcode to create the Flexbox wrapper.
Use the `{{% flex-content %}}` shortcode to identify each column content block.
```md
{{< flex >}}
{{% flex-content %}}
Column 1
{{% /flex-content %}}
{{% flex-content %}}
Column 2
{{% /flex-content %}}
{{< /flex >}}
```
`{{% flex-content %}}` has an optional width argument that determines the maximum
width of the column.
```md
{{% flex-content "half" %}}
```
The following options are available:
- half _(Default)_
- third
- quarter
### Reference content
The InfluxDB documentation is "task-based," meaning content primarily focuses on
what a user is **doing**, not what they are **using**.

1
assets/styles/layouts/_article.scss
View File

@ -104,6 +104,7 @@
"article/cloud",
"article/enterprise",
"article/feedback",
"article/flex",
"article/lists",
"article/note",
"article/pagination-btns",

24
assets/styles/layouts/article/_flex.scss Normal file
View File

@ -0,0 +1,24 @@
/////////////////////////// Flex Content Blocks ///////////////////////////
.flex-wrapper {
display: flex;
flex-wrap: wrap;
}
.flex-container {
margin-right: 1rem;
&.half { width: calc(50% - 1rem); }
&.third { width: calc(33.33% - 1rem); }
&.quarter { width: calc(25% - 1rem); }
}
////////////////////////////////////////////////////////////////////////////////
///////////////////////////////// MEDIA QUERIES ////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
@include media(small) {
.flex-container {
&.half, &.third { width: calc(100% - 1rem); }
&.quarter { width: calc(50% - 1rem); }
}
}

47
content/v2.0/query-data/common-queries/_index.md Normal file
View File

@ -0,0 +1,47 @@
---
title: Common Flux queries
description: >
placeholder
weight: 103
menu:
v2_0:
parent: Query data
name: Common queries
v2.0/tags: [query]
---
{{% note %}}
#### Example data variable
Many of the examples provided in the following guides use a `data` variable,
which represents a basic query that filters data by measurement and field.
`data` is defined as:
```js
data = from(bucket: "example-bucket")
|> range(start: -1h)
|> filter(fn: (r) =>
r._measurement == "example-measurement" and
r._field == "example-field"
)
```
{{% /note %}}
{{< children >}}
---
- [x] SELECT-like commands
- [x] Median
- [x] Percentile
- [ ] Cumulative Sum
- [ ] Moving Average
- [ ] Increase
- [ ] Rate
- [ ] Delta
- [ ] Window
- [ ] First/Last
- [ ] Histogram
- [ ] Gap filling
- [ ] Last observation carried forward
- [ ] Last point

67
content/v2.0/query-data/common-queries/cumulativesum.md Normal file
View File

@ -0,0 +1,67 @@
---
title: Query cumulative sum
seotitle: Query cumulative sum in Flux
list_title: Cumulative sum
description: >
Use the `cumulativeSum()` function to calculate a running total of values.
weight: 204
menu:
v2_0:
parent: Common queries
name: Cumulative sum
v2.0/tags: [query, cumulative sum]
---
Use the [`cumulativeSum()` function](/v2.0/reference/flux/stdlib/built-in/transformations/cumulativesum/)
to calculate a running total of values.
`cumulativeSum` sums the values of subsequent records and returns each row updated with the summed total.
{{< flex >}}
{{% flex-content "half" %}}
**Given the following input table:**
| _time | _value |
| ----- |:------:|
| 0001 | 1 |
| 0002 | 2 |
| 0003 | 1 |
| 0004 | 3 |
{{% /flex-content %}}
{{% flex-content "half" %}}
**`cumulativeSum()` returns:**
| _time | _value |
| ----- |:------:|
| 0001 | 1 |
| 0002 | 3 |
| 0003 | 4 |
| 0004 | 7 |
{{% /flex-content %}}
{{< /flex >}}
{{% note %}}
The examples below use the [example data variable](/v2.0/query-data/common-queries/#example-data-variable).
{{% /note %}}
##### Calculate the running total of values
```js
data
|> cumulativeSum()
```
## Use cumulativeSum() with aggregateWindow()
[`aggregateWindow()`](/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/)
segments data into windows of time, aggregates data in each window into a single
point, then removes the time-based segmentation.
It is primarily used to [downsample data](/v2.0/process-data/common-tasks/downsample-data/).
`aggregateWindow()` expects an aggregate function that returns a single row for each time window.
To use `cumulativeSum()` with `aggregateWindow`, use `sum` in `aggregateWindow()`,
then calculate the running total of the aggregate values with `cumulativeSum()`.
<!-- -->
```js
data
|> aggregateWindow(every: 5m, fn: sum)
|> cumulativeSum()
```

147
content/v2.0/query-data/common-queries/median.md Normal file
View File

@ -0,0 +1,147 @@
---
title: Query median values
seotitle: Query median values in Flux
list_title: Median
description: >
Use the `median()` function to return a value representing the `0.5` quantile
(50th percentile) or median of input data.
weight: 202
menu:
v2_0:
parent: Common queries
name: Median
v2.0/tags: [query, median]
related:
- /v2.0/query-data/common-queries/percentile-quantile/
---
Use the [`median()` function](/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/median/)
to return a value representing the `0.5` quantile (50th percentile) or median of input data.
## Select a method for calculating the median
Select one of the following methods to calculate the median:
- [estimate_tdigest](#estimate-tdigest)
- [exact_mean](#exact-mean)
- [exact_selector](#exact-selector)
### estimate_tdigest
**(Default)** An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest)
to compute an accurate `0.5` quantile estimate on large data sources.
Output tables consist of a single row containing the calculated median.
{{< flex >}}
{{% flex-content %}}
**Given the following input table:**
| _time | _value |
| ----- |:------:|
| 0001 | 1.0 |
| 0002 | 1.0 |
| 0003 | 2.0 |
| 0004 | 3.0 |
{{% /flex-content %}}
{{% flex-content %}}
**`estimate_tdigest` returns:**
| _value |
|:------:|
| 1.5 |
{{% /flex-content %}}
{{< /flex >}}
### exact_mean
An aggregate method that takes the average of the two points closest to the `0.5` quantile value.
Output tables consist of a single row containing the calculated median.
{{< flex >}}
{{% flex-content %}}
**Given the following input table:**
| _time | _value |
| ----- |:------:|
| 0001 | 1.0 |
| 0002 | 1.0 |
| 0003 | 2.0 |
| 0004 | 3.0 |
{{% /flex-content %}}
{{% flex-content %}}
**`exact_mean` returns:**
| _value |
|:------:|
| 1.5 |
{{% /flex-content %}}
{{< /flex >}}
### exact_selector
A selector method that returns the data point for which at least 50% of points are less than.
Output tables consist of a single row containing the calculated median.
{{< flex >}}
{{% flex-content %}}
**Given the following input table:**
| _time | _value |
| ----- |:------:|
| 0001 | 1.0 |
| 0002 | 1.0 |
| 0003 | 2.0 |
| 0004 | 3.0 |
{{% /flex-content %}}
{{% flex-content %}}
**`exact_selector` returns:**
| _time | _value |
| ----- |:------:|
| 0002 | 1.0 |
{{% /flex-content %}}
{{< /flex >}}
{{% note %}}
The examples below use the [example data variable](/v2.0/query-data/common-queries/#example-data-variable).
{{% /note %}}
## Find the value that represents the median
Use the default method, `"estimate_tdigest"`, to return all rows in a table that
contain values in the 50th percentile of data in the table.
```js
data
|> median()
```
## Find the average of values closest to the median
Use the `exact_mean` method to return a single row per input table containing the
average of the two values closest to the mathematical median of data in the table.
```js
data
|> median(method: "exact_mean")
```
## Find the point with the median value
Use the `exact_selector` method to return a single row per input table containing the
value that 50% of values in the table are less than.
```js
data
|> median(method: "exact_selector")
```
## Use median() with aggregateWindow()
[`aggregateWindow()`](/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/)
segments data into windows of time, aggregates data in each window into a single
point, and then removes the time-based segmentation.
It is primarily used to [downsample data](/v2.0/process-data/common-tasks/downsample-data/).
To specify the [median calculation method](#median-calculation-methods) in `aggregateWindow()`, use the
[full function syntax](/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/#specify-parameters-of-the-aggregate-function):
```js
data
|> aggregateWindow(
every: 5m,
fn: (tables=<-, column) => tables |> median(method: "exact_selector")
)
```

163
content/v2.0/query-data/common-queries/percentile-quantile.md Normal file
View File

@ -0,0 +1,163 @@
---
title: Query percentile and quantile values
seotitle: Query percentile and quantile values in Flux
list_title: Percentile & quantile
description: >
Use the `quantile()` function to return all values within the `q` quantile or
percentile of input data.
weight: 203
menu:
v2_0:
parent: Common queries
name: Percentile & quantile
v2.0/tags: [query, percentile, quantile]
related:
- /v2.0/query-data/common-queries/query-median/
---
Use the [`quantile()` function](/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/quantile/)
to return a value representing the `q` quantile or percentile of input data.
## Percentile versus quantile
Percentiles and quantiles are very similar, differing only in the number used to calculate return values.
A percentile is calculated using numbers between `0` and `100`.
A quantile is calculated using numbers between `0.0` and `1.0`.
For example, the **`0.5` quantile** is the same as the **50th percentile**.
## Select a method for calculating the quantile
Select one of the following methods to calculate the quantile:
- [estimate_tdigest](#estimate-tdigest)
- [exact_mean](#exact-mean)
- [exact_selector](#exact-selector)
### estimate_tdigest
**(Default)** An aggregate method that uses a [t-digest data structure](https://github.com/tdunning/t-digest)
to compute a quantile estimate on large data sources.
Output tables consist of a single row containing the calculated quantile.
If calculating the `0.5` quantile or 50th percentile:
{{< flex >}}
{{% flex-content %}}
**Given the following input table:**
| _time | _value |
| ----- |:------:|
| 0001 | 1.0 |
| 0002 | 1.0 |
| 0003 | 2.0 |
| 0004 | 3.0 |
{{% /flex-content %}}
{{% flex-content %}}
**`estimate_tdigest` returns:**
| _value |
|:------:|
| 1.5 |
{{% /flex-content %}}
{{< /flex >}}
### exact_mean
An aggregate method that takes the average of the two points closest to the quantile value.
Output tables consist of a single row containing the calculated quantile.
If calculating the `0.5` quantile or 50th percentile:
{{< flex >}}
{{% flex-content %}}
**Given the following input table:**
| _time | _value |
| ----- |:------:|
| 0001 | 1.0 |
| 0002 | 1.0 |
| 0003 | 2.0 |
| 0004 | 3.0 |
{{% /flex-content %}}
{{% flex-content %}}
**`exact_mean` returns:**
| _value |
|:------:|
| 1.5 |
{{% /flex-content %}}
{{< /flex >}}
### exact_selector
A selector method that returns the data point for which at least `q` points are less than.
Output tables consist of a single row containing the calculated quantile.
If calculating the `0.5` quantile or 50th percentile:
{{< flex >}}
{{% flex-content %}}
**Given the following input table:**
| _time | _value |
| ----- |:------:|
| 0001 | 1.0 |
| 0002 | 1.0 |
| 0003 | 2.0 |
| 0004 | 3.0 |
{{% /flex-content %}}
{{% flex-content %}}
**`exact_selector` returns:**
| _time | _value |
| ----- |:------:|
| 0002 | 1.0 |
{{% /flex-content %}}
{{< /flex >}}
{{% note %}}
The examples below use the [example data variable](/v2.0/query-data/common-queries/#example-data-variable).
{{% /note %}}
## Find the value representing the 99th percentile
Use the default method, `"estimate_tdigest"`, to return all rows in a table that
contain values in the 99th percentile of data in the table.
```js
data
|> quantile(q: 0.99)
```
## Find the average of values closest to the quantile
Use the `exact_mean` method to return a single row per input table containing the
average of the two values closest to the mathematical quantile of data in the table.
For example, to calculate the `0.99` quantile:
```js
data
|> quantile(q: 0.99, method: "exact_mean")
```
## Find the point with the quantile value
Use the `exact_selector` method to return a single row per input table containing the
value that `q * 100`% of values in the table are less than.
For example, to calculate the `0.99` quantile:
```js
data
|> quantile(q: 0.99, method: "exact_selector")
```
## Use quantile() with aggregateWindow()
[`aggregateWindow()`](/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/)
segments data into windows of time, aggregates data in each window into a single
point, and then removes the time-based segmentation.
It is primarily used to [downsample data](/v2.0/process-data/common-tasks/downsample-data/).
To specify the [quantile calculation method](#quantile-calculation-methods) in
`aggregateWindow()`, use the [full function syntax](/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow/#specify-parameters-of-the-aggregate-function):
```js
data
|> aggregateWindow(
every: 5m,
fn: (tables=<-, column) =>
tables
|> quantile(q: 0.99, method: "exact_selector")
)
```

67
content/v2.0/query-data/common-queries/query-fields.md Normal file
View File

@ -0,0 +1,67 @@
---
title: Query fields and tags
seotitle: Query fields and tags in InfluxDB using Flux
description: >
Use the `filter()` function to query data based on fields, tags, or any other column value.
`filter()` performs operations similar to the `SELECT` statement and the `WHERE`
clause in InfluxQL and other SQL-like query languages.
weight: 201
menu:
v2_0:
parent: Common queries
v2.0/tags: [query, select, where]
---
Use the [`filter()` function](/v2.0/reference/flux/stdlib/built-in/transformations/filter/)
to query data based on fields, tags, or any other column value.
`filter()` performs operations similar to the `SELECT` statement and the `WHERE`
clause in InfluxQL and other SQL-like query languages.
## The filter() function
`filter()` has an `fn` parameter that expects a [predicate function](/v2.0/reference/glossary/#predicate-function),
an anonymous function comprised of one or more [predicate expressions](/v2.0/reference/glossary/#predicate-expression).
The predicate function evaluates each input row.
Rows that evaluate to `true` are **included** in the output data.
Rows that evaluate to `false` are **excluded** from the output data.
```js
// ...
|> filter(fn: (r) => r._measurement == "example-measurement" )
```
The `fn` predicate function requires an `r` argument, which represents each row
as `filter()` iterates over input data.
Key-value pairs in the row object represent columns and their values.
Use **dot notation** or **bracket notation** to reference specific column values in the predicate function.
Use [logical operators](/v2.0/reference/flux/language/operators/#logical-operators)
to chain multiple predicate expressions together.
```js
// Row object
r = {foo: "bar", baz: "quz"}
// Example predicate function
(r) => r.foo == "bar" and r["baz"] == "quz"
// Evaluation results
(r) => true and true
```
## Filter by fields and tags
The combination of [`from()`](/v2.0/reference/flux/stdlib/built-in/inputs/from),
[`range()`](/v2.0/reference/flux/stdlib/built-in/transformations/range),
and `filter()` represent the most basic Flux query:
1. Use `from()` to define your [bucket](/v2.0/reference/glossary/#bucket).
2. Use `range()` to limit query results by time.
3. Use `filter()` to identify what rows of data to output.
```js
from(bucket: "example-bucket")
|> range(start: -1h)
|> filter(fn: (r) =>
r._measurement == "example-measurement" and
r._field == "example-field" and
r.tag == "example-tag"
)
```

9
content/v2.0/reference/glossary.md
View File

@ -708,6 +708,15 @@ A predicate expression compares two values and returns `true` or `false` based o
the relationship between the two values.
A predicate expression is comprised of a left operand, a comparison operator, and a right operand.
### predicate function
A Flux predicate function is an anonymous function that returns `true` or `false`
based on one or more [predicate expressions](#predicate-expression).
###### Example predicate function
```js
(r) => r.foo == "bar" and r.baz != "quz"
```
### process
A set of predetermined rules.

2
content/v2.0/visualize-data/variables/common-variables.md
View File

@ -54,7 +54,7 @@ List all unique tag values for a specific tag in a specified bucket.
The example below lists all unique values of the `host` tag.
_**Flux package:** [InfluxDB v1](/v2.0/reference/flux/stdlib/influxdb-v1/)_
_**Flux functions:** [v1.measurements()](/v2.0/reference/flux/stdlib/influxdb-v1/measurements/)_
_**Flux functions:** [v1.tagValues()](/v2.0/reference/flux/stdlib/influxdb-v1/tagvalues/)_
```js
import "influxdata/influxdb/v1"

5
layouts/shortcodes/flex-content.html Normal file
View File

@ -0,0 +1,5 @@
{{ $width := .Get 0 | default "half" }}
{{ $_hugo_config := `{ "version": 1 }` }}
<div class="flex-container {{ $width }}">
{{ .Inner }}
</div>

4
layouts/shortcodes/flex.html Normal file
View File

@ -0,0 +1,4 @@
{{ $_hugo_config := `{ "version": 1 }` }}
<div class="flex-wrapper">
{{ .Inner }}
</div>