Initial support for leftOuterJoin

Author: Thorium

docs/RELEASE_NOTES.md

@@ -1,3 +1,6 @@
+### 1.5.24 - 12.06.2026
+* Initial support for standard F# `leftOuterJoin .. into g` / `g.DefaultIfEmpty()` left outer joins (single/multi-key and chained over several tables): unmatched columns are None/default and a whole selected entity is null #540 #697
+
 ### 1.5.23 - 12.06.2026
 * SQLite: added missing string type mappings (longvarchar, longchar, longnvarchar, clob) #101
 * PostgreSQL: skip columns with types unknown to Npgsql (e.g. PostGIS geometry) instead of failing the table #695

docs/content/core/querying.fsx

@@ -218,7 +218,7 @@ if                       |X |
 join                     |X |                                                       |
 last                     |  |                                                       |
 lastOrDefault            |  |                                                       |
-leftOuterJoin            |  |                                                       |
+leftOuterJoin            |x | Standard `leftOuterJoin .. into g` + `g.DefaultIfEmpty()`, see below |
 let                      |x | ...but not using tmp variables in where-clauses       |
 maxBy                    |X | Single table (1)                                      |
 maxByNullable            |X | Single table (1)                                      |
@@ -418,7 +418,28 @@ You can find some custom operators `using FSharp.Data.Sql`:
 * `|<>|` (Not in set)
 * `=%` (Like)
 * `<>%` (Not like)
-* `!!` (Left join)
+* `!!` (Left join: the joined entity is populated with default values when there is no match)
+
+### Left outer joins
+
+There are two ways to do a `LEFT OUTER JOIN`:
+
+The standard F# `leftOuterJoin ... into g` query operator (with `g.DefaultIfEmpty()`) is supported.
+When there is no matching row the joined columns are `None` (under `UseOptionTypes`) / default, and
+the joined entity itself is `null` if you select it whole:
+
+```fsharp
+let res =
+    query {
+        for cust in ctx.Main.Customers do
+        leftOuterJoin order in ctx.Main.Orders on (cust.CustomerId = order.CustomerId) into result
+        for order in result.DefaultIfEmpty() do
+        select (cust.CustomerId, order.OrderDate) // OrderDate is None / default when the customer has no orders
+    }
+```
+
+Alternatively the `!!` operator does an inline left join, but (unlike the form above) the joined
+entity is populated with default values rather than being null when there is no match.
 
 ## Best practices working with queries
 

src/SQLProvider.Common/AssemblyInfo.fs

@@ -5,13 +5,13 @@ open System.Reflection
 [<assembly: AssemblyTitleAttribute("SQLProvider.Common")>]
 [<assembly: AssemblyProductAttribute("SQLProvider")>]
 [<assembly: AssemblyDescriptionAttribute("Type provider for SQL database access, common library")>]
-[<assembly: AssemblyVersionAttribute("1.5.23")>]
-[<assembly: AssemblyFileVersionAttribute("1.5.23")>]
+[<assembly: AssemblyVersionAttribute("1.5.24")>]
+[<assembly: AssemblyFileVersionAttribute("1.5.24")>]
 do ()
 
 module internal AssemblyVersionInformation =
     let [<Literal>] AssemblyTitle = "SQLProvider.Common"
     let [<Literal>] AssemblyProduct = "SQLProvider"
     let [<Literal>] AssemblyDescription = "Type provider for SQL database access, common library"
-    let [<Literal>] AssemblyVersion = "1.5.23"
-    let [<Literal>] AssemblyFileVersion = "1.5.23"
+    let [<Literal>] AssemblyVersion = "1.5.24"
+    let [<Literal>] AssemblyFileVersion = "1.5.24"

src/SQLProvider.Common/Operators.fs

@@ -289,8 +289,8 @@ module Operators =
     /// Used after "in" and before the context.tablename
     /// param a: The related table queryable
     /// A queryable that performs a left outer join
-    let (!!) (a:IQueryable<'a>) = query { for x in a do select (leftJoin x) } 
-    
+    let (!!) (a:IQueryable<'a>) = query { for x in a do select (leftJoin x) }
+
     /// Calculates the standard deviation of numeric values in a column.
     /// Used in aggregate queries with groupBy.
     /// param a: The column value

src/SQLProvider.Common/SqlRuntime.Common.fs

@@ -417,6 +417,31 @@ type SqlEntity(dc: ISqlDataContext, tableName, columns: ColumnLookup, activeColu
             aliasCache.Value.Add(alias,newEntity)
             newEntity
 
+    /// Like GetSubTable, but returns null when the aliased table produced no matching row in a
+    /// left outer join (i.e. all of its columns are null). Used by the `leftOuterJoin ... into g`
+    /// form so the joined result-set entity is null instead of an entity full of default values.
+    /// Note: a real match always has a non-null primary key, so only genuine no-match rows
+    /// (every selected column null) are mapped to null.
+    member internal e.GetSubTableNullable(alias:string, tableName) =
+        let sub = e.GetSubTable(alias, tableName)
+        // Decide no-match by looking ONLY at columns that are genuinely qualified with this alias.
+        // GetSubTable also copies unqualified/foreign columns as a fallback (Utilities.checkPred),
+        // which must not count here. checkPred strips the alias prefix, so a column belongs to this
+        // alias exactly when the returned key differs from the original (a prefix was removed).
+        let pred = Utilities.checkPred alias
+        let ownValues =
+            e.ColumnValues
+            |> Seq.choose (fun (k, v) ->
+                match pred (k, v) with
+                | Some(stripped, value) when stripped <> k -> Some value
+                | _ -> None)
+            |> Seq.toList
+        let hasMatch =
+            match ownValues with
+            | [] -> true   // no alias-qualified columns to judge by: keep the entity
+            | _ -> ownValues |> List.exists (fun v -> not (isNull v))
+        if hasMatch then sub else Unchecked.defaultof<SqlEntity>
+
     /// Maps database entity class to the type provided in generic attribute.
     /// You can define more detailed mapping via MappedColumnAttribute or propertyTypeMapping 
     member x.MapTo<'a>(?propertyTypeMapping : (string * obj) -> obj) =
@@ -588,6 +613,10 @@ type LinkData =
       ForeignTable       : Table
       ForeignKey         : SqlColumnType list
       OuterJoin          : bool
+      // When true (leftOuterJoin), the joined result-set entity is materialised as
+      // null (or None with UseOptionTypes) when there is no matching row, instead of
+      // an entity populated with default values. Only meaningful when OuterJoin = true.
+      IsNullableOuter    : bool
       RelDirection       : RelationshipDirection      }
     with
         member x.Rev() =