# Requirements Archive: v0.5 Parser Extension Spike

**Archived:** 2026-03-08
**Status:** SHIPPED

For current requirements, see `.planning/REQUIREMENTS.md`.

---

# Requirements: DuckDB Semantic Views

**Defined:** 2026-03-07
**Core Value:** Prove that native `CREATE SEMANTIC VIEW` DDL syntax is achievable via DuckDB parser extension hooks in a Rust+C++ mixed extension.

## v0.5.0 Requirements

Requirements for the parser extension spike. Each maps to roadmap phases.

### Build System

- [ ] **BUILD-01**: C++ shim compiles via `cc` crate against vendored DuckDB amalgamation header (`duckdb.hpp` v1.4.4)
- [ ] **BUILD-02**: Symbol visibility updated in `build.rs` to export the correct entry point symbol(s) for the chosen ABI strategy
- [x] **BUILD-03**: Extension binary loads successfully via `LOAD` in DuckDB CLI and Python client (`import duckdb; conn.load_extension(...)`) — validates compatibility with Python DuckDB's `-fvisibility=hidden` compilation
- [x] **BUILD-04**: `cargo test` (bundled mode) continues to pass without C++ compilation overhead
- [x] **BUILD-05**: Extension is publishable to DuckDB community extension registry (correct footer, platform binaries, no CMake dependency)

### Entry Point

- [ ] **ENTRY-01**: POC Option A — keep `C_STRUCT` footer, Rust entry initializes normally, then calls a linked C++ function that registers parser hooks using the `duckdb_database` handle
- [ ] **ENTRY-02**: POC Option B — switch to `CPP` footer, C++ entry via `DUCKDB_CPP_EXTENSION_ENTRY`, delegates to Rust init via FFI, Rust C API stubs are initialized
- [ ] **ENTRY-03**: Chosen strategy preserves all existing `semantic_view()` query functionality (existing sqllogictest suite passes)

### Parser Hooks

- [x] **PARSE-01**: `parse_function` registered as a fallback hook — only fires for statements DuckDB's parser cannot handle
- [x] **PARSE-02**: `CREATE SEMANTIC VIEW name (...)` is recognized by the parse function (case-insensitive, handles leading whitespace and trailing semicolons)
- [x] **PARSE-03**: Parse function returns `DISPLAY_ORIGINAL_ERROR` for all non-semantic-view statements (zero overhead for normal SQL)
- [x] **PARSE-04**: Parse function delegates to Rust via FFI — C++ trampoline calls `extern "C"` Rust function
- [x] **PARSE-05**: Rust parse function is panic-safe (`catch_unwind`) and thread-safe (no shared mutable state)

### DDL Execution

- [x] **DDL-01**: `CREATE SEMANTIC VIEW name (tables := [...], dimensions := [...], metrics := [...])` creates a semantic view via parser hook → plan function → existing catalog code
- [x] **DDL-02**: View created via native DDL is queryable via `FROM semantic_view('name', dimensions := [...], metrics := [...])`
- [x] **DDL-03**: Existing function-based DDL (`FROM create_semantic_view(...)`) continues to work alongside native DDL

### Verification

- [x] **VERIFY-01**: `just test-all` passes (Rust unit tests, sqllogictest, DuckLake CI)
- [x] **VERIFY-02**: At least one sqllogictest test exercises the native `CREATE SEMANTIC VIEW` syntax end-to-end

## Future Requirements

Deferred to subsequent milestone after spike validates the approach.

### Extended DDL Surface

- **DDL-F01**: `DROP SEMANTIC VIEW name` via parser hook
- **DDL-F02**: `CREATE OR REPLACE SEMANTIC VIEW` via parser hook
- **DDL-F03**: `CREATE SEMANTIC VIEW IF NOT EXISTS` via parser hook
- **DDL-F04**: `DROP SEMANTIC VIEW IF EXISTS` via parser hook
- **DDL-F05**: `DESCRIBE SEMANTIC VIEW name` via parser hook
- **DDL-F06**: `SHOW SEMANTIC VIEWS` / `LIST SEMANTIC VIEWS` via parser hook

### Parser Quality

- **QUAL-F01**: Error location reporting (`error_location` in parse result) for syntax errors
- **QUAL-F02**: Custom `ParserExtensionInfo` carrying Rust catalog pointer
- **QUAL-F03**: Helpful error messages for malformed `CREATE SEMANTIC VIEW` statements

## Out of Scope

| Feature | Reason |
|---------|--------|
| Native query syntax change (`QUERY SEMANTIC VIEW` or similar) | Separate concern from DDL; existing `semantic_view()` table function works well |
| `parser_override` hook | Only needed for full language replacement (PRQL); `parse_function` fallback is correct for DDL |
| OperatorExtension / stash pattern | Not needed for DDL — direct TableFunction return (Path A) is simpler |
| YAML/file-based DDL | SQL DDL first; YAML is a future path |
| Custom SQL grammar parser | Spike uses statement rewriting (rewrites to existing function-based DDL); custom grammar deferred |
| Windows support | macOS and Linux are primary targets; Windows can follow |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| BUILD-01 | Phase 15 | Pending |
| BUILD-02 | Phase 15 | Pending |
| BUILD-03 | Phase 17 | Complete |
| BUILD-04 | Phase 18 | Complete |
| BUILD-05 | Phase 18 | Complete |
| ENTRY-01 | Phase 15 | Pending |
| ENTRY-02 | Phase 15 | Pending |
| ENTRY-03 | Phase 15 | Pending |
| PARSE-01 | Phase 16 | Complete |
| PARSE-02 | Phase 16 | Complete |
| PARSE-03 | Phase 16 | Complete |
| PARSE-04 | Phase 16 | Complete |
| PARSE-05 | Phase 16 | Complete |
| DDL-01 | Phase 17 | Complete |
| DDL-02 | Phase 17 | Complete |
| DDL-03 | Phase 17 | Complete |
| VERIFY-01 | Phase 18 | Complete |
| VERIFY-02 | Phase 18 | Complete |

**Coverage:**
- v0.5.0 requirements: 18 total
- Mapped to phases: 18
- Unmapped: 0

---
*Requirements defined: 2026-03-07*
*Last updated: 2026-03-08 after gap closure audit (9 checkbox + traceability updates for Phases 16-17)*
