Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท LINQ

LINQ Join() and GroupJoin() methods

Reference for LINQ Join() and GroupJoin() in C#: inner joins on keys, left outer joins with DefaultIfEmpty, composite keys, comparers and performance.

Join() matches elements of two sequences by key and combines each matching pair into a result: an inner join, like SQL INNER JOIN. Elements without a partner on the other side are dropped.

GroupJoin() keeps every element of the first (outer) sequence and pairs it with the group of matching elements from the second, which may be empty. Combined with SelectMany() and DefaultIfEmpty() it produces a left outer join.

C#
var rows = orders.Join(customers, o => o.CustomerId, c => c.Id, (o, c) => new { c.Name, o.Total });
var tree = customers.GroupJoin(orders, c => c.Id, o => o.CustomerId, (c, os) => new { c.Name, Orders = os });

Try it

C# Inner join and group join

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Left outer join and composite keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public static IEnumerable<TResult> Join<TOuter, TInner, TKey, TResult>(
    this IEnumerable<TOuter> outer, IEnumerable<TInner> inner,
    Func<TOuter, TKey> outerKeySelector, Func<TInner, TKey> innerKeySelector,
    Func<TOuter, TInner, TResult> resultSelector,
    IEqualityComparer<TKey>? comparer = null);

public static IEnumerable<TResult> GroupJoin<TOuter, TInner, TKey, TResult>(
    this IEnumerable<TOuter> outer, IEnumerable<TInner> inner,
    Func<TOuter, TKey> outerKeySelector, Func<TInner, TKey> innerKeySelector,
    Func<TOuter, IEnumerable<TInner>, TResult> resultSelector,
    IEqualityComparer<TKey>? comparer = null);
Name Description
outer, inner The two sequences. Results follow the order of outer.
outerKeySelector, innerKeySelector Compute the join key from each side; keys must have the same type.
resultSelector Join(): called once per matching pair. GroupJoin(): called once per outer element with all its matches (possibly none).
comparer Optional key equality; the default is the default equality of TKey.

Returns: a lazy sequence of results.

Errors: ArgumentNullException for a null sequence or selector. Elements whose key is null never match anything.

Usage notes

  • How it works: the inner sequence is read once into a lookup table by key, then the outer sequence streams past it. Cost is O(n + m) plus the number of results, far better than a Where() inside a Select(), which is O(n x m).
  • Order: results follow the outer sequence; for each outer element, matches appear in inner order. This is documented behavior, unlike many hash-based operations.
  • One-to-many produces one result per pair: an order with three lines yields three rows.
  • No right or full outer join operators exist. Swap the arguments for a right join, or union two left joins.
  • Left join idiom: GroupJoin() then SelectMany(x => x.items.DefaultIfEmpty(), ...). For value types the default element is a zero value, which is ambiguous; project to a nullable first, or check a key.
  • Composite keys need a type with value equality: tuples, records and anonymous types qualify.
  • Query syntax: from o in orders join c in customers on o.CustomerId equals c.Id select ..., and join ... into g for GroupJoin().
  • Database providers translate these into SQL joins; in LINQ to Objects the full inner sequence is buffered in memory.