162 lines
3.8 KiB
Markdown
162 lines
3.8 KiB
Markdown
---
|
|
title: experimental.join() function
|
|
description: >
|
|
The `experimental.join()` function joins two streams of tables on the
|
|
group key with the addition of the `_time` column.
|
|
menu:
|
|
v2_0_ref:
|
|
name: experimental.join
|
|
parent: Experimental
|
|
weight: 302
|
|
---
|
|
|
|
The `experimental.join()` function joins two streams of tables on the
|
|
[group key](/v2.0/reference/glossary/#group-key) and `_time` column.
|
|
Columns that are not part of the group key or explicitly mapped in the join operation
|
|
are dropped from output tables.
|
|
|
|
{{% note %}}
|
|
To join streams of tables with different fields or measuremtns, use [`group()`](/v2.0/reference/flux/stdlib/built-in/transformations/group/)
|
|
or [`drop()`](/v2.0/reference/flux/stdlib/built-in/transformations/drop/) to remove
|
|
`_field` and `_measurement` from the group key before joining.
|
|
_See an example [below](#join-two-streams-of-tables-with-different-fields)._
|
|
{{% /note %}}
|
|
|
|
_**Function type:** Transformation_
|
|
|
|
```js
|
|
import "experimental"
|
|
|
|
// ...
|
|
|
|
experimental.join(
|
|
left: left,
|
|
right: right,
|
|
fn: (left, right) => ({left with lv: left._value, rv: right._value })
|
|
)
|
|
```
|
|
|
|
{{% note %}}
|
|
This function will likely replace the [`join` function](/v2.0/reference/flux/stdlib/built-in/transformations/join/)
|
|
when sufficiently vetted.
|
|
{{% /note %}}
|
|
|
|
## Parameters
|
|
|
|
### left
|
|
First of two streams of tables to join.
|
|
|
|
_**Data type:** Stream of tables_
|
|
|
|
### right
|
|
Second of two streams of tables to join.
|
|
|
|
_**Data type:** Stream of tables_
|
|
|
|
### fn
|
|
A function with `left` and `right` arguments that maps a new output object
|
|
using values from the `left` and `right` input objects.
|
|
The return value must be an object.
|
|
|
|
_**Data type:** Function_
|
|
|
|
## Examples
|
|
|
|
### Input and output tables
|
|
|
|
**Given the following input tables:**
|
|
{{< flex >}}
|
|
{{% flex-content %}}
|
|
##### left
|
|
| _time | _field | _value |
|
|
|:----- |:------:| ------:|
|
|
| 0001 | temp | 80.1 |
|
|
| 0002 | temp | 80.2 |
|
|
| 0003 | temp | 79.9 |
|
|
| 0004 | temp | 80.0 |
|
|
{{% /flex-content %}}
|
|
{{% flex-content %}}
|
|
##### right
|
|
| _time | _field | _value |
|
|
|:----- |:------:| ------:|
|
|
| 0001 | temp | 72.1 |
|
|
| 0002 | temp | 72.2 |
|
|
| 0003 | temp | 71.9 |
|
|
| 0004 | temp | 72.0 |
|
|
{{% /flex-content %}}
|
|
{{< /flex >}}
|
|
|
|
**The following `experimental.join()` function would output:**
|
|
|
|
```js
|
|
import "experimental"
|
|
|
|
experimental.join(
|
|
left: left,
|
|
right: right,
|
|
fn: (left, right) => ({
|
|
left with
|
|
lv: left._value,
|
|
rv: right._value,
|
|
diff: left._value - right._value
|
|
})
|
|
)
|
|
```
|
|
|
|
| _time | _field | lv | rv | diff |
|
|
|:----- |:------:|:--: |:--: | ----:|
|
|
| 0001 | temp | 80.1 | 72.1 | 8.0 |
|
|
| 0002 | temp | 80.2 | 72.2 | 8.0 |
|
|
| 0003 | temp | 79.9 | 71.9 | 8.0 |
|
|
| 0004 | temp | 80.0 | 72.0 | 8.0 |
|
|
|
|
---
|
|
|
|
###### Join two streams of tables
|
|
```js
|
|
import "experimental"
|
|
|
|
s1 = from(bucket: "example-bucket")
|
|
|> range(start: -1h)
|
|
|> filter(fn: (r) => r._measurement == "foo")
|
|
|
|
s2 = from(bucket: "example-bucket")
|
|
|> range(start: -1h)
|
|
|> filter(fn: (r) => r._measurement == "bar")
|
|
|
|
experimental.join(
|
|
left: s1,
|
|
right: s2,
|
|
fn: (left, right) => ({
|
|
left with
|
|
s1_value: left._value,
|
|
s2_value: right._value
|
|
})
|
|
)
|
|
```
|
|
|
|
###### Join two streams of tables with different fields and measurements
|
|
```js
|
|
import "experimental"
|
|
|
|
s1 = from(bucket: "example-bucket")
|
|
|> range(start: -1h)
|
|
|> filter(fn: (r) => r._measurement == "foo" and r._field == "bar")
|
|
|> group(columns: ["_time", "_measurement", "_field", "_value"], mode: "except")
|
|
|
|
s2 = from(bucket: "example-bucket")
|
|
|> range(start: -1h)
|
|
|> filter(fn: (r) => r._measurement == "baz" and r._field == "quz")
|
|
|> group(columns: ["_time", "_measurement", "_field", "_value"], mode: "except")
|
|
|
|
experimental.join(
|
|
left: s1,
|
|
right: s2,
|
|
fn: (left, right) => ({
|
|
left with
|
|
bar_value: left._value,
|
|
quz_value: right._value
|
|
})
|
|
)
|
|
```
|