---
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: 6727
product: Flux
version: v0
---

# Join data

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)

#### 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.
    
    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})
```

#### 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.

```js
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/)