Add IncludeGraph support for full object graph bulk insert

Co-authored-by: PhenX <42170+PhenX@users.noreply.github.com>

Author: Copilot

README.md

@@ -115,6 +115,29 @@ await dbContext.ExecuteBulkInsertAsync(entities, o =>
 await dbContext.ExecuteBulkInsertReturnEntitiesAsync(entities);
 ```
 
+### Insert with navigation properties (Graph Insert)
+
+Insert entities with their related navigation properties:
+
+```csharp
+var blogs = new List<Blog>
+{
+    new Blog
+    {
+        Name = "Blog 1",
+        Posts = new List<Post>
+        {
+            new Post { Title = "Post 1" },
+            new Post { Title = "Post 2" }
+        }
+    }
+};
+
+await dbContext.ExecuteBulkInsertAsync(blogs, o => o.IncludeGraph = true);
+```
+
+See [Graph Insert documentation](https://phenx.github.io/PhenX.EntityFrameworkCore.BulkInsert/graph-insert.html) for details.
+
 ### Conflict resolution / merge / upsert
 
 Conflict resolution works by specifying columns that should be used to detect conflicts and the action to take when
@@ -152,7 +175,7 @@ await dbContext.ExecuteBulkInsertAsync(entities, onConflict: new OnConflictOptio
 
 ## Roadmap
 
-- [ ] [Add support for navigation properties](https://github.com/PhenX/PhenX.EntityFrameworkCore.BulkInsert/issues/2)
+- [x] [Add support for navigation properties](https://github.com/PhenX/PhenX.EntityFrameworkCore.BulkInsert/issues/2)
 - [x] [Add support for complex types](https://github.com/PhenX/PhenX.EntityFrameworkCore.BulkInsert/issues/3)
 - [x] Add support for owned types
 - [ ] Add support for shadow properties

docs/documentation.md

@@ -204,3 +204,36 @@ Enable streaming bulk copy for SQL Server
 * Default: `unset` (PostgreSQL only)
 
 Custom PostgreSQL type providers for handling specific data types.
+
+### IncludeGraph
+
+* Type: `bool`
+* Default: `false`
+
+When enabled, recursively inserts all reachable entities via navigation properties.
+This includes one-to-one, one-to-many, many-to-one, and many-to-many relationships.
+
+See [Graph Insert documentation](./graph-insert.md) for details.
+
+### MaxGraphDepth
+
+* Type: `int`
+* Default: `0` (unlimited)
+
+Maximum depth for graph traversal when `IncludeGraph` is enabled.
+Use 0 for unlimited depth.
+
+### IncludeNavigations
+
+* Type: `HashSet<string>?`
+* Default: `null` (all navigations)
+
+Navigation properties to explicitly include when `IncludeGraph` is enabled.
+If empty and `IncludeGraph` is true, all navigation properties are included.
+
+### ExcludeNavigations
+
+* Type: `HashSet<string>?`
+* Default: `null` (none)
+
+Navigation properties to explicitly exclude when `IncludeGraph` is enabled.

docs/graph-insert.md

@@ -0,0 +1,132 @@
+# Graph Insert (Navigation Properties)
+
+This library supports bulk inserting entire object graphs, including entities with their related navigation properties.
+
+## Enabling Graph Insert
+
+```csharp
+await dbContext.ExecuteBulkInsertAsync(blogs, options =>
+{
+    options.IncludeGraph = true;
+});
+```
+
+## How It Works
+
+1. The library traverses all reachable entities via navigation properties
+2. Entities are sorted in topological order (parents before children) to respect foreign key constraints
+3. Each entity type is bulk inserted in dependency order
+4. Generated IDs (identity columns) are propagated to foreign key properties
+5. Many-to-many join tables are populated automatically
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `IncludeGraph` | `false` | Enable graph traversal |
+| `MaxGraphDepth` | `0` (unlimited) | Maximum depth to traverse. Use 0 for unlimited. |
+| `IncludeNavigations` | `null` (all) | Specific navigation property names to include |
+| `ExcludeNavigations` | `null` (none) | Navigation property names to exclude |
+
+## Supported Relationship Types
+
+- ✅ One-to-Many (e.g., Blog → Posts)
+- ✅ Many-to-One (e.g., Post → Blog)
+- ✅ One-to-One (e.g., Blog → BlogSettings)
+- ✅ Many-to-Many with join table (e.g., Post ↔ Tags)
+- ✅ Self-referencing/Hierarchies (e.g., Category → Parent/Children)
+
+## Performance Considerations
+
+- Graph insert is inherently slower than flat insert due to FK propagation overhead
+- For entities with identity columns, the library uses `ExecuteBulkInsertReturnEntities` internally to retrieve generated IDs
+- Consider using client-generated keys (GUIDs with `ValueGeneratedNever()`) to avoid ID propagation overhead
+- Use `MaxGraphDepth` to limit traversal for large/deep graphs
+- Use `IncludeNavigations` or `ExcludeNavigations` to reduce the scope of insertions
+
+## Example
+
+### One-to-Many Relationship
+
+```csharp
+var blog = new Blog
+{
+    Name = "My Blog",
+    Posts = new List<Post>
+    {
+        new Post { Title = "First Post" },
+        new Post { Title = "Second Post" }
+    }
+};
+
+await dbContext.ExecuteBulkInsertAsync(new[] { blog }, o => o.IncludeGraph = true);
+
+// After insert:
+// - blog.Id is populated
+// - blog.Posts[0].BlogId == blog.Id
+// - blog.Posts[1].BlogId == blog.Id
+```
+
+### One-to-One Relationship
+
+```csharp
+var blog = new Blog
+{
+    Name = "My Blog",
+    Settings = new BlogSettings { EnableComments = true }
+};
+
+await dbContext.ExecuteBulkInsertAsync(new[] { blog }, o => o.IncludeGraph = true);
+
+// After insert:
+// - blog.Id is populated
+// - blog.Settings.BlogId == blog.Id
+```
+
+### Selective Navigation Inclusion
+
+```csharp
+var blog = new Blog
+{
+    Name = "My Blog",
+    Posts = new List<Post> { new Post { Title = "Post" } },
+    Settings = new BlogSettings { EnableComments = true }
+};
+
+// Only insert Posts, not Settings
+await dbContext.ExecuteBulkInsertAsync(new[] { blog }, o =>
+{
+    o.IncludeGraph = true;
+    o.IncludeNavigations = new HashSet<string> { "Posts" };
+});
+```
+
+### Limiting Graph Depth
+
+```csharp
+var blog = new Blog
+{
+    Name = "My Blog",
+    Posts = new List<Post>
+    {
+        new Post
+        {
+            Title = "Post",
+            Tags = new List<Tag> { new Tag { Name = "EF Core" } }  // Won't be inserted
+        }
+    }
+};
+
+// MaxGraphDepth = 1 means only Blog and direct children (Posts)
+await dbContext.ExecuteBulkInsertAsync(new[] { blog }, o =>
+{
+    o.IncludeGraph = true;
+    o.MaxGraphDepth = 1;
+});
+```
+
+## Limitations
+
+- **Shadow foreign keys**: Currently not supported. Add a CLR property for foreign keys.
+- **Circular references**: Handled gracefully by tracking visited entities, but may result in incomplete graphs.
+- **OnConflict/Upsert**: Not currently supported with `IncludeGraph = true`.

docs/limitations.md

@@ -2,7 +2,7 @@
 
 For now this library does not support the following features:
 
-* **Navigation properties**: The library does not support inserting entities with navigation properties. You can only insert simple entities without any relationships.
+* **Navigation properties**: ✅ Supported via the `IncludeGraph` option (see [Graph Insert documentation](./graph-insert.md)).
 * **Change tracking**: The library does not track changes to the entities being inserted. This means that you cannot use the `DbContext.ChangeTracker` to track changes to the entities after they have been inserted.
 * **Inheritance**: The library does not support inserting entities with inheritance (TPT, TPH, TPC). You can only insert entities of a single type.
 

src/PhenX.EntityFrameworkCore.BulkInsert/Abstractions/IBulkInsertProvider.cs

@@ -39,6 +39,12 @@ internal Task BulkInsert<T>(
 
     SqlDialectBuilder SqlDialect { get; }
 
+    /// <summary>
+    /// Returns whether this provider supports returning generated IDs efficiently.
+    /// Required for IncludeGraph when entities have identity columns.
+    /// </summary>
+    bool SupportsOutputInsertedIds { get; }
+
     /// <summary>
     /// Make the default options for the provider, can be a subclass of <see cref="BulkInsertOptions"/>.
     /// </summary>

src/PhenX.EntityFrameworkCore.BulkInsert/BulkInsertProviderUntyped.cs

@@ -15,6 +15,12 @@ internal abstract class BulkInsertProviderUntyped<TDialect, TOptions> : IBulkIns
 
     SqlDialectBuilder IBulkInsertProvider.SqlDialect => SqlDialect;
 
+    /// <summary>
+    /// Returns whether this provider supports returning generated IDs efficiently.
+    /// Default implementation returns true for all providers.
+    /// </summary>
+    public virtual bool SupportsOutputInsertedIds => true;
+
     BulkInsertOptions IBulkInsertProvider.CreateDefaultOptions() => CreateDefaultOptions();
 
     /// <summary>

src/PhenX.EntityFrameworkCore.BulkInsert/Extensions/PublicExtensions.DbSet.cs

@@ -1,5 +1,6 @@
 using Microsoft.EntityFrameworkCore;
 
+using PhenX.EntityFrameworkCore.BulkInsert.Graph;
 using PhenX.EntityFrameworkCore.BulkInsert.Options;
 
 namespace PhenX.EntityFrameworkCore.BulkInsert.Extensions;
@@ -157,6 +158,13 @@ public static async Task ExecuteBulkInsertAsync<T, TOptions>(
     {
         var (provider, context, options) = InitProvider(dbSet, configure);
 
+        if (options.IncludeGraph)
+        {
+            var orchestrator = new GraphBulkInsertOrchestrator();
+            await orchestrator.InsertGraphAsync(context, entities, options, provider, cancellationToken);
+            return;
+        }
+
         await provider.BulkInsert(false, context, dbSet.GetDbContext().GetTableInfo<T>(), entities, options, onConflict,
             cancellationToken);
     }
@@ -204,6 +212,14 @@ public static void ExecuteBulkInsert<T, TOptions>(
     {
         var (provider, context, options) = InitProvider(dbSet, configure);
 
+        if (options.IncludeGraph)
+        {
+            var orchestrator = new GraphBulkInsertOrchestrator();
+            orchestrator.InsertGraphAsync(context, entities, options, provider, CancellationToken.None)
+                .GetAwaiter().GetResult();
+            return;
+        }
+
         provider.BulkInsert(true, context, dbSet.GetDbContext().GetTableInfo<T>(), entities, options, onConflict)
             .GetAwaiter().GetResult();
     }