DuckDB Under the Microscope: What 67 AST Tools Found Inside the Analytical Engine
We benchmarked all 67 prod-code AST tools against duckdb/duckdb: 681,000 lines of modern C++, QueryResult slicing, and catch2 matcher guardrails.
On this page · 4 sections
First published on 2026-09-30. The measurements reported in this article are historical and have not been re-run for this revision. The article reports using duckdb/duckdb at commit a2af0a7bba.
duckdb/duckdb is a high-performance in-process analytical SQL database management system, providing vectorized execution, columnar storage, and seamless zero-copy integration across Python, R, and Rust environments.
Spanning 681,473 lines of modern C++ across 3,273 source files in src/ (with 350,004 declarations indexed monorepo-wide), DuckDB represents a monumental benchmark for compiler-grade tooling. The engine makes extensive use of C++17 templates, multi-tiered query planner abstractions, and vectorized vector pipelines.
We evaluated all 67 prod-code AST tools against duckdb/duckdb (commit a2af0a7bba) executing on remote 32-core LAN nodes, as the article reports. The sections below show selected search, clone, refactoring-preview and validation runs, not a per-tool record, and no laptop CPU measurement is shown.
Semantic Search and Slicing the Query Execution Spine
Executing SQL queries in DuckDB flows from high-level client interfaces down into vectorized chunk operators. Locating foundational execution hubs across thousands of templated headers requires ranking symbols by typed graph centrality.
We queried reciprocal-rank-fusion (RRF) search for ClientContext across 350,004 indexed declarations:
$ prod-code search "ClientContext"
10 hit(s) for `ClientContext` in 4172 ms (350004 declarations, 4971 files; ranked by words and typed graph only; 0 of 350004 declarations embedded so far, the rest in the background)
6. [function] Event::GetClientContext src/include/duckdb/parallel/event.hpp:63
ClientContext &GetClientContext();
attribution [score 0.0152]: lexical: rank 6 (matched client, context)
7. [function] Pipeline::GetClientContext src/include/duckdb/parallel/pipeline.hpp:125
ClientContext &GetClientContext();
attribution [score 0.0149]: lexical: rank 7 (matched client, context)
8. [class] ClientContext extension/json/include/json_functions.hpp:20
class ClientContext;
attribution [score 0.0148]: graph: rank 1 (class 'ClientContext' in-degree 3671 (centrality 5.23))
In 4,172 ms, as reported, the search returned class ClientContext as hit 8 overall and rank 1 on the typed-graph side, with an in-degree of 3,671 and a centrality score of 5.23. The hit itself is the forward declaration class ClientContext; in extension/json/include/json_functions.hpp, and an in-degree alone does not make a class the structural center of the engine.
Correction, 2026-10-27. As published on 2026-09-30, this sentence said graph centrality ranked
ClientContextas the structural center of the engine. The output above places it eighth overall and first only in the graph ranking, the declaration it returned is a forward declaration (json_functions.hppline 20 at the article’s commita2af0a7bba), and the search reports that no declarations were embedded yet. The in-degree and timing stand as reported; the structural-center conclusion is withdrawn.
We executed backward AST program slicing on Connection::Query at src/main/connection.cpp:81:
$ prod-code slice src/main/connection.cpp --line 81 --depth 1
=== src/main/connection.cpp
[method] Connection::Query src/main/connection.cpp:81-83 (the seed)
unique_ptr<QueryResult> Connection::Query(const string &query) {
return context->Query(query, QueryParameters());
}
=== src/include/duckdb/main/query_result.hpp
[class] QueryResult src/include/duckdb/main/query_result.hpp:65-275 (depth 1, used by Connection::Query)
class QueryResult {
public:
DUCKDB_API virtual ~QueryResult();
DUCKDB_API const ResultFormat &Format() const;
DUCKDB_API void Materialize();
DUCKDB_API void Complete();
...
template <class FORMAT = ChunkFormat>
unique_ptr<typename FORMAT::T> Fetch() {
if constexpr (std::is_same<FORMAT, ChunkFormat>::value) {
auto chunk = FetchRaw();
if (!chunk) return nullptr;
chunk->Flatten();
return chunk;
}
}
...
shared_ptr<ClientContext> context;
shared_ptr<BufferedData> buffer;
};
The AST slicer isolated the query submission seed in connection.cpp and followed header dependencies into query_result.hpp; the excerpt above is an abridged view of QueryResult, not its full contract.
Correction, 2026-10-27. As published on 2026-09-30, this section called the excerpt the full data-chunk streaming contract. At duckdb commit
a2af0a7b,QueryResultderives fromBaseQueryResult, its own documentation says thatFetch, likeMaterialize,CollectionandRowCount, materializes the result, and the streaming interface is a separateQueryResultStream<FORMAT>. The excerpt omits the base class and the non-chunkFetchbranch; it is a bounded slice as reported, not the streaming contract.
Structural Invariant Queries and Extension Clones
DuckDB uses typed C++ exception hierarchies to safeguard database invariants. Internal assertion failures throw InternalException, signaling unhandled execution states or optimizer bugs.
We queried throw InternalException($$$) across all repository files using structural AST matching:
$ prod-code structural-search 'throw InternalException($$$)'
2277 match(es) in 693 file(s) (5001 scanned in 18848.71ms)
• benchmark/include/duckdb_benchmark.hpp:48:4 throw InternalException("Unknown profiling option \"%s\"", instance.configuration.profile_info)
└─ [$$$ = "Unknown profiling option \"%s\"", instance.configuration.profile_info]
• extension/core_functions/aggregate/algebraic/avg.cpp:295:3 throw InternalException("Unimplemented average aggregate")
└─ [$$$ = "Unimplemented average aggregate"]
• extension/core_functions/aggregate/distributive/approx_count.cpp:40:3 throw InternalException("ApproxCountDistinct - count must be at most vector size")
└─ [$$$ = "ApproxCountDistinct - count must be at most vector size"]
• extension/core_functions/aggregate/holistic/reservoir_quantile.cpp:39:4 throw InternalException("Memory allocation failure")
└─ [$$$ = "Memory allocation failure"]
In 18,848 ms, the tool scanned 5,001 translation units and indexed all 2,277 internal exception call sites with bound argument expressions.
Running AST subtree duplicate detection reportedly found over 5,500 clone groups, primarily concentrated in third-party parsers and unicode tables. Clone Group #1518 matched 33 parameterized (Type-2) 12-line AST subtrees in third_party/utf8proc/utf8proc_data.cpp:
$ prod-code duplicates --min-lines 12 --group 1518
[Clone Group #1518] 12 lines | 33 occurrences (Type-2 (Parameterized))
• Occurrence 1: third_party/utf8proc/utf8proc_data.cpp:9038-9049
• Occurrence 2: third_party/utf8proc/utf8proc_data.cpp:9050-9061
• Occurrence 3: third_party/utf8proc/utf8proc_data.cpp:9062-9073
• Occurrence 4: third_party/utf8proc/utf8proc_data.cpp:9256-9267
Preview:
│ {UTF8PROC_CATEGORY_LU, 0, UTF8PROC_BIDI_CLASS_L, UTF8PROC_DECOMP_TYPE_FONT, 26, UINT16_MAX, UINT16_MAX, 9560...},
│ {UTF8PROC_CATEGORY_LU, 0, UTF8PROC_BIDI_CLASS_L, UTF8PROC_DECOMP_TYPE_FONT, 27, UINT16_MAX, UINT16_MAX, 9562...},
Detecting these repetitive tables shows where generated data repeats one shape with different values, as the preview’s differing numbers show. It does not compare those values with the Unicode specification.
Correction, 2026-10-27. As published on 2026-09-30, this paragraph said detecting these tables allows automated verification that generated parser assets match upstream Unicode specifications, and the paragraph above called the 33 occurrences identical. Clone detection finds structurally similar code; the group is labelled Type-2 (parameterized) and its rows differ in value, and nothing in it is checked against Unicode data. The verification claim is withdrawn and the occurrences are described as parameterized.
Cross-Class Overload Collisions and Matcher Guardrails
In large C++ codebases, identical method names frequently exist across independent classes. Inverting StringUtil::EndsWith requires ensuring that unrelated classes containing EndsWith-such as Identifier::EndsWith-are not incorrectly captured.
We executed invert-boolean on StringUtil::EndsWith:
$ prod-code invert-boolean --path src/common/string_util.cpp --to DoesNotEndWith "StringUtil::EndsWith"
--- a/src/function/table/read_duckdb.cpp
+++ b/src/function/table/read_duckdb.cpp
@@ -533,7 +533,7 @@
auto table_name = ReplacementScan::GetFullPath(input);
auto lower_name = StringUtil::Lower(table_name);
- if (!StringUtil::EndsWith(lower_name, ".db") && !StringUtil::Contains(lower_name, ".db?") &&
- !StringUtil::EndsWith(lower_name, ".ddb") && !StringUtil::Contains(lower_name, ".ddb?") &&
- !StringUtil::EndsWith(lower_name, ".duckdb") && !StringUtil::Contains(lower_name, ".duckdb?")) {
+ if (StringUtil::DoesNotEndWith(lower_name, ".db") && !StringUtil::Contains(lower_name, ".db?") &&
+ StringUtil::DoesNotEndWith(lower_name, ".ddb") && !StringUtil::Contains(lower_name, ".ddb?") &&
+ StringUtil::DoesNotEndWith(lower_name, ".duckdb") && !StringUtil::Contains(lower_name, ".duckdb?")) {
return nullptr;
}
not rewritten (2 reference(s) that are not a call - a function used as a value keeps its old meaning under its new name; nothing is written while any remains):
third_party/catch/catch.hpp:5035:20 `EndsWith` used as a value
third_party/catch/catch.hpp:5060:40 `EndsWith` used as a value
the analyzer rejects the result:
In included file: expected member name or ';' after declaration specifiers [expected_member_name_or_semi] (src/include/duckdb/common/identifier.hpp:87:18)
nothing was written; pass `apply: true` to make these edits
In the preview shown, the transformation adjusted call sites in read_duckdb.cpp, removing outer ! negations. The output then lists two references in third_party/catch/catch.hpp (lines 5035 and 5060) where EndsWith is used as a value and so was not rewritten, and one analyzer diagnostic, “expected member name or ‘;’ after declaration specifiers”, at src/include/duckdb/common/identifier.hpp:87:18. The transcript is a preview with its diagnostics; no apply attempt and no compilation are shown, so whether a write would have been refused is not established here.
In-Memory C++ Header Pre-Flight Analyzer Diagnostics
Modifying core utility headers in DuckDB triggers recompilation of hundreds of translation units. Testing speculative refactorings locally wastes CPU cycles and clutters build trees with object caches.
prod-code validate checks proposed modifications with clangd in a remote memory overlay before files are touched on disk. What it reports are clangd diagnostics for the edited file, not the result of a compiler build of the translation units that include it.
We submitted src/common/string_util.cpp clean, followed by an injected type error:
$ prod-code validate src/common/string_util.cpp --from src/common/string_util.cpp
src/common/string_util.cpp: 0 error(s), 0 warning(s)
(4 diagnostic(s) the file already had before this edit are not counted)
[prod-code] analysed in 2.68s
$ prod-code validate src/common/string_util.cpp --from /tmp/broken_string_util.cpp
src/common/string_util.cpp: 1 error(s), 0 warning(s)
(4 diagnostic(s) the file already had before this edit are not counted)
error: Use of undeclared identifier 'NonExistentType' [undeclared_var_use] (src/common/string_util.cpp:59:50)
[prod-code] analysed in 2.82s
In 2.82 seconds, as reported, remote clangd flagged the undeclared type identifier in the injected edit; the proposed text was read from a temporary file and the repository file was not changed, which is all the transcript shows about writes. The output does not show which headers clangd parsed for the file, and one caught error does not show that every uncompilable change would be caught.
Correction, 2026-10-27. As published on 2026-09-30, this section said
prod-code validatecompiles proposed modifications, and this paragraph said clangd verified the C++ AST against DuckDB’s full header hierarchy and protected the repository from uncompilable code changes. The output above shows clangd diagnostics for one file, an unchanged run with 0 errors and an injected edit with 1 error, with pre-existing diagnostics left out of the count. The compilation, full-header-hierarchy and protection claims are withdrawn; the diagnostics and timings stand as published.
In large-scale C++ analytical engines where templates, multiple overloads, and macro-heavy test frameworks coexist, automated refactorings cannot succeed through unconstrained lexical replacement; AST transformations must enforce cross-class symbol disambiguation and validate proposed translation units entirely in memory before touching disk.
Cite this article
Alexander Panasenko (2026-09-30). DuckDB Under the Microscope: What 67 AST Tools Found Inside the Analytical Engine. https://prod.codes/blog/duckdb-under-the-microscope-67-ast-tools/