# Requirements Archive: v0.5.1 DDL Polish

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

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

---

# Requirements: DuckDB Semantic Views

**Defined:** 2026-03-09
**Core Value:** A DuckDB user can define a semantic view once and query it with any combination of dimensions and metrics, without writing GROUP BY or JOIN logic by hand -- the extension handles expansion, DuckDB handles execution.

## v0.5.1 Requirements

Requirements for DDL polish milestone. Each maps to roadmap phases.

### DDL Statements

- [x] **DDL-03**: User can drop a semantic view with `DROP SEMANTIC VIEW name`
- [x] **DDL-04**: User can drop a semantic view idempotently with `DROP SEMANTIC VIEW IF EXISTS name`
- [x] **DDL-05**: User can replace a semantic view with `CREATE OR REPLACE SEMANTIC VIEW name (...)`
- [x] **DDL-06**: User can create a semantic view idempotently with `CREATE SEMANTIC VIEW IF NOT EXISTS name (...)`
- [x] **DDL-07**: User can inspect a semantic view with `DESCRIBE SEMANTIC VIEW name` showing dimensions, metrics, and types
- [x] **DDL-08**: User can list all semantic views with `SHOW SEMANTIC VIEWS`

### Error Reporting

- [x] **ERR-01**: Malformed DDL statements show clause-level error hints (e.g., "Error in DIMENSIONS clause")
- [x] **ERR-02**: Error messages include character position for DuckDB caret rendering
- [x] **ERR-03**: Misspelled keywords and view names show "did you mean" suggestions

### Documentation

- [x] **DOC-01**: README includes DDL syntax reference with worked examples

### Test Coverage

- [x] **TEST-01**: DDL detection is case-insensitive for all 7 forms under random case variation (proptest)
- [x] **TEST-02**: DDL rewrite produces correct function call for all 7 forms with random view names (proptest)
- [x] **TEST-03**: Validation error positions always point to correct byte in original query regardless of whitespace (proptest)
- [x] **TEST-04**: Near-miss detection does not false-positive on normal SQL statements (proptest)
- [x] **TEST-05**: Bracket validation handles nested structures with embedded strings correctly (proptest)
- [x] **TEST-06**: Caret renders at correct position in DuckDB error output through full extension pipeline (Python integration)

## Future Requirements

Deferred to future milestones. Tracked but not in current roadmap.

### Registry

- **REG-01**: Extension published to DuckDB community extension registry (`INSTALL semantic_views FROM community`)

### Demo

- **DEMO-01**: Real-world TPC-H demo notebook

### Extended DDL (Future)

- **DDL-09**: `DESC` as alias for `DESCRIBE SEMANTIC VIEW`
- **DDL-10**: `SHOW SEMANTIC VIEWS LIKE '%pattern%'` filtering
- **DDL-11**: Schema-qualified names (`myschema.myview`)
- **DDL-12**: Row-per-field DESCRIBE format (one row per dimension/metric/table)

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| `ALTER SEMANTIC VIEW` | Not in Snowflake or DuckDB for views. Use `CREATE OR REPLACE` instead. |
| Schema-qualified names | Flat HashMap catalog. Would require fundamental architecture change. |
| `SHOW ... LIKE` filtering | Client-side filtering suffices. Wrap in `SELECT * FROM list_semantic_views() WHERE ...` |
| `DESC` alias | Minor convenience vs. added parser complexity. Add later if requested. |
| ANSI-colored error output | DuckDB error channel is plain text. Colors render as garbage in JDBC/ODBC/Python. |
| `miette`/`ariadne` error crates | Terminal diagnostic renderers incompatible with DuckDB plain-text errors. |
| Full SQL parser (sqlparser/nom/pest) | 7 prefix patterns + clause extraction. Framework adds ~500KB for no benefit. |
| DDL expression validation at define time | Expression validity depends on source table existing. DuckDB validates at query time. |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| DDL-03 | Phase 20 | Complete |
| DDL-04 | Phase 20 | Complete |
| DDL-05 | Phase 20 | Complete |
| DDL-06 | Phase 20 | Complete |
| DDL-07 | Phase 20 | Complete |
| DDL-08 | Phase 20 | Complete |
| ERR-01 | Phase 21 | Complete |
| ERR-02 | Phase 21 | Complete |
| ERR-03 | Phase 21 | Complete |
| DOC-01 | Phase 22 | Complete |
| TEST-01 | Phase 23 | Complete |
| TEST-02 | Phase 23 | Complete |
| TEST-03 | Phase 23 | Complete |
| TEST-04 | Phase 23 | Complete |
| TEST-05 | Phase 23 | Complete |
| TEST-06 | Phase 23 | Complete |

**Coverage:**
- v0.5.1 requirements: 16 total
- Mapped to phases: 16
- Unmapped: 0

---
*Requirements defined: 2026-03-09*
*Last updated: 2026-03-09 after phase 23 planning*
