ALTER SEMANTIC VIEW¶

Modifies an existing semantic view. Supports renaming and setting or removing the view-level comment. The view definition (tables, relationships, dimensions, metrics, facts) is preserved.

Syntax¶

ALTER SEMANTIC VIEW [ IF EXISTS ] <name> RENAME TO <new_name>

ALTER SEMANTIC VIEW [ IF EXISTS ] <name> SET COMMENT = '<text>'

ALTER SEMANTIC VIEW [ IF EXISTS ] <name> UNSET COMMENT

Statement Variants¶

ALTER SEMANTIC VIEW <name> RENAME TO <new_name>: Renames the semantic view from <name> to <new_name>. Returns an error if <name> does not exist or if <new_name> already exists.
ALTER SEMANTIC VIEW IF EXISTS <name> RENAME TO <new_name>: Renames the semantic view if it exists. If <name> does not exist, the statement succeeds silently without modifying anything. Returns an error if <new_name> already exists.
ALTER SEMANTIC VIEW <name> SET COMMENT = '<text>': Sets the view-level comment on the semantic view. Replaces any existing comment. Returns an error if the view does not exist.
ALTER SEMANTIC VIEW IF EXISTS <name> SET COMMENT = '<text>': Sets the view-level comment if the view exists. If the view does not exist, the statement succeeds silently.
ALTER SEMANTIC VIEW <name> UNSET COMMENT: Removes the view-level comment from the semantic view. Returns an error if the view does not exist.
ALTER SEMANTIC VIEW IF EXISTS <name> UNSET COMMENT: Removes the view-level comment if the view exists. If the view does not exist, the statement succeeds silently.

Note

ALTER participates in your surrounding transaction (BEGIN ... ROLLBACK restores the previous name and comment). The non-IF EXISTS forms raise semantic view '<name>' was concurrently dropped if another process drops the view at the same time, instead of silently succeeding. IF EXISTS keeps its silent-no-op behaviour. See Transactional DDL and Known Limitations.

Note

Requires a writable database. On a read-only database this statement fails with DuckDB’s standard Cannot execute statement of type "..." which is attached in read-only mode! error. See Read-Only Databases.

Parameters¶

<name>: The name of the semantic view to modify.
<new_name>: The new name for the semantic view (RENAME TO only). Must not match the name of an existing semantic view.
<text>: The comment text (SET COMMENT only). Must be enclosed in single quotes. Use '' to escape single quotes within the text.

Output Columns¶

RENAME TO returns a single row with 2 columns:

Column	Type	Description
`old_name`	VARCHAR	The original semantic view name before the rename.
`new_name`	VARCHAR	The new semantic view name after the rename.

SET COMMENT and UNSET COMMENT return a single row with 2 columns:

Column	Type	Description
`name`	VARCHAR	The semantic view name.
`status`	VARCHAR	The operation result: `comment set` or `comment unset`.

Examples¶

Rename a semantic view:

ALTER SEMANTIC VIEW sales_view RENAME TO revenue_view;

After the rename, queries must use the new name:

-- This works
SELECT * FROM semantic_view('revenue_view',
    dimensions := ['region'],
    metrics := ['total_amount']
);

-- This fails: "semantic view 'sales_view' does not exist"
SELECT * FROM semantic_view('sales_view',
    dimensions := ['region'],
    metrics := ['total_amount']
);

Rename with IF EXISTS (safe no-op):

-- Succeeds silently if 'old_reports' does not exist
ALTER SEMANTIC VIEW IF EXISTS old_reports RENAME TO new_reports;

Set a view-level comment:

ALTER SEMANTIC VIEW sales SET COMMENT = 'Revenue analytics for North America';

┌───────┬─────────────┐
│ name  │ status      │
├───────┼─────────────┤
│ sales │ comment set │
└───────┴─────────────┘

The comment appears in SHOW SEMANTIC VIEWS and DESCRIBE SEMANTIC VIEW.

Remove a view-level comment:

ALTER SEMANTIC VIEW sales UNSET COMMENT;

┌───────┬───────────────┐
│ name  │ status        │
├───────┼───────────────┤
│ sales │ comment unset │
└───────┴───────────────┘

Error: target name already exists:

-- Assuming both 'sales' and 'inventory' exist
ALTER SEMANTIC VIEW sales RENAME TO inventory;

Error: semantic view 'inventory' already exists

The statement is case-insensitive:

alter semantic view sales_view rename to revenue_view;