Case Study: DuckDB Table Function API Migration

A Codex GPT-5.5 run with GitHits fixed a DuckDB v1.3.2 table-function migration 34% faster and using 19% fewer tokens than a run without GitHits, by leveraging version-specific source evidence to correctly implement filter_prune semantics. The without-GitHits run produced a syntax-correct patch but missed the optimizer path for filter-only column pruning, demonstrating that compile-correctness is insufficient for behavioral correctness.

Back to blog /blog/ June 3, 2026 · 3 min read Case Study: DuckDB Table Function API Migration A measured Codex run fixing a DuckDB v1.3.2 table-function migration with version-specific source evidence. The fixture is a C++ DuckDB table-function migration. Both runs used Codex GPT-5.5 against the same fixture. The prompt was: Fix web archive scan.cpp so it is source-correct for DuckDB v1.3.2 C++ table-function projection and complex-filter pushdown API. The stale fixture came from older DuckDB table-function examples. The patch had to update web archive scan.cpp for DuckDB v1.3.2 while preserving projection and filter pushdown behavior. A patch could compile and still be wrong if it dropped columns needed only by pushed filters. Case study replay DuckDB API migration model Codex GPT-5.5Fix web archive scan.cpp so it is source-correct for DuckDB v1.3.2 C++ table-function projection and complex-filter pushdown API. Without GitHits - tokens - 0 - time - 0s / 496s - Ready. Click "Watch Replay" to start. - Produced a syntax-checking diff but missed the filter prune path that enables filter-only column pruning. With GitHits - tokens - 0 - time - 0s / 327s - Ready. Click "Watch Replay" to start. - Caught the v1.3.2 callback signature, column t projection mapping, TableFunctionSet include, and filter prune semantics. Result | Run | Time | Tokens | Tools | |---|---|---|---| | With GitHits | 327s | 1.41M | 40 | | Without GitHits | 496s | 1.73M | 48 | The GitHits run was about 34% faster and used about 19% fewer processed tokens. It also found the filter prune path used for filter-only column pruning. The no-GitHits run updated API shapes and passed syntax checks. It missed the path that tells DuckDB how to retain columns required only by pushed filters. Failure Surface The broken fixture mixed several kinds of API drift: - The pushdown complex filter callback signature had changed. - Projection handling needed to account for DuckDB’s column t and projection ids behavior. TableFunctionSet needed the right include path.- Complex filter pushdown had to cooperate with column pruning instead of only erasing filters from a local vector. The no-GitHits run fetched headers, made a sparse checkout, inspected optimizer files, and ran syntax checks. Most of that work was source acquisition and orientation: branch, header, optimizer file, usage site, and version. The GitHits run moved from the fixture into version-specific DuckDB source evidence: table function.hpp for the v1.3.2 callback and init inputs. projection ids usage to understand projection mapping. remove unused columns.cpp to confirm how filter-only columns are preserved. logical get.cpp and pushdown get.cpp to connect the table function API to optimizer behavior. function set.hpp to settle the TableFunctionSet include. That evidence covered both the API shape and the planner behavior. Missed Behavior The fixture contained this warning in the stale code: // Older examples used column ids directly. This is wrong when DuckDB has // produced projection ids for a filtered/projection-pushed scan. That comment points at the right area, but it is incomplete. projection ids explains visible output columns. It does not fully explain columns needed only to evaluate filters that have been pushed into the scan. The no-GitHits result did enough source work to avoid compilation errors. It stopped before the filter-pruning behavior. In this fixture, compile-correct was not enough. The behavior depended on the optimizer path, not only on the table-function header. Evidence Path The required context was DuckDB v1.3.2 source in the files that implement table functions and optimizer pruning: - The new pushdown complex filter shape. - The projection mapping between requested output columns and table function state. - The role of filter prune when filters reference columns that are not otherwise projected. - The include boundary for TableFunctionSet . The no-GitHits run inspected real source too, but spent more of the run getting and locating it. The GitHits run reached the relevant files earlier and followed the planner path far enough to catch the column-pruning edge case.