---
title: Join data
description: Flux supports inner, full outer, left outer, and right outer joins. Learn how to use the join package to join two data sets with common values.
url: https://docs.influxdata.com/flux/v0/join-data/
estimated_tokens: 2057
product: Flux
version: v0
publisher: InfluxData
canonical: https://docs.influxdata.com/flux/v0/join-data/
date: '2023-09-12T23:33:31-06:00'
lastmod: '2023-09-12T23:33:31-06:00'
---

Use the Flux [`join` package](/flux/v0/stdlib/join/) to join two data sets based on common values.
Learn how join two data sets using the following join methods:

[

**Inner join**

](#perform-an-inner-join)

[

**Left outer join**

](#perform-a-left-outer-join)

[

**Right outer join**

](#perform-a-right-outer-join)

[

**Full outer join**

](#perform-a-full-outer-join)

> [!Note]
> #### When to use the join package
>
> We recommend using the `join` package to join streams that have mostly different
> schemas or that come from two separate data sources.
> If you’re joining data from the same data source with the same schema, using[`union()`](/flux/v0/stdlib/universe/union/) and [`pivot()`](/flux/v0/stdlib/universe/pivot/)to combine the data will likely be more performant.
>
> For more information, see[When to use union and pivot instead of join functions](/influxdb/v2/query-data/flux/join/#when-to-use-union-and-pivot-instead-of-join-functions).

* [How join functions work](#how-join-functions-work)
  * [Input streams](#input-streams)
  * [Join predicate function (on)](#join-predicate-function-on)
  * [Join output function (as)](#join-output-function-as)

* [Perform join operations](#perform-join-operations)
  * [Perform an inner join](#perform-an-inner-join)
  * [Perform a left outer join](#perform-a-left-outer-join)
  * [Perform a right outer join](#perform-a-right-outer-join)
  * [Perform a full outer join](#perform-a-full-outer-join)
  * [Join on time](#join-on-time)

* [Troubleshoot join operations](#troubleshoot-join-operations)

## How join functions work

`join` functions join *two* streams of tables together based
on common values in each input stream.

* [Input streams](#input-streams)
* [Join predicate function (on)](#join-predicate-function-on)
* [Join output function (as)](#join-output-function-as)

### Input streams

Each input stream is assigned to the `left` or `right` parameter.
Input streams can be defined from any valid data source.
For more information, see:

* [Query data sources](/flux/v0/query-data/)
* Define ad hoc tables with [`array.from()`](/flux/v0/stdlib/array/from/)

#### Data requirements

To join data, each input stream must have the following:

* **One or more columns with common values to join on**.  
  Columns do not need identical labels, but they do need to have comparable values.

* **Identical [group keys](/flux/v0/get-started/data-model/#group-key)**.  
  Functions in the `join` package use group keys to quickly determine what tables
  from each input stream should be paired and evaluated for the join operation.  
  *Both input streams should have the same group key.*If they don’t, your join operation may not find any matching tables and will
  return unexpected output.
  If the group keys of your input streams are not identical, use[`group()`](/flux/v0/stdlib/universe/group/) to regroup each input
  stream before joining them together.

  > [!Note]
> Only tables with the same [group key instance](/flux/v0/get-started/data-model/#example-group-key-instances)are joined.

### Join predicate function (on)

`join` package functions require the `on` parameter to compare values from each input stream (represented by `l` (left) and `r` (right))
and returns `true` or `false`.
Rows that return `true` are joined.
This parameter is a [predicate function](/flux/v0/get-started/syntax-basics/#predicate-functions).

```js
(l, r) => l.column == r.column
```

### Join output function (as)

`join` package functions *(except [`join.time()`](/flux/v0/stdlib/join/time/))*require the `as` parameter to define the output schema of the join.
The `as` parameter returns a new record using values from
joined rows–left (`l`) and right (`r`).

```js
(l, r) => ({l with name: r.name, location: r.location})
```

> [!Note]
> #### Do not modify group key columns
>
> Do not modify group key columns. The `as` function must return the same group key as both input streams to successfully perform a join.

## Perform join operations

The `join` package supports the following join types and special use cases:

* [Perform an inner join](#perform-an-inner-join)
* [Perform a left outer join](#perform-a-left-outer-join)
* [Perform a right outer join](#perform-a-right-outer-join)
* [Perform a full outer join](#perform-a-full-outer-join)
* [Join on time](#join-on-time)

### [Perform an inner join](/flux/v0/join-data/inner/)

Use [`join.inner()`](/flux/v0/stdlib/join/inner/) to perform an inner join of two streams of data. Inner joins drop any rows from both input streams that do not have a matching row in the other stream.

```js
import "join"

left = from(bucket: "example-bucket-1") |> //...
right = from(bucket: "example-bucket-2") |> //...

join.inner(
    left: left,
    right: right,
    on: (l, r) => l.column == r.column,
    as: (l, r) => ({l with name: r.name, location: r.location}),
)
```

[Read more ](/flux/v0/join-data/inner/)

### [Perform a left outer join](/flux/v0/join-data/left-outer/)

Use [`join.left()`](/flux/v0/stdlib/join/left/) to perform an outer left join of two streams of data. Left joins output a row for each row in the **left** data stream with data matching from the **right** data stream. If there is no matching data in the **right** data stream, non-group-key columns with values from the **right** data stream are *null*.

```js
import "join"

left = from(bucket: "example-bucket-1") |> //...
right = from(bucket: "example-bucket-2") |> //...

join.left(
    left: left,
    right: right,
    on: (l, r) => l.column == r.column,
    as: (l, r) => ({l with name: r.name, location: r.location}),
)
```

[Read more ](/flux/v0/join-data/left-outer/)

### [Perform a right outer join](/flux/v0/join-data/right-outer/)

Use [`join.right()`](/flux/v0/stdlib/join/right/) to perform an right outer join of two streams of data. Right joins output a row for each row in the **right** data stream with data matching from the **left** data stream. If there is no matching data in the **left** data stream, non-group-key columns with values from the **left** data stream are *null*.

```js
import "join"

left = from(bucket: "example-bucket-1") |> //...
right = from(bucket: "example-bucket-2") |> //...

join.right(
    left: left,
    right: right,
    on: (l, r) => l.column == r.column,
    as: (l, r) => ({r with name: l.name, location: l.location}),
)
```

[Read more ](/flux/v0/join-data/right-outer/)

### [Perform a full outer join](/flux/v0/join-data/full-outer/)

Use [`join.full()`](/flux/v0/stdlib/join/full/) to perform an full outer join of two streams of data. Full outer joins output a row for all rows in both the **left** and **right** input streams and join rows that match according to the `on` predicate.

```
import "join"

left = from(bucket: "example-bucket-1") |> //...
right = from(bucket: "example-bucket-2") |> //...

join.full(
    left: left,
    right: right,
    on: (l, r) => l.id== r.id,
    as: (l, r) => {
        id = if exists l.id then l.id else r.id

        return {name: l.name, location: r.location, id: id}
    },
)
```

[Read more ](/flux/v0/join-data/full-outer/)

### [Join on time](/flux/v0/join-data/time/)

Use [`join.time()`](/flux/v0/stdlib/join/time/) to join two streams of data based on time values in the `_time` column. This type of join operation is common when joining two streams of [time series data](/influxdb/v2/reference/glossary/#time-series-data).

```js
import "join"

left = from(bucket: "example-bucket-1") |> //...
right = from(bucket: "example-bucket-2") |> //...

join.time(
    left: left,
    right: right,
    as: (l, r) => ({l with field1: l._value, field2: r._value_}),
)
```

[Read more ](/flux/v0/join-data/time/)

## Troubleshoot join operations

For information about unexpected behaviors and errors when using the `join` package,
see [Troubleshoot join operations](/flux/v0/join-data/troubleshoot-joins/).

#### Related

* [join package](/flux/v0/stdlib/join/)
* [join.inner() function](/flux/v0/stdlib/join/inner/)
* [join.left() function](/flux/v0/stdlib/join/left/)
* [join.right() function](/flux/v0/stdlib/join/right/)
* [join.full() function](/flux/v0/stdlib/join/full/)
* [join.time() function](/flux/v0/stdlib/join/time/)