batch readme guidelines

Author: MPCoreDeveloper

docs/graphrag/GRAPHRAG_PROPOSAL_ANALYSIS.md

@@ -221,6 +221,19 @@ if (column.Type == DataType.RowRef)
 
 ---
 
+### L1 Storage: Bulk Edge Insert
+
+LLM-based ingestion can generate large bursts of edges. To avoid per-edge WAL/B-Tree overhead,
+use the existing batch insert APIs on the edge table:
+
+- `Database.InsertBatch` / `InsertBatchAsync` for SQL-free batch ingestion.
+- `ExecuteBatchSQL` for batched INSERT statements.
+
+These paths execute a single storage transaction and bulk index updates, making edge ingestion
+throughput bounded by serialization rather than transaction overhead.
+
+---
+
 ### Phase 2: Graph Traversal Executor (3-4 weeks)
 
 **Goal:** Execute queries like: `SELECT * FROM articles WHERE article_id IN (graph_traverse(start_id, 'references', 2))`

docs/graphrag/README.md

@@ -70,6 +70,42 @@ SELECT GRAPH_TRAVERSE(1, 'nextId', 5, 1)  -- DFS from node 1
 
 ---
 
+## Bulk Edge Ingestion
+
+GraphRAG ingestion workloads (LLM extraction) should batch edges to avoid per-edge WAL/BTREE overhead.
+Use the existing batch insert APIs on the edge table so the storage engine performs a single transaction
+and index update sequence.
+
+### Recommended API
+
+```csharp
+// Edge table schema: (SourceId, TargetId, Relationship)
+var edges = new List<Dictionary<string, object>>
+{
+    new()
+    {
+        ["SourceId"] = 1L,
+        ["TargetId"] = 2L,
+        ["Relationship"] = "calls"
+    },
+    new()
+    {
+        ["SourceId"] = 1L,
+        ["TargetId"] = 3L,
+        ["Relationship"] = "uses"
+    }
+};
+
+database.InsertBatch("GraphEdges", edges);
+```
+
+### Notes
+- `InsertBatch` and `InsertBatchAsync` execute a single engine transaction.
+- For SQL pipelines, prefer `ExecuteBatchSQL` with batched INSERT statements.
+- Follow bulk inserts with `Flush()` and `ForceSave()` when persistence is required.
+
+---
+
 ## Features
 
 ### ✅ Traversal Algorithms