---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: semantic_views
excerpt: |
DuckDB Community Extensions
Semantic views -- a declarative layer for dimensions, metrics, and relationships
extension:
name: semantic_views
description: "Semantic views -- a declarative layer for dimensions, metrics, and relationships"
version: 0.17.0
language: Rust
build: cargo
license: MIT
excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads;windows_amd64_rtools;windows_amd64_mingw;linux_amd64_musl;linux_arm64_musl;windows_arm64"
requires_toolchains: "rust;python3"
maintainers:
- anentropic
repo:
github: s-layer/duckdb-semantic-views
ref: a3a5547e516984903508c6d027fbd374175ce723
variegata: 71ea4f11e76c6ad2542bbc77c8669ac491ebc2a4
docs:
hello_world: |
-- Create sample data
CREATE TABLE demo(region VARCHAR, amount DECIMAL(10,2));
INSERT INTO demo VALUES ('US', 100), ('US', 200), ('EU', 150);
-- Define a semantic view
CREATE SEMANTIC VIEW sales AS
TABLES (d AS demo PRIMARY KEY (region))
DIMENSIONS (d.region AS d.region)
METRICS (d.revenue AS SUM(d.amount));
-- Query it
FROM semantic_view('sales', dimensions := ['region'], metrics := ['revenue']);
extended_description: |
Semantic views let you define dimensions, metrics, joins, and filters once,
then query any combination. The extension handles GROUP BY, JOIN, and filter
composition automatically. Supports multi-table joins with PK/FK relationships,
fan trap detection, role-playing dimensions, derived metrics, and FACTS.
Documentation: https://s-layer.github.io/duckdb-semantic-views/
extension_star_count: 20
extension_star_count_pretty: 20
extension_download_count: 1796
extension_download_count_pretty: 1.8k
image: '/images/community_extensions/social_preview/preview_community_extension_semantic_views.png'
layout: community_extension_doc
---
### Compatibility Matrix
This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.
| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ❌ | ✅ | ✅ | ✅ |
| Linux ARM64 | ❌ | ❌ | ✅ | ✅ | ✅ |
| macOS AMD64 | ❌ | ❌ | ✅ | ✅ | ❌ |
| macOS ARM64 | ❌ | ❌ | ✅ | ✅ | ✅ |
| Windows AMD64 | ❌ | ❌ | ✅ | ✅ | ✅ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ❌ |
### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```
{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}
{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions
| function_name | function_type | description | comment | examples |
|-------------------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| __sv_check_create | table | Internal helper behind CREATE SEMANTIC VIEW: checks that every member of the definition binds. Use that statement instead; this function is not for direct use. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | |
| __sv_compute_create_from_yaml | table | Internal helper behind CREATE SEMANTIC VIEW ... FROM YAML FILE. Use that statement instead; this function is not for direct use. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | |
| describe_semantic_view | table | Backs DESCRIBE SEMANTIC VIEW: returns a semantic view's definition as one row per property of each table, relationship, fact, dimension, metric and materialization. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [DESCRIBE SEMANTIC VIEW sales;] |
| explain_semantic_view | table | Shows how semantic_view() would answer the same arguments: the generated SQL, the materialization routing decision and the DuckDB query plan, as rows of text, without running the data query. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SELECT * FROM explain_semantic_view('sales', dimensions := ['region'], metrics := ['revenue']);] |
| get_ddl | scalar | Returns the CREATE OR REPLACE SEMANTIC VIEW statement that recreates a stored semantic view. object_type must be 'SEMANTIC_VIEW'; pass true as the optional third argument (use_fully_qualified_names) to schema-qualify the view name in the output. | NULL | [SELECT GET_DDL('SEMANTIC_VIEW', 'sales');, SELECT GET_DDL('SEMANTIC_VIEW', 'sales', true);] |
| list_semantic_views | table | Backs SHOW SEMANTIC VIEWS: lists every registered semantic view with its creation time, database, schema and comment. Use that statement rather than calling this directly; it works as a subquery too. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC VIEWS;, SELECT GET_DDL('SEMANTIC_VIEW', '"' \|\| replace(schema_name, '"', '""') \|\| '"."' \|\| replace(name, '"', '""') \|\| '"') FROM (SHOW SEMANTIC VIEWS);] |
| list_terse_semantic_views | table | Backs SHOW TERSE SEMANTIC VIEWS: lists every registered semantic view without the comment column. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW TERSE SEMANTIC VIEWS;] |
| read_yaml_from_semantic_view | scalar | Returns a stored semantic view's definition as YAML, suitable for re-import with CREATE SEMANTIC VIEW ... FROM YAML. | NULL | [SELECT READ_YAML_FROM_SEMANTIC_VIEW('sales');] |
| semantic_view | table | Queries a semantic view: returns the requested dimensions, metrics and/or facts, generating the joins and GROUP BY from the view definition. Pass at least one of dimensions, metrics or facts; an item may name its column ('region AS r'). where_clause filters rows before aggregation, and refers to the values of params (e.g. row('EU')) as $1, $2, ...; column_order (e.g. ['metrics', 'dimensions']) sets the order of the columns. The SEMANTIC_VIEW(...) construct is the same query written as SQL. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SELECT * FROM semantic_view('sales', dimensions := ['region'], metrics := ['revenue']);] |
| show_columns_in_semantic_view | table | Backs SHOW COLUMNS IN SEMANTIC VIEW: lists a semantic view's queryable dimensions, facts and metrics with their kind and expression (data_type is the declared type, empty for views created since v0.10.0). Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW COLUMNS IN SEMANTIC VIEW sales;] |
| show_semantic_dimensions | table | Backs SHOW SEMANTIC DIMENSIONS IN : lists the dimensions of one semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC DIMENSIONS IN sales;] |
| show_semantic_dimensions_all | table | Backs SHOW SEMANTIC DIMENSIONS without IN: lists the dimensions of every semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC DIMENSIONS;] |
| show_semantic_dimensions_for_metric | table | Backs SHOW SEMANTIC DIMENSIONS IN FOR METRIC : lists the dimensions that can be combined with a metric without a fan trap, and which ones a window metric requires. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC DIMENSIONS IN sales FOR METRIC revenue;] |
| show_semantic_facts | table | Backs SHOW SEMANTIC FACTS IN : lists the facts of one semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC FACTS IN sales;] |
| show_semantic_facts_all | table | Backs SHOW SEMANTIC FACTS without IN: lists the facts of every semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC FACTS;] |
| show_semantic_materializations | table | Backs SHOW SEMANTIC MATERIALIZATIONS IN : lists the materializations declared in one semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC MATERIALIZATIONS IN sales;] |
| show_semantic_materializations_all | table | Backs SHOW SEMANTIC MATERIALIZATIONS without IN: lists the materializations of every semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC MATERIALIZATIONS;] |
| show_semantic_metrics | table | Backs SHOW SEMANTIC METRICS IN : lists the metrics of one semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC METRICS IN sales;] |
| show_semantic_metrics_all | table | Backs SHOW SEMANTIC METRICS without IN: lists the metrics of every semantic view. Use that statement rather than calling this directly. The search_path parameter is reserved (kept so views stored by earlier releases still bind); do not pass it. | NULL | [SHOW SEMANTIC METRICS;] |
### Overloaded Functions
This extension does not add any function overloads.
### Added Types
This extension does not add any types.
### Added Settings
| name | description | input_type | scope | aliases | typed_value |
|---------------------------|---------------------------------------------------------|------------|--------|---------|-------------------------|
| active_grammar_extensions | The grammar extensions used by the parser. | VARCHAR[] | LOCAL | [] | [shell, semantic_views] |
| temp_directory | Set the directory to which temporary files are written. | VARCHAR | GLOBAL | [] | post.db.tmp |