> For the complete documentation index, see [llms.txt](https://danfo.jsdata.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://danfo.jsdata.org/api-reference/general-functions/danfo.merge.md).

# danfo.merge

danfo.**merge**(options)

| Parameters | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| options    | Object | <p><strong>left</strong>: A DataFrame or named Series object.</p><p><strong>right</strong>: Another DataFrame or named Series object.</p><p><strong>on</strong>: Column names to join on. Must be found in both the left and right DataFrame and/or Series objects.</p><p><strong>how</strong>: One of <code>'left','right'</code>,<code>'outer'</code>, <code>'inner'</code>. Defaults to 'inner'</p> |

## **Examples**

**danfo.js** merge function is similar to Pandas merge and performs in-memory join operations idiomatically very similar to relational databases like SQL.

danfo.js provides a single function, [`merge()`](/api-reference/general-functions/danfo.merge.md), as the entry point for all standard database join operations between `DataFrame` or named `Series` objects.

For a more intuitive understanding, this [guide](https://pandas.pydata.org/pandas-docs/stable/user_guide/merging.html#brief-primer-on-merge-methods-relational-algebra) on the [Pandas](https://pandas.pydata.org/pandas-docs/stable) doc is worth reading.

### **Merging by a single key found in both axis**

In the following example, we perform an inner join. An inner join requires each row in the two joined DataFrames to have matching column values. This is similar to the **intersection** of two sets. It returns a DataFrame with only those rows that have common characteristics.

{% tabs %}
{% tab title="Node" %}

```javascript
const dfd = require("danfojs-node")


let data = [['K0', 'k0', 'A0', 'B0'], ['k0', 'K1', 'A1', 'B1'],
            ['K1', 'K0', 'A2', 'B2'], ['K2', 'K2', 'A3', 'B3']]

let data2 = [['K0', 'k0', 'C0', 'D0'], ['K1', 'K0', 'C1', 'D1'],
            ['K1', 'K0', 'C2', 'D2'], ['K2', 'K0', 'C3', 'D3']]

let colum1 = ['Key1', 'Key2', 'A', 'B']
let colum2 = ['Key1', 'Key2', 'A', 'D']

let df1 = new dfd.DataFrame(data, { columns: colum1 })
let df2 = new dfd.DataFrame(data2, { columns: colum2 })
df1.print()
df2.print()

let merge_df = dfd.merge({ "left": df1, "right": df2, "on": ["Key1"], how: "inner"})
merge_df.print()
```

{% endtab %}

{% tab title="Browser" %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Output" %}

```
 //first DataFrame
╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ k0                │ K1                │ A1                │ B1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K2                │ A3                │ B3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


 //Second DataFrame

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K0                │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


 //After inner join on column 'Key1'

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 │ Key2_1            │ A_1               │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                │ k0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ A2                │ B2                │ K0                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                │ K0                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K2                │ A3                │ B3                │ K0                │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝
```

{% endtab %}
{% endtabs %}

### **Inner Join/Merge by multiple keys found in both axis**

Merging by two keys takes into consideration the keys appearing in both`left` and `right DataFrame.`

{% tabs %}
{% tab title="Node" %}

```javascript
const dfd = require("danfojs-node")


let data = [['K0', 'k0', 'A0', 'B0'], ['k0', 'K1', 'A1', 'B1'],
            ['K1', 'K0', 'A2', 'B2'], ['K2', 'K2', 'A3', 'B3']]

let data2 = [['K0', 'k0', 'C0', 'D0'], ['K1', 'K0', 'C1', 'D1'],
            ['K1', 'K0', 'C2', 'D2'], ['K2', 'K0', 'C3', 'D3']]

let colum1 = ['Key1', 'Key2', 'A', 'B']
let colum2 = ['Key1', 'Key2', 'A', 'D']

let df1 = new dfd.DataFrame(data, { columns: colum1 })
let df2 = new dfd.DataFrame(data2, { columns: colum2 })
df1.print()
df2.print()

let merge_df = dfd.merge({ left: df1, right: df2, 
                            on: ["Key1", 'Key2'], how: "inner"})
merge_df.print()
```

{% endtab %}

{% tab title="Browser" %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Output" %}

```
//first DataFrame
╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ k0                │ K1                │ A1                │ B1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K2                │ A3                │ B3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


//second DataFrame

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K0                │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


 //After inner join on two keys

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 │ A_1               │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ A2                │ B2                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                │ C2                │ D2                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝
```

{% endtab %}
{% endtabs %}

The how parameter takes other types of joins like left, right and outer join and these are similar to their SQL equivalent

### Outer join/merge on DataFrame

{% tabs %}
{% tab title="Node" %}

```javascript
const dfd = require("danfojs-node")


let data = [['K0', 'k0', 'A0', 'B0'], ['k0', 'K1', 'A1', 'B1'],
            ['K1', 'K0', 'A2', 'B2'], ['K2', 'K2', 'A3', 'B3']]

let data2 = [['K0', 'k0', 'C0', 'D0'], ['K1', 'K0', 'C1', 'D1'],
            ['K1', 'K0', 'C2', 'D2'], ['K2', 'K0', 'C3', 'D3']]

let colum1 = ['Key1', 'Key2', 'A', 'B']
let colum2 = ['Key1', 'Key2', 'A', 'D']

let df1 = new dfd.DataFrame(data, { columns: colum1 })
let df2 = new dfd.DataFrame(data2, { columns: colum2 })
df1.print()
df2.print()

let merge_df = dfd.merge({ left: df1, right: df2, 
                            on: ["Key1"], how: "outer"})
merge_df.print()
```

{% endtab %}

{% tab title="Browser" %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Output" %}

```
//First DataFrame
╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ k0                │ K1                │ A1                │ B1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K2                │ A3                │ B3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


 //Second DataFrame

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K0                │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝

//After outer join

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 │ Key2_1            │ A_1               │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                │ k0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ k0                │ K1                │ A1                │ B1                │ NaN               │ NaN               │ NaN               ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                │ K0                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K1                │ K0                │ A2                │ B2                │ K0                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 4 │ K2                │ K2                │ A3                │ B3                │ K0                │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝
```

{% endtab %}
{% endtabs %}

### Left join/merge on DataFrame

{% tabs %}
{% tab title="Node" %}

```javascript
const dfd = require("danfojs-node")


let data = [['K0', 'k0', 'A0', 'B0'], ['k0', 'K1', 'A1', 'B1'],
            ['K1', 'K0', 'A2', 'B2'], ['K2', 'K2', 'A3', 'B3']]

let data2 = [['K0', 'k0', 'C0', 'D0'], ['K1', 'K0', 'C1', 'D1'],
            ['K1', 'K0', 'C2', 'D2'], ['K2', 'K0', 'C3', 'D3']]

let colum1 = ['Key1', 'Key2', 'A', 'B']
let colum2 = ['Key1', 'Key2', 'A', 'D']

let df1 = new dfd.DataFrame(data, { columns: colum1 })
let df2 = new dfd.DataFrame(data2, { columns: colum2 })
df1.print()
df2.print()

let merge_df = dfd.merge({ left: df1, right: df2, 
                            on: ["Key1", "Key2"], how: "left"})
merge_df.print()
```

{% endtab %}

{% tab title="Browser" %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Output" %}

```
//first DataFrame
╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ k0                │ K1                │ A1                │ B1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K2                │ A3                │ B3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


//second DataFrame

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K0                │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


 After left join
╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 │ A_1               │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ k0                │ K1                │ A1                │ B1                │ NaN               │ NaN               ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K1                │ K0                │ A2                │ B2                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 4 │ K2                │ K2                │ A3                │ B3                │ NaN               │ NaN               ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝
```

{% endtab %}
{% endtabs %}

### Right join/merge on DataFrame

{% tabs %}
{% tab title="Node" %}

```javascript
const dfd = require("danfojs-node")


let data = [['K0', 'k0', 'A0', 'B0'], ['k0', 'K1', 'A1', 'B1'],
            ['K1', 'K0', 'A2', 'B2'], ['K2', 'K2', 'A3', 'B3']]

let data2 = [['K0', 'k0', 'C0', 'D0'], ['K1', 'K0', 'C1', 'D1'],
            ['K1', 'K0', 'C2', 'D2'], ['K2', 'K0', 'C3', 'D3']]

let colum1 = ['Key1', 'Key2', 'A', 'B']
let colum2 = ['Key1', 'Key2', 'A', 'D']

let df1 = new dfd.DataFrame(data, { columns: colum1 })
let df2 = new dfd.DataFrame(data2, { columns: colum2 })
df1.print()
df2.print()

let merge_df = dfd.merge({ left: df1, right: df2, 
                            on: ["Key1", "Key2"], how: "right"})
merge_df.print()
```

{% endtab %}

{% tab title="Browser" %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Output" %}

```
//first DataFrame
╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ k0                │ K1                │ A1                │ B1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K2                │ A3                │ B3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


 //second DataFrame

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K0                │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝


//after right join

╔═══╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╤═══════════════════╗
║   │ Key1              │ Key2              │ A                 │ B                 │ A_1               │ D                 ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 0 │ K0                │ k0                │ A0                │ B0                │ C0                │ D0                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 1 │ K1                │ K0                │ A2                │ B2                │ C1                │ D1                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 2 │ K1                │ K0                │ A2                │ B2                │ C2                │ D2                ║
╟───┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────┼───────────────────╢
║ 3 │ K2                │ K0                │ NaN               │ NaN               │ C3                │ D3                ║
╚═══╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╧═══════════════════╝
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
See also [danfo.concat ](/api-reference/general-functions/danfo.concat.md)for joining objects based on axis.
{% endhint %}