Merge pull request #937 from influxdata/flux/get-record-column
Flux 'getRecord' and 'getColumn' functionspull/966/head
Scott Anderson
GitHub
commit
7acdad37e2
|
|
@ -22,9 +22,9 @@ This lets you, for example, dynamically set variables using query results.
|
|||
|
||||
**To extract scalar values from output:**
|
||||
|
||||
1. [Extract a table](#extract-a-table).
|
||||
2. [Extract a column from the table](#extract-a-column-from-the-table)
|
||||
_**or**_ [extract a row from the table](#extract-a-row-from-the-table).
|
||||
1. [Extract a column from the input stream](#extract-a-column)
|
||||
_**or**_ [extract a row from the input stream](#extract-a-row).
|
||||
2. Use the returned array or object to reference scalar values.
|
||||
|
||||
_The samples on this page use the [sample data provided below](#sample-data)._
|
||||
|
||||
|
|
@ -38,61 +38,33 @@ _The samples on this page use the [sample data provided below](#sample-data)._
|
|||
See [#15321](https://github.com/influxdata/influxdb/issues/15231).
|
||||
{{% /warn %}}
|
||||
|
||||
## Extract a table
|
||||
## Table extraction
|
||||
Flux formats query results as a stream of tables.
|
||||
To extract a scalar value from a stream of tables, you must first extract a single table.
|
||||
|
||||
to extract a single table from the stream of tables.
|
||||
|
||||
{{% note %}}
|
||||
If query results include only one table, it is still formatted as a stream of tables.
|
||||
You still must extract that table from the stream.
|
||||
{{% /note %}}
|
||||
|
||||
Use [`tableFind()`](/v2.0/reference/flux/stdlib/built-in/transformations/stream-table/tablefind/)
|
||||
to extract the **first** table whose [group key](/v2.0/reference/glossary/#group-key)
|
||||
values match the `fn` [predicate function](/v2.0/reference/glossary/#predicate-expression).
|
||||
The predicate function requires a `key` object, which represents the group key of
|
||||
each table.
|
||||
|
||||
```js
|
||||
sampleData
|
||||
|> tableFind(fn: (key) =>
|
||||
key._field == "temp" and
|
||||
key.location == "sfo"
|
||||
)
|
||||
```
|
||||
|
||||
The example above returns a single table:
|
||||
|
||||
| _time | location | _field | _value |
|
||||
|:----- |:--------:|:------:| ------:|
|
||||
| 2019-11-01T12:00:00Z | sfo | temp | 65.1 |
|
||||
| 2019-11-01T13:00:00Z | sfo | temp | 66.2 |
|
||||
| 2019-11-01T14:00:00Z | sfo | temp | 66.3 |
|
||||
| 2019-11-01T15:00:00Z | sfo | temp | 66.8 |
|
||||
Both [`findColumn()`](/v2.0/reference/flux/stdlib/built-in/transformations/stream-table/findcolumn/)
|
||||
and [`findRecord()`](/v2.0/reference/flux/stdlib/built-in/transformations/stream-table/findrecord/)
|
||||
extract the first table in a stream of tables whose [group key](/v2.0/reference/glossary/#group-key)
|
||||
values match the `fn` [predicate function](/v2.0/reference/glossary/#predicate-function).
|
||||
|
||||
{{% note %}}
|
||||
#### Extract the correct table
|
||||
Flux functions do not guarantee table order and `tableFind()` returns only the
|
||||
**first** table that matches the `fn` predicate.
|
||||
To extract the table that includes the data you actually want, be very specific in
|
||||
your predicate function or filter and transform your data to minimize the number
|
||||
of tables piped-forward into `tableFind()`.
|
||||
Flux functions do not guarantee table order.
|
||||
`findColumn()` and `findRecord` extract only the **first** table that matches the `fn` predicate.
|
||||
To extract the correct table, be very specific in your predicate function or
|
||||
filter and transform your data to minimize the number of tables piped-forward into the functions.
|
||||
{{% /note %}}
|
||||
|
||||
## Extract a column from the table
|
||||
Use the [`getColumn()` function](/v2.0/reference/flux/stdlib/built-in/transformations/stream-table/getcolumn/)
|
||||
## Extract a column
|
||||
Use the [`findColumn()` function](/v2.0/reference/flux/stdlib/built-in/transformations/stream-table/findcolumn/)
|
||||
to output an array of values from a specific column in the extracted table.
|
||||
|
||||
_See [Sample data](#sample-data) below._
|
||||
|
||||
```js
|
||||
sampleData
|
||||
|> tableFind(fn: (key) =>
|
||||
key._field == "temp" and
|
||||
key.location == "sfo"
|
||||
|> findColumn(
|
||||
fn: (key) => key._field == "temp" and key.location == "sfo",
|
||||
column: "_value"
|
||||
)
|
||||
|> getColumn(column: "_value")
|
||||
|
||||
// Returns [65.1, 66.2, 66.3, 66.8]
|
||||
```
|
||||
|
|
@ -103,13 +75,14 @@ In the example below, `SFOTemps` represents the array of values.
|
|||
Reference a specific index (integer starting from `0`) in the array to return the
|
||||
value at that index.
|
||||
|
||||
_See [Sample data](#sample-data) below._
|
||||
|
||||
```js
|
||||
SFOTemps = sampleData
|
||||
|> tableFind(fn: (key) =>
|
||||
key._field == "temp" and
|
||||
key.location == "sfo"
|
||||
|> findColumn(
|
||||
fn: (key) => key._field == "temp" and key.location == "sfo",
|
||||
column: "_value"
|
||||
)
|
||||
|> getColumn(column: "_value")
|
||||
|
||||
SFOTemps
|
||||
// Returns [65.1, 66.2, 66.3, 66.8]
|
||||
|
|
@ -121,19 +94,18 @@ SFOTemps[2]
|
|||
// Returns 66.3
|
||||
```
|
||||
|
||||
## Extract a row from the table
|
||||
Use the [`getRecord()` function](/v2.0/reference/flux/stdlib/built-in/transformations/stream-table/getrecord/)
|
||||
## Extract a row
|
||||
Use the [`findRecord()` function](/v2.0/reference/flux/stdlib/built-in/transformations/stream-table/findrecord/)
|
||||
to output data from a single row in the extracted table.
|
||||
Specify the index of the row to output using the `idx` parameter.
|
||||
The function outputs an object with key-value pairs for each column.
|
||||
|
||||
```js
|
||||
sampleData
|
||||
|> tableFind(fn: (key) =>
|
||||
key._field == "temp" and
|
||||
key.location == "sfo"
|
||||
|> findRecord(
|
||||
fn: (key) => key._field == "temp" and key.location == "sfo",
|
||||
idx: 0
|
||||
)
|
||||
|> getRecord(idx: 0)
|
||||
|
||||
// Returns {
|
||||
// _time:2019-11-11T12:00:00Z,
|
||||
|
|
@ -151,11 +123,10 @@ keys in the object.
|
|||
|
||||
```js
|
||||
tempInfo = sampleData
|
||||
|> tableFind(fn: (key) =>
|
||||
key._field == "temp" and
|
||||
key.location == "sfo"
|
||||
|> findRecord(
|
||||
fn: (key) => key._field == "temp" and key.location == "sfo",
|
||||
idx: 0
|
||||
)
|
||||
|> getRecord(idx: 0)
|
||||
|
||||
tempInfo
|
||||
// Returns {
|
||||
|
|
@ -180,8 +151,10 @@ Create custom helper functions to extract scalar values from query output.
|
|||
// Define a helper function to extract field values
|
||||
getFieldValue = (tables=<-, field) => {
|
||||
extract = tables
|
||||
|> tableFind(fn: (key) => key._field == field)
|
||||
|> getColumn(column: "_value")
|
||||
|> findColumn(
|
||||
fn: (key) => key._field == field,
|
||||
column: "_value"
|
||||
)
|
||||
return extract[0]
|
||||
}
|
||||
|
||||
|
|
@ -200,8 +173,10 @@ lastJFKTemp
|
|||
// Define a helper function to extract a row as an object
|
||||
getRow = (tables=<-, field, idx=0) => {
|
||||
extract = tables
|
||||
|> tableFind(fn: (key) => true)
|
||||
|> getRecord(idx: idx)
|
||||
|> findRecord(
|
||||
fn: (key) => true,
|
||||
idx: idx
|
||||
)
|
||||
return extract
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: columns
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `columns()` function lists the column labels of input tables.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: cumulativeSum
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `cumulativeSum()` function computes a running sum for non-null records in the table.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: drop
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `drop()` function removes specified columns from a table.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: duplicate
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `duplicate()` function duplicates a specified column in a table.
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: elapsed
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `elapsed()` function returns the time between subsequent records.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: fill
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `fill()` function replaces all null values in an input stream with a non-null value.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: filter
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
v2.0/tags: [exists]
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: group
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `group()` function groups records based on their values for specific columns.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: histogram
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `histogram()` function approximates the cumulative distribution of a dataset by counting data frequencies for a list of bins.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: hourSelection
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `hourSelection()` function retains all rows with time values in a specified hour range.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: join
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
related:
|
||||
- /v2.0/reference/flux/stdlib/built-in/transformations/union/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: keep
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `keep()` function returns a table containing only the specified columns, ignoring all others.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: keys
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `keys()` function outputs the group key of input tables.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: keyValues
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `keyValues()` function returns a table with the input table's group key plus two columns,
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: limit
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
related:
|
||||
- /v2.0/reference/flux/stdlib/built-in/transformations/tail/
|
||||
- https://docs.influxdata.com/influxdb/latest/query_language/data_exploration/#the-limit-and-slimit-clauses, InfluxQL LIMIT
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: map
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
v2.0/tags: [exists]
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: pivot
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `pivot()` function collects values stored vertically (column-wise) in a table
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: range
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `range()` function filters records based on time bounds.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: rename
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `rename()` function renames specified columns in a table.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: set
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `set()` function assigns a static value to each record in the input table.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: sort
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `sort()` function orders the records within each table.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: stateCount
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `stateCount()` function computes the number of consecutive records in a given state.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: stateDuration
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `stateDuration()` function computes the duration of a given state.
|
||||
|
|
|
|||
|
|
@ -13,16 +13,38 @@ menu:
|
|||
name: Stream & table
|
||||
parent: built-in-transformations
|
||||
v2.0/tags: [transformations, built-in, functions, stream, table]
|
||||
related:
|
||||
- /v2.0/query-data/flux/scalar-values/
|
||||
---
|
||||
|
||||
Use stream and table functions to extract a table from a stream of tables and access its
|
||||
columns and records.
|
||||
|
||||
##### Example stream and table functions
|
||||
{{< children type="functions" >}}
|
||||
|
||||
### Example stream and table functions
|
||||
|
||||
##### Recommended usage
|
||||
```js
|
||||
data = from(bucket:"example-bucket")
|
||||
|> range(start: -5m)
|
||||
|> filter(fn:(r) => r._measurement == "cpu")
|
||||
|> range(start: -5m)
|
||||
|> filter(fn:(r) => r._measurement == "cpu")
|
||||
|
||||
// Extract the "_value" column from the table
|
||||
data
|
||||
|> findColumn(fn: (key) => key._field == "usage_idle", column: "_value")
|
||||
|
||||
// Extract the first record from the table
|
||||
data
|
||||
|> findRecord(fn: (key) => key._field == "usage_idle", idx: 0)
|
||||
|
||||
```
|
||||
|
||||
##### Alternate usage
|
||||
```js
|
||||
data = from(bucket:"example-bucket")
|
||||
|> range(start: -5m)
|
||||
|> filter(fn:(r) => r._measurement == "cpu")
|
||||
|
||||
// Extract the first available table for which "_field" is equal to "usage_idle"
|
||||
t = data |> tableFind(fn: (key) => key._field == "usage_idle")
|
||||
|
|
@ -33,5 +55,3 @@ values = t |> getColumn(column: "_value")
|
|||
// Extract the first record from the table
|
||||
r0 = t |> getRecord(idx: 0)
|
||||
```
|
||||
|
||||
{{< children type="functions" >}}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: findColumn() function
|
||||
description: >
|
||||
The `findColumn()` function returns an array of values in a specified column from the
|
||||
first table in a stream of tables where group key values match the specified predicate.
|
||||
menu:
|
||||
v2_0_ref:
|
||||
name: findColumn
|
||||
parent: Stream & table
|
||||
weight: 501
|
||||
related:
|
||||
- /v2.0/query-data/flux/scalar-values/
|
||||
---
|
||||
|
||||
The `findColumn()` function returns an array of values in a specified column from the
|
||||
first table in a stream of tables where the group key values match the specified predicate.
|
||||
The function returns an empty array if no table is found or if the column label
|
||||
is not present in the set of columns.
|
||||
|
||||
_**Function type:** Stream and table_
|
||||
|
||||
```js
|
||||
findColumn(
|
||||
fn: (key) => key._field == "fieldName")
|
||||
column: "_value"
|
||||
)
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
### fn
|
||||
A predicate function for matching keys in a table's group key.
|
||||
Expects a `key` argument that represents a group key in the input stream.
|
||||
|
||||
_**Data type:** Function_
|
||||
|
||||
### column
|
||||
Name of the column to extract.
|
||||
|
||||
_**Data type:** String_
|
||||
|
||||
## Example
|
||||
```js
|
||||
vs = from(bucket:"example-bucket")
|
||||
|> range(start: -5m)
|
||||
|> filter(fn:(r) => r._measurement == "cpu")
|
||||
|> findColumn(
|
||||
fn: (key) => key._field == "usage_idle",
|
||||
column: "_value"
|
||||
)
|
||||
|
||||
// Use column values
|
||||
x = vs[0] + vs[1]
|
||||
```
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: findRecord() function
|
||||
description: >
|
||||
The `findRecord()` function returns a record at a specified index from the first
|
||||
table in a stream of tables where the group key values match the specified predicate.
|
||||
menu:
|
||||
v2_0_ref:
|
||||
name: findRecord
|
||||
parent: Stream & table
|
||||
weight: 501
|
||||
related:
|
||||
- /v2.0/query-data/flux/scalar-values/
|
||||
---
|
||||
|
||||
The `findRecord()` function returns a record at a specified index from the first
|
||||
table in a stream of tables where the group key values match the specified predicate.
|
||||
The function returns an empty object if no table is found or if the index is out of bounds.
|
||||
|
||||
_**Function type:** Stream and table_
|
||||
|
||||
```js
|
||||
findRecord(
|
||||
fn: (key) => key._field == "fieldName",
|
||||
idx: 0
|
||||
)
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
### fn
|
||||
A predicate function for matching keys in a table's group key.
|
||||
Expects a `key` argument that represents a group key in the input stream.
|
||||
|
||||
_**Data type:** Function_
|
||||
|
||||
### idx
|
||||
Index of the record to extract.
|
||||
|
||||
_**Data type:** Integer_
|
||||
|
||||
## Example
|
||||
```js
|
||||
r0 = from(bucket:"example-bucket")
|
||||
|> range(start: -5m)
|
||||
|> filter(fn:(r) => r._measurement == "cpu")
|
||||
|> tableFind()
|
||||
|> findRecord(
|
||||
fn: (key) => key._field == "usage_idle",
|
||||
idx: 0
|
||||
)
|
||||
|
||||
// Use record values
|
||||
x = r0._field + "--" + r0._measurement
|
||||
```
|
||||
|
|
@ -31,7 +31,7 @@ to extract a single table from a stream of tables.
|
|||
## Parameters
|
||||
|
||||
### column
|
||||
The name of the column to extract.
|
||||
Name of the column to extract.
|
||||
|
||||
_**Data type:** String_
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ to extract a single table from a stream of tables.
|
|||
## Parameters
|
||||
|
||||
### idx
|
||||
The index of the record to extract.
|
||||
Index of the record to extract.
|
||||
|
||||
_**Data type:** Integer_
|
||||
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ To learn why, see [Match parameter names](/v2.0/reference/flux/language/data-mod
|
|||
|
||||
A predicate function for matching keys in a table's group key.
|
||||
`tableFind` returns the first table that resolves as `true`.
|
||||
It expects a `key` argument which represents a group key in the input stream.
|
||||
Expects a `key` argument that represents a group key in the input stream.
|
||||
|
||||
_**Data type:** Function_
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: tail
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
related:
|
||||
- /v2.0/reference/flux/functions/built-in/transformations/limit/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: timeShift
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `timeShift()` function adds a fixed duration to time columns.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: truncateTimeColumn
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
related:
|
||||
- /v2.0/reference/flux/stdlib/date/truncate/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: union
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
related:
|
||||
- /v2.0/reference/flux/stdlib/built-in/transformations/join/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ menu:
|
|||
v2_0_ref:
|
||||
name: window
|
||||
parent: built-in-transformations
|
||||
weight: 401
|
||||
weight: 402
|
||||
---
|
||||
|
||||
The `window()` function groups records based on a time value.
|
||||
|
|
|
|||
Loading…
Reference in New Issue