# Requirements Archive: v0.5.4 Snowflake-Parity & Registry Publishing

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

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

---

# Requirements: DuckDB Semantic Views v0.5.4

**Defined:** 2026-03-15
**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

## v0.5.4 Requirements

### Cardinality Model

- [x] **CARD-01**: TABLES clause supports `UNIQUE (col, ...)` constraint alongside existing `PRIMARY KEY (col)`
- [x] **CARD-02**: A table can have one PRIMARY KEY and multiple UNIQUE constraints (composite allowed)
- [x] **CARD-03**: Referenced columns in RELATIONSHIPS must match a declared PRIMARY KEY or UNIQUE constraint on the target table -- error at define time if not
- [x] **CARD-04**: Cardinality inferred from constraints: FK column has PK/UNIQUE = one-to-one; FK column bare = many-to-one
- [x] **CARD-05**: Explicit cardinality keywords (ONE TO MANY, MANY TO ONE, ONE TO ONE, MANY TO MANY) removed from parser
- [x] **CARD-06**: ManyToMany variant removed from Cardinality enum
- [x] **CARD-07**: `REFERENCES target` (no column list) resolves to target's PRIMARY KEY; `REFERENCES target(col)` resolves to matching PK or UNIQUE
- [x] **CARD-08**: Fan trap detection continues to work using inferred cardinality values
- [x] **CARD-09**: Composite FK referencing a subset of a composite PK is rejected -- only exact PK/UNIQUE match is valid

### Multi-Version DuckDB

- [x] **DKDB-01**: Extension builds and all tests pass against DuckDB 1.5.x (latest)
- [x] **DKDB-02**: Extension builds and all tests pass against DuckDB 1.4.x (Andium LTS)
- [x] **DKDB-03**: `andium` branch maintained for 1.4.x LTS compatibility
- [x] **DKDB-04**: Build.yml runs CI for both DuckDB versions
- [x] **DKDB-05**: `.duckdb-version` on main tracks latest; `.duckdb-version` on andium tracks LTS
- [x] **DKDB-06**: DuckDB Version Monitor updated to check both latest and LTS releases

### DDL Surface Parity (Snowflake Alignment)

- [x] **DDL-01**: `ALTER SEMANTIC VIEW old_name RENAME TO new_name` renames a semantic view in both in-memory catalog and persistent storage
- [x] **DDL-02**: `ALTER SEMANTIC VIEW IF EXISTS missing_name RENAME TO new_name` is a silent no-op when the view does not exist
- [x] **DDL-03**: `SHOW SEMANTIC DIMENSIONS IN view_name` lists all dimensions for a specific semantic view with columns: semantic_view_name, name, expr, source_table, data_type
- [x] **DDL-04**: `SHOW SEMANTIC DIMENSIONS` (without IN clause) lists dimensions across all semantic views
- [x] **DDL-05**: `SHOW SEMANTIC METRICS [IN view_name]` lists metrics (single-view or cross-view) with same column schema as SHOW DIMENSIONS
- [x] **DDL-06**: `SHOW SEMANTIC FACTS [IN view_name]` lists facts (single-view or cross-view) with columns: semantic_view_name, name, expr, source_table
- [x] **DDL-07**: `SHOW SEMANTIC DIMENSIONS IN view_name FOR METRIC metric_name` returns only dimensions where the join path does not fan out (fan-trap-aware filtering per Snowflake semantics)

### SHOW Command Filtering (Snowflake Parity)

- [x] **DDL-08**: `SHOW SEMANTIC DIMENSIONS LIKE '<pattern>'` filters dimensions by name using case-insensitive SQL wildcard matching (% and _)
- [x] **DDL-09**: `SHOW SEMANTIC METRICS LIKE '<pattern>'` filters metrics by name using case-insensitive SQL wildcard matching
- [x] **DDL-10**: `SHOW SEMANTIC FACTS LIKE '<pattern>'` filters facts by name using case-insensitive SQL wildcard matching
- [x] **DDL-11**: `SHOW SEMANTIC DIMENSIONS STARTS WITH '<prefix>'` filters by case-sensitive name prefix
- [x] **DDL-12**: `SHOW SEMANTIC METRICS STARTS WITH '<prefix>'` filters by case-sensitive name prefix
- [x] **DDL-13**: `SHOW SEMANTIC FACTS STARTS WITH '<prefix>'` filters by case-sensitive name prefix
- [x] **DDL-14**: `SHOW SEMANTIC DIMENSIONS LIMIT <n>` caps output rows
- [x] **DDL-15**: `SHOW SEMANTIC METRICS LIMIT <n>` caps output rows
- [x] **DDL-16**: `SHOW SEMANTIC FACTS LIMIT <n>` caps output rows
- [x] **DDL-17**: `SHOW SEMANTIC DIMENSIONS IN view_name FOR METRIC metric_name` supports LIKE, STARTS WITH, LIMIT
- [x] **DDL-18**: All LIKE/STARTS WITH/LIMIT clauses compose: `SHOW SEMANTIC DIMENSIONS LIKE '%rev%' STARTS WITH 'r' LIMIT 10`
- [x] **DDL-19**: Clauses work with both IN (single-view) and cross-view forms

### Documentation Site

- [x] **DOCS-01**: Sphinx + Shibuya docs configured with `docs/conf.py` and `docs/pyproject.toml`
- [x] **DOCS-02**: GitHub Actions workflow deploys docs to GitHub Pages on push to main
- [x] **DOCS-03**: Site structure includes: getting started, DDL reference, query reference, clause-level pages, examples, architecture overview
- [x] **DOCS-04**: README links to the documentation site

### Community Extension Registry

- [x] **CREG-01**: `description.yml` created with all required fields (name, description, version, language, build, license, maintainers, excluded_platforms, requires_toolchains)
- [x] **CREG-02**: `description.yml` includes `repo.ref` (latest) and `repo.andium` (LTS) commit hashes
- [x] **CREG-03**: `docs.hello_world` example in descriptor works end-to-end
- [ ] **CREG-04**: PR submitted to `duckdb/community-extensions` and build pipeline passes
- [ ] **CREG-05**: Extension installable via `INSTALL semantic_views FROM community`

### Maintainer Documentation

- [x] **MAINT-01**: MAINTAINER.md documents multi-version branching strategy (main vs andium)
- [x] **MAINT-02**: MAINTAINER.md documents CE registry update process (how to update description.yml, cut a release)
- [x] **MAINT-03**: MAINTAINER.md documents how to bump DuckDB version on both branches

## Future Requirements

### Semi-Additive Metrics

- **SEMI-01**: `NON ADDITIVE BY (dim [ASC|DESC], ...)` syntax on metrics
- **SEMI-02**: Expansion generates window function subquery for non-additive dimensions

### PEG Parser Migration

- **PEG-01**: Investigate DuckDB PEG parser as replacement for C++ shim (when PEG becomes default, likely DuckDB 2.0)

## Out of Scope

| Feature | Reason |
|---------|--------|
| Semi-additive metrics (NON ADDITIVE BY) | Expansion pipeline structural change; defer to post-registry-publish stability |
| PEG parser migration | Experimental in DuckDB 1.5; opt-in only; API may change |
| YAML definition format | SQL DDL is sole interface; YAML is future path |
| Many-to-many relationships | Structurally impossible under Snowflake-style inference (referenced side must have PK/UNIQUE) |
| Data-driven cardinality inference | We are a preprocessor; no query execution at define time |
| Backward compat for explicit cardinality keywords | Pre-release; finding the right design |
| WASM support | Parser hooks require C++ shim; incompatible with WASM targets |
| TPC-H worked example | Deferred to future milestone |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| CARD-01 | Phase 33 | Complete |
| CARD-02 | Phase 33 | Complete |
| CARD-03 | Phase 33 | Complete |
| CARD-04 | Phase 33 | Complete |
| CARD-05 | Phase 33 | Complete |
| CARD-06 | Phase 33 | Complete |
| CARD-07 | Phase 33 | Complete |
| CARD-08 | Phase 33 | Complete |
| CARD-09 | Phase 33 | Complete |
| DKDB-01 | Phase 34 | Complete |
| DKDB-02 | Phase 34 | Complete |
| DKDB-03 | Phase 34 | Complete |
| DKDB-04 | Phase 34 | Complete |
| DKDB-05 | Phase 34 | Complete |
| DKDB-06 | Phase 34 | Complete |
| DDL-01 | Phase 34.1 | Complete |
| DDL-02 | Phase 34.1 | Complete |
| DDL-03 | Phase 34.1 | Complete |
| DDL-04 | Phase 34.1 | Complete |
| DDL-05 | Phase 34.1 | Complete |
| DDL-06 | Phase 34.1 | Complete |
| DDL-07 | Phase 34.1 | Complete |
| DDL-08 | Phase 34.1.1 | Complete |
| DDL-09 | Phase 34.1.1 | Complete |
| DDL-10 | Phase 34.1.1 | Complete |
| DDL-11 | Phase 34.1.1 | Complete |
| DDL-12 | Phase 34.1.1 | Complete |
| DDL-13 | Phase 34.1.1 | Complete |
| DDL-14 | Phase 34.1.1 | Complete |
| DDL-15 | Phase 34.1.1 | Complete |
| DDL-16 | Phase 34.1.1 | Complete |
| DDL-17 | Phase 34.1.1 | Complete |
| DDL-18 | Phase 34.1.1 | Complete |
| DDL-19 | Phase 34.1.1 | Complete |
| DOCS-01 | Phase 35 | Complete |
| DOCS-02 | Phase 35 | Complete |
| DOCS-03 | Phase 35 | Complete |
| DOCS-04 | Phase 35 | Complete |
| CREG-01 | Phase 36 | Complete |
| CREG-02 | Phase 36 | Complete |
| CREG-03 | Phase 36 | Complete |
| CREG-04 | Phase 36 | Pending |
| CREG-05 | Phase 36 | Pending |
| MAINT-01 | Phase 36 | Complete |
| MAINT-02 | Phase 36 | Complete |
| MAINT-03 | Phase 36 | Complete |

**Coverage:**
- v0.5.4 requirements: 46 total
- Mapped to phases: 46
- Unmapped: 0

---
*Requirements defined: 2026-03-15*
*Last updated: 2026-03-22 after Phase 34.1.1 planning*
