# Requirements Archive: v0.5.5 SHOW/DESCRIBE Alignment & Refactoring

**Archived:** 2026-04-05
**Status:** SHIPPED

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

---

# Requirements: DuckDB Semantic Views

**Defined:** 2026-04-01
**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.5 Requirements

Requirements for v0.5.5: SHOW/DESCRIBE Alignment & Refactoring.

### Refactoring

- [x] **REF-01**: expand.rs split into expand/ module directory (mod.rs + submodules for validation, resolution, facts, fan_trap, role_playing, join_resolver, sql_gen)
- [x] **REF-02**: graph.rs split into graph/ module directory (mod.rs + submodules for relationship, facts, derived_metrics, using, toposort)
- [x] **REF-03**: suggest_closest and replace_word_boundary extracted to util.rs, breaking expand-graph circular dependency
- [x] **REF-04**: ParseError extracted to shared errors.rs, breaking parse-body_parser circular dependency
- [x] **REF-05**: All existing tests pass after refactoring with zero behavior changes

### Metadata Storage

- [x] **META-01**: SemanticViewDefinition stores created_on timestamp (Option String, ISO 8601) set at define time
- [x] **META-02**: SemanticViewDefinition stores database_name (Option String) set at define time
- [x] **META-03**: SemanticViewDefinition stores schema_name (Option String) set at define time
- [x] **META-04**: Fact model gains output_type field (Option String) for data_type in SHOW FACTS
- [x] **META-05**: Old stored JSON without new fields deserializes via serde(default) with no migration

### DESCRIBE Alignment

- [x] **DESC-01**: DESCRIBE SEMANTIC VIEW outputs property-per-row format with 5 columns: object_kind, object_name, parent_entity, property, property_value
- [x] **DESC-02**: TABLE objects emit BASE_TABLE_NAME, PRIMARY_KEY, BASE_TABLE_DATABASE_NAME, BASE_TABLE_SCHEMA_NAME properties
- [x] **DESC-03**: RELATIONSHIP objects emit TABLE, REF_TABLE, FOREIGN_KEY, REF_KEY properties
- [x] **DESC-04**: DIMENSION objects emit TABLE, EXPRESSION, DATA_TYPE properties
- [x] **DESC-05**: FACT objects emit TABLE, EXPRESSION, DATA_TYPE properties
- [x] **DESC-06**: METRIC objects emit TABLE, EXPRESSION, DATA_TYPE properties
- [x] **DESC-07**: DERIVED_METRIC objects emit EXPRESSION, DATA_TYPE properties (no TABLE)

### SHOW Alignment

- [x] **SHOW-01**: SHOW SEMANTIC VIEWS returns 5 columns: created_on, name, kind, database_name, schema_name
- [x] **SHOW-02**: SHOW SEMANTIC DIMENSIONS returns 6 columns: database_name, schema_name, semantic_view_name, table_name, name, data_type
- [x] **SHOW-03**: SHOW SEMANTIC METRICS returns 6 columns: database_name, schema_name, semantic_view_name, table_name, name, data_type
- [x] **SHOW-04**: SHOW SEMANTIC FACTS returns 6 columns: database_name, schema_name, semantic_view_name, table_name, name, data_type
- [x] **SHOW-05**: SHOW SEMANTIC DIMENSIONS FOR METRIC returns 4 columns: table_name, name, data_type, required (BOOLEAN, constant FALSE)
- [x] **SHOW-06**: expr column removed from all SHOW commands
- [x] **SHOW-07**: source_table renamed to table_name in all SHOW commands
- [x] **SHOW-08**: LIKE, STARTS WITH, LIMIT filtering continues to work on all SHOW commands

### Code Quality (Phase 42)

- [x] **TIDY-01**: catalog_insert and catalog_delete use single write lock for check-and-mutate (no TOCTOU race)
- [x] **TIDY-02**: Persistence SQL uses parameterized prepared statements via duckdb_prepare/duckdb_bind_varchar (no string interpolation)
- [x] **TIDY-03**: SemanticViewDefinition has inferred_types() helper expressing the parallel Vec invariant
- [x] **TIDY-04**: Body parser unwrap() calls have safety invariant comments explaining paren-balance guarantee
- [x] **TIDY-05**: sql_gen.rs test fixtures extracted to expand/test_helpers.rs with shared builder functions
- [x] **TIDY-06**: File-backed catalog round-trip verified via sqllogictest (CREATE, restart, SHOW, DROP)
- [x] **TIDY-07**: Transmute layout guard test catches Value/duckdb_value size or alignment mismatches
- [x] **TIDY-08**: suggest_closest property tested (suggestions are always valid names from input set)

## Future Requirements

### DDL Enhancements (deferred)

- **DDL-COMMENT**: User can add COMMENT to semantic views, dimensions, metrics, facts
- **DDL-SYNONYM**: User can define SYNONYMS on dimensions, metrics, facts
- **DDL-TERSE**: SHOW TERSE SEMANTIC VIEWS returns reduced column set

## Out of Scope

| Feature | Reason |
|---------|--------|
| comment/synonyms columns in SHOW output | No DDL support yet; adding NULL placeholders rejected |
| owner/owner_role_type in SHOW VIEWS | DuckDB has no RBAC model |
| access_modifier in DESCRIBE | DuckDB has no access control |
| IN ACCOUNT/IN DATABASE scoping | Single-database extension |
| SHOW TERSE SEMANTIC VIEWS | Parser complexity for marginal value; deferred |
| CUSTOM_INSTRUCTIONS in DESCRIBE | Snowflake Cortex AI specific |
| Cortex Search Service properties | Snowflake specific |
| SHOW COLUMNS command | Redundant with existing SHOW SEMANTIC DIMS/METRICS/FACTS |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| REF-01 | Phase 38 | Complete |
| REF-02 | Phase 38 | Complete |
| REF-03 | Phase 37 | Complete |
| REF-04 | Phase 37 | Complete |
| REF-05 | Phase 38 | Complete |
| META-01 | Phase 39 | Complete |
| META-02 | Phase 39 | Complete |
| META-03 | Phase 39 | Complete |
| META-04 | Phase 39 | Complete |
| META-05 | Phase 39 | Complete |
| DESC-01 | Phase 41 | Complete |
| DESC-02 | Phase 41 | Complete |
| DESC-03 | Phase 41 | Complete |
| DESC-04 | Phase 41 | Complete |
| DESC-05 | Phase 41 | Complete |
| DESC-06 | Phase 41 | Complete |
| DESC-07 | Phase 41 | Complete |
| SHOW-01 | Phase 40 | Complete |
| SHOW-02 | Phase 40 | Complete |
| SHOW-03 | Phase 40 | Complete |
| SHOW-04 | Phase 40 | Complete |
| SHOW-05 | Phase 40 | Complete |
| SHOW-06 | Phase 40 | Complete |
| SHOW-07 | Phase 40 | Complete |
| SHOW-08 | Phase 40 | Complete |
| TIDY-01 | Phase 42 | Complete |
| TIDY-02 | Phase 42 | Complete |
| TIDY-03 | Phase 42 | Complete |
| TIDY-04 | Phase 42 | Complete |
| TIDY-05 | Phase 42 | Complete |
| TIDY-06 | Phase 42 | Complete |
| TIDY-07 | Phase 42 | Complete |
| TIDY-08 | Phase 42 | Complete |

**Coverage:**
- v0.5.5 requirements: 33 total (33 complete)
- Mapped to phases: 33
- Unmapped: 0

---
*Requirements defined: 2026-04-01*
*Last updated: 2026-04-04 after Phase 42 planning*
