(() =>
+ Parser.Parse("EXPLAIN ESTIMATE FOR INSERT INTO users VALUES (1);"));
+
+ Assert.Contains("supports SELECT", ex.Message);
+ }
+
[Fact]
public void Parse_ComplexExpression()
{
diff --git a/tests/CSharpDB.Tests/PlannerStatisticsTests.cs b/tests/CSharpDB.Tests/PlannerStatisticsTests.cs
index 0a6eb617..1c285f09 100644
--- a/tests/CSharpDB.Tests/PlannerStatisticsTests.cs
+++ b/tests/CSharpDB.Tests/PlannerStatisticsTests.cs
@@ -216,6 +216,52 @@ public async Task FilteredRowEstimate_UsesCompositePrefixStatisticsForCorrelated
Assert.Equal(500, estimatedRows);
}
+ [Fact]
+ public async Task ExplainEstimate_ReportsHistogramHeavyHitterAndCompositePrefixSources()
+ {
+ var ct = TestContext.Current.CancellationToken;
+ await SetupSkewedEqualityTableAsync(ct);
+ await SetupHistogramRangeTableAsync(ct);
+ await SetupCompositePrefixCorrelationTableAsync(ct);
+ await _db.ExecuteAsync("ANALYZE planner_skew", ct);
+ await _db.ExecuteAsync("ANALYZE planner_hist", ct);
+ await _db.ExecuteAsync("ANALYZE planner_corr", ct);
+
+ await using var heavy = await _db.ExecuteAsync(
+ "EXPLAIN ESTIMATE FOR SELECT * FROM planner_skew WHERE hot_code = 1",
+ ct);
+ var heavyRows = await heavy.ToListAsync(ct);
+ Assert.Contains(heavyRows, row => row[4].AsText == "heavy-hitter" && row[7].AsText == "sys.planner_heavy_hitters");
+
+ await using var histogram = await _db.ExecuteAsync(
+ "EXPLAIN ESTIMATE FOR SELECT * FROM planner_hist WHERE value BETWEEN 1 AND 10",
+ ct);
+ var histogramRows = await histogram.ToListAsync(ct);
+ Assert.Contains(histogramRows, row => row[4].AsText == "histogram-range" && row[7].AsText == "sys.planner_histograms");
+
+ await using var composite = await _db.ExecuteAsync(
+ "EXPLAIN ESTIMATE FOR SELECT * FROM planner_corr WHERE region = 'East' AND city = 'EastCity'",
+ ct);
+ var compositeRows = await composite.ToListAsync(ct);
+ Assert.Contains(compositeRows, row => row[4].AsText == "composite-prefix-filter" && row[7].AsText == "sys.planner_index_prefix_stats");
+ }
+
+ [Fact]
+ public async Task ExplainEstimate_ReportsStaleStatsAsIgnored()
+ {
+ var ct = TestContext.Current.CancellationToken;
+ await SetupSkewedEqualityTableAsync(ct);
+ await _db.ExecuteAsync("ANALYZE planner_skew", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_skew VALUES (1001, 1)", ct);
+
+ await using var explain = await _db.ExecuteAsync(
+ "EXPLAIN ESTIMATE FOR SELECT * FROM planner_skew WHERE hot_code = 1",
+ ct);
+ var rows = await explain.ToListAsync(ct);
+
+ Assert.Contains(rows, row => row[4].AsText == "ignored-stale-stats" && row[8].AsText == "stale-ignored");
+ }
+
[Fact]
public async Task FreshColumnStats_NonUniqueJoin_PrefersIndexLookupWhenExpectedMatchesAreLow()
{
diff --git a/tests/CSharpDB.Tests/SqlScriptSplitterTests.cs b/tests/CSharpDB.Tests/SqlScriptSplitterTests.cs
index 42864560..9fb8d790 100644
--- a/tests/CSharpDB.Tests/SqlScriptSplitterTests.cs
+++ b/tests/CSharpDB.Tests/SqlScriptSplitterTests.cs
@@ -96,6 +96,7 @@ public void SplitExecutableStatements_IgnoresTrailingCommentOnlyRemainder()
[Theory]
[InlineData("SELECT * FROM t;", true)]
+ [InlineData("EXPLAIN ESTIMATE FOR SELECT * FROM t;", true)]
[InlineData("INSERT INTO t VALUES (1);", false)]
[InlineData("UPDATE t SET n = 1;", false)]
[InlineData("DELETE FROM t WHERE id = 1;", false)]
diff --git a/tests/CSharpDB.Tests/SystemCatalogTests.cs b/tests/CSharpDB.Tests/SystemCatalogTests.cs
index 3faf52be..a914ab3e 100644
--- a/tests/CSharpDB.Tests/SystemCatalogTests.cs
+++ b/tests/CSharpDB.Tests/SystemCatalogTests.cs
@@ -526,6 +526,115 @@ ORDER BY ordinal_position
Assert.Equal(0L, rows[2][6].AsInteger);
}
+ [Fact]
+ public async Task SystemCatalog_PlannerStats_ExposeHistogramsHeavyHittersAndPrefixes()
+ {
+ var ct = TestContext.Current.CancellationToken;
+
+ await _db.ExecuteAsync("CREATE TABLE planner_public_stats (id INTEGER PRIMARY KEY, region TEXT, city TEXT, score INTEGER)", ct);
+ await _db.ExecuteAsync("CREATE INDEX idx_public_region_city ON planner_public_stats(region, city)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (1, 'East', 'Seattle', 10)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (2, 'East', 'Seattle', 11)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (3, 'East', 'Bellevue', 12)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (4, 'West', 'Portland', 100)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (5, 'West', 'Portland', 101)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (6, 'West', 'Salem', 102)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (7, 'West', 'Salem', 103)", ct);
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (8, 'West', 'Salem', 104)", ct);
+ await _db.ExecuteAsync("ANALYZE planner_public_stats", ct);
+
+ await using (var histogramCount = await _db.ExecuteAsync(
+ """
+ SELECT COUNT(*)
+ FROM sys.planner_histograms
+ WHERE table_name = 'planner_public_stats' AND column_name = 'score' AND is_stale = 0
+ """,
+ ct))
+ {
+ Assert.True(Assert.Single(await histogramCount.ToListAsync(ct))[0].AsInteger > 0);
+ }
+
+ await using (var heavyHitters = await _db.ExecuteAsync(
+ """
+ SELECT value, row_count, frequency_ppm, is_stale
+ FROM sys.planner_heavy_hitters
+ WHERE table_name = 'planner_public_stats' AND column_name = 'region'
+ ORDER BY row_count DESC
+ LIMIT 1
+ """,
+ ct))
+ {
+ var row = Assert.Single(await heavyHitters.ToListAsync(ct));
+ Assert.Equal("West", row[0].AsText);
+ Assert.Equal(5L, row[1].AsInteger);
+ Assert.Equal(625000L, row[2].AsInteger);
+ Assert.Equal(0L, row[3].AsInteger);
+ }
+
+ await using (var prefixStats = await _db.ExecuteAsync(
+ """
+ SELECT prefix_length, prefix_columns, distinct_count, table_row_count, is_stale
+ FROM sys_planner_index_prefix_stats
+ WHERE index_name = 'idx_public_region_city'
+ ORDER BY prefix_length
+ """,
+ ct))
+ {
+ var rows = await prefixStats.ToListAsync(ct);
+ Assert.Equal(2, rows.Count);
+ Assert.Equal(1L, rows[0][0].AsInteger);
+ Assert.Equal("region", rows[0][1].AsText);
+ Assert.Equal(2L, rows[0][2].AsInteger);
+ Assert.Equal(8L, rows[0][3].AsInteger);
+ Assert.Equal(0L, rows[0][4].AsInteger);
+ Assert.Equal(2L, rows[1][0].AsInteger);
+ Assert.Equal("region,city", rows[1][1].AsText);
+ Assert.Equal(4L, rows[1][2].AsInteger);
+ }
+
+ await _db.DisposeAsync();
+ _db = await Database.OpenAsync(_dbPath, ct);
+
+ await using (var persistedCount = await _db.ExecuteAsync(
+ "SELECT COUNT(*) FROM sys.planner_histograms WHERE table_name = 'planner_public_stats'",
+ ct))
+ {
+ Assert.True(Assert.Single(await persistedCount.ToListAsync(ct))[0].AsInteger > 0);
+ }
+
+ await _db.ExecuteAsync("INSERT INTO planner_public_stats VALUES (9, 'West', 'Salem', 105)", ct);
+
+ await using (var staleRows = await _db.ExecuteAsync(
+ """
+ SELECT
+ (SELECT is_stale FROM sys.planner_histograms WHERE table_name = 'planner_public_stats' LIMIT 1),
+ (SELECT is_stale FROM sys.planner_heavy_hitters WHERE table_name = 'planner_public_stats' LIMIT 1),
+ (SELECT is_stale FROM sys.planner_index_prefix_stats WHERE table_name = 'planner_public_stats' LIMIT 1)
+ """,
+ ct))
+ {
+ var row = Assert.Single(await staleRows.ToListAsync(ct));
+ Assert.Equal(1L, row[0].AsInteger);
+ Assert.Equal(1L, row[1].AsInteger);
+ Assert.Equal(1L, row[2].AsInteger);
+ }
+
+ await _db.ExecuteAsync("DROP TABLE planner_public_stats", ct);
+
+ await using var afterDrop = await _db.ExecuteAsync(
+ """
+ SELECT
+ (SELECT COUNT(*) FROM sys.planner_histograms WHERE table_name = 'planner_public_stats'),
+ (SELECT COUNT(*) FROM sys.planner_heavy_hitters WHERE table_name = 'planner_public_stats'),
+ (SELECT COUNT(*) FROM sys.planner_index_prefix_stats WHERE table_name = 'planner_public_stats')
+ """,
+ ct);
+ var afterDropRow = Assert.Single(await afterDrop.ToListAsync(ct));
+ Assert.Equal(0L, afterDropRow[0].AsInteger);
+ Assert.Equal(0L, afterDropRow[1].AsInteger);
+ Assert.Equal(0L, afterDropRow[2].AsInteger);
+ }
+
[Fact]
public async Task SystemCatalog_ColumnStats_BecomeStaleOnWriteAndRollbackRestoresFreshState()
{
diff --git a/www/roadmap-reference.html b/www/roadmap-reference.html
index c1dd0002..a1b5c01a 100644
--- a/www/roadmap-reference.html
+++ b/www/roadmap-reference.html
@@ -337,8 +337,18 @@ Long-Term
| Source-generated collection fast path |
- In progress: GetGeneratedCollectionAsync<T>(...), generated field descriptors/index bindings, analyzer-packaged collection model/codecs, trim/NativeAOT smoke coverage, and a dedicated sample are now in place while broader package ergonomics and remaining generator coverage continue |
- In Progress |
+ Done for the current phase: opt-in generated collection models now provide GetGeneratedCollectionAsync<T>(...), generated field descriptors/index bindings, analyzer-packaged collection model/codecs, generated binary direct-payload encode/decode for supported document graphs, source-generated JSON fallback for unsupported shapes, trim/NativeAOT smoke coverage, and a dedicated sample |
+ Done |
+
+
+ | Generated collection package ergonomics |
+ Streamline NuGet/analyzer packaging, templates, onboarding docs, and generated-collection setup so consumers can adopt the opt-in path with less project wiring |
+ Planned |
+
+
+ | Broader generated collection model coverage |
+ Expand generator support beyond the current scalar, scalar collection, nested scalar, and nested collection-scalar shapes; unsupported shapes currently warn and fall back to source-generated JSON instead of binary direct payloads |
+ Planned |
| Page-level compression |
@@ -352,13 +362,23 @@ Long-Term
| Advanced cost-based query optimizer |
- In progress: phase-2 stats-guided costing is now in place through internal equi-depth histograms, heavy hitters, composite-index prefix distinct-count summaries, skew-aware lookup/filter estimates, correlation-aware composite equality filters/joins, and bounded DP reordering for small inner-join chains; adaptive re-optimization and public histogram inspection remain future work |
- In Progress |
+ Done for the current phase: ANALYZE-driven stats-guided costing now uses internal equi-depth histograms, heavy hitters, composite-index prefix distinct-count summaries, skew-aware lookup/filter estimates, correlation-aware composite equality filters/joins, non-unique lookup costing, hash build-side choice, and bounded DP reordering for small inner-join chains |
+ Done |
+
+
+ | Adaptive query re-optimization |
+ Re-plan or adapt at runtime when observed cardinality diverges materially from persisted statistics, especially after stale stats or parameter-sensitive predicates |
+ Planned |
+
+
+ | Public planner histogram inspection |
+ Expose histogram, heavy-hitter, composite-prefix, and estimate explanation diagnostics through a public surface; current histogram/prefix stats remain internal implementation details |
+ Planned |
| Async I/O batching |
- In progress: WAL frame-chunk writes, chunked checkpoint page copies, shared snapshot/export batching, and reusable B-tree copy utilities now cover the main storage and maintenance write paths; remaining auditing is outside the WAL hot path |
- In Progress |
+ Done for the current phase: WAL frame-chunk writes, chunked checkpoint page copies, shared snapshot/export batching, reusable B-tree copy utilities, and the close-out audit now cover the main storage and maintenance write paths; future work is limited to specialized diagnostics or maintenance-path tuning |
+ Done |
| Low-latency durable writes |
@@ -438,7 +458,7 @@ Current Limitations
| Collections |
- FindByIndexAsync supports declared field-equality lookups; FindByPathAsync and FindByPathRangeAsync support path-based queries on indexed paths; FindAsync remains a full scan for unindexed predicates |
+ FindByIndexAsync supports declared field-equality lookups; FindByPathAsync and FindByPathRangeAsync support path-based queries on indexed paths; FindAsync remains a full scan for unindexed predicates. Generated collections require registered descriptors for existing collection indexes; unsupported generated model shapes warn and use the source-generated JSON fallback instead of binary direct payloads |
| Networking |
@@ -530,7 +550,7 @@ Completed Milestones
Binary direct-payload collection storage with direct hydration and field/path extraction
Collection path indexes: nested scalar, array-element, nested array-object, Guid, temporal, ordered text
Collection path query APIs: FindByPathAsync and FindByPathRangeAsync
- Source-generated typed collection fast path foundations: generated collection models/codecs/field descriptors, trim-safe GetGeneratedCollectionAsync<T>(...), generator diagnostics, NativeAOT trim-smoke validation, and a dedicated sample
+ Source-generated typed collection fast path: generated collection models/codecs/field descriptors, generated binary direct payloads for supported shapes, trim-safe GetGeneratedCollectionAsync<T>(...), generator diagnostics, NativeAOT trim-smoke validation, and a dedicated sample
Full-text search with tokenization, stemming, and relevance ranking
Hybrid storage mode with lazy-resident durable storage and gRPC tunable file-cache
Client-wide BackupAsync / RestoreAsync across direct, HTTP, gRPC, CLI, and Admin
diff --git a/www/roadmap.html b/www/roadmap.html
index a2863c36..5ca9612d 100644
--- a/www/roadmap.html
+++ b/www/roadmap.html
@@ -150,7 +150,7 @@
Source-Generated Collections
Done
-
No-reflection, trim-safe typed collection API via CSharpDB.Generators with GetGeneratedCollectionAsync<T>(), GeneratedCollection<T>, generated field metadata, and NativeAOT-friendly model registration.
+ No-reflection, trim-safe typed collection API via CSharpDB.Generators with GetGeneratedCollectionAsync<T>(), GeneratedCollection<T>, generated field metadata, binary direct payloads for supported shapes, and NativeAOT-friendly model registration.
-
No-reflection, trim-safe typed collection API via CSharpDB.Generators with generated field metadata and NativeAOT-friendly model registration.
+
Current phase is complete: opt-in generated models provide GetGeneratedCollectionAsync<T>, generated descriptors/index bindings, binary direct payloads for supported shapes, JSON fallback for unsupported shapes, and trim/NativeAOT smoke coverage.
+
+
+
Streamline NuGet/analyzer packaging, templates, onboarding docs, and project setup for the opt-in generated collection path.
+
+
+
Expand generator support beyond the current scalar, scalar collection, nested scalar, and nested collection-scalar shapes.