Join and GroupJoin operations in C Sharp (C#)

Introduction

Join and GroupJoin help you combine two lists based on matching values. They make it easy to find related data from different sources.

You have two lists, like students and their grades, and want to match students with their grades.

You want to find all orders and the products in each order.

You need to combine employee data with their department info.

You want to group related items, like customers and their orders.

Syntax

C Sharp (C#)

var joinResult = list1.Join(
    list2,
    item1 => item1.Key,
    item2 => item2.Key,
    (item1, item2) => new { item1, item2 }
);

var groupJoinResult = list1.GroupJoin(
    list2,
    item1 => item1.Key,
    item2 => item2.Key,
    (item1, group) => new { item1, group }
);

Join matches items one-to-one based on keys.

GroupJoin matches one item to many related items as a group.

Examples

This joins students with their grades by matching student IDs.

C Sharp (C#)

var joinResult = students.Join(
    grades,
    student => student.Id,
    grade => grade.StudentId,
    (student, grade) => new { student.Name, grade.Score }
);

This groups all grades for each student.

C Sharp (C#)

var groupJoinResult = students.GroupJoin(
    grades,
    student => student.Id,
    grade => grade.StudentId,
    (student, gradesGroup) => new { student.Name, Grades = gradesGroup.Select(g => g.Score) }
);

Sample Program

This program shows how to use Join to pair each student with each of their grades, and GroupJoin to group all grades per student.

C Sharp (C#)

using System;
using System.Collections.Generic;
using System.Linq;

class Program
{
    public class Student
    {
        public int Id { get; set; }
        public string Name { get; set; }
    }

    public class Grade
    {
        public int StudentId { get; set; }
        public int Score { get; set; }
    }

    static void Main()
    {
        var students = new List<Student>
        {
            new() { Id = 1, Name = "Alice" },
            new() { Id = 2, Name = "Bob" },
            new() { Id = 3, Name = "Charlie" }
        };

        var grades = new List<Grade>
        {
            new() { StudentId = 1, Score = 85 },
            new() { StudentId = 1, Score = 90 },
            new() { StudentId = 2, Score = 78 }
        };

        var joinResult = students.Join(
            grades,
            student => student.Id,
            grade => grade.StudentId,
            (student, grade) => new { student.Name, grade.Score }
        );

        Console.WriteLine("Join result (student and each grade):");
        foreach (var item in joinResult)
        {
            Console.WriteLine($"{item.Name} scored {item.Score}");
        }

        var groupJoinResult = students.GroupJoin(
            grades,
            student => student.Id,
            grade => grade.StudentId,
            (student, gradesGroup) => new { student.Name, Scores = gradesGroup.Select(g => g.Score) }
        );

        Console.WriteLine("\nGroupJoin result (student and all grades):");
        foreach (var item in groupJoinResult)
        {
            var scores = string.Join(", ", item.Scores);
            Console.WriteLine($"{item.Name} scored: {scores}");
        }
    }
}

Important Notes

If no matching items are found in Join, those items are skipped.

GroupJoin always includes all items from the first list, even if the group is empty.

Use GroupJoin when you want to keep all items from the first list and group related items from the second.

Summary

Join matches items one-to-one based on keys.

GroupJoin matches one item to many related items as a group.

Both help combine related data from two lists easily.