# Merge Verbs

Sometimes you'd like to merge two collections into one. There are a few ways of doing that in this library.

## Concat¶

If you just want to stack collections on top of each other, you can use `concat` for that. It's short for "concatenate".

``````from clumper import Clumper

c1 = Clumper([{"a": 1}])
c2 = Clumper([{"a": 2}])
c3 = Clumper([{"a": 3}])

assert len(c1.concat(c2)) == 2
assert len(c1.concat(c2, c3)) == 3
assert len(c1.concat(c2).concat(c3)) == 3
``````

## Joins¶

If you want to merge two collections together based on the values then you'd be interested in a `join`. When doing a join there are two sets: a leftset and a right set. Depending on the type of join that you are performing you will get different behavior.

### Left Join¶

A left join keeps all the values from the left table even when there's nothing from the right table that it can join on.

``````from clumper import Clumper

left = Clumper([
{"a": 1, "b": 4},
{"a": 2, "b": 6},
{"a": 3, "b": 8},
])

right = Clumper([
{"c": 9, "b": 4},
{"c": 8, "b": 5},
{"c": 7, "b": 6},
])

result = left.inner_join(right, mapping={"b": "b"})
expected = [
{"a": 1, "b": 4, "c": 9},
{"a": 2, "b": 6, "c": 7},
{"a": 3, "b": 8},
]

assert result.equals(expected)
``````

Note that items on the left hand side may appear multiple times.

``````from clumper import Clumper

left = Clumper([
{"a": 1, "b": 4},
{"a": 2, "b": 6},
{"a": 3, "b": 8},
])

right = Clumper([
{"c": 9, "b": 4},
{"c": 8, "b": 5},
{"c": 7, "b": 6},
{"c": 9, "b": 6},
])

result = left.left_join(right, mapping={"b": "b"})
expected = [
{'a': 1, 'b': 4, 'c': 9},
{'a': 2, 'b': 6, 'c': 7},
{'a': 2, 'b': 6, 'c': 9},
{'a': 3, 'b': 8}
]

assert result.equals(expected)
``````

### Right Join¶

This is not implemented. You can swap the left/right tables and still use the left-join for this.

### Inner Join¶

An inner join only keeps items that can be paired in both tables.

``````from clumper import Clumper

left = Clumper([
{"a": 1, "b":4},
{"a": 2, "b":6},
{"a": 3, "b":8},
])

right = Clumper([
{"c": 9, "b":4},
{"c": 8, "b":5},
{"c": 7, "b":6},
])

result = left.inner_join(right, mapping={"b": "b"})
expected = [
{"a": 1, "b": 4, "c": 9},
{"a": 2, "b": 6, "c": 7},
]

assert result.equals(expected)
``````