Mutates an existing semantic context: updates its metadata, or adds and drops its tables, expressions, example queries, sample questions, and informational virtual key constraints.
ALTER SEMANTIC CONTEXT <name> SET (TITLE='...', DESCRIPTION='...', INSTRUCTIONS='...')
ALTER SEMANTIC CONTEXT <name> ADD TABLE <zone.schema.table> [DESCRIPTION '...']
ALTER SEMANTIC CONTEXT <name> DROP TABLE <zone.schema.table>
ALTER SEMANTIC CONTEXT <name> ADD EXPRESSION <expr_name> AS '<sql>' [DESCRIPTION '...']
ALTER SEMANTIC CONTEXT <name> DROP EXPRESSION <expr_name>
ALTER SEMANTIC CONTEXT <name> ADD QUERY '<title>' AS '<sql>' [QUESTION '...']
ALTER SEMANTIC CONTEXT <name> DROP QUERY '<title>'
ALTER SEMANTIC CONTEXT <name> ADD QUESTION '<text>'
ALTER SEMANTIC CONTEXT <name> DROP QUESTION '<text>'
ALTER SEMANTIC CONTEXT <name> ADD PRIMARY KEY (<col>, ...) ON <zone.schema.table>
ALTER SEMANTIC CONTEXT <name> ADD FOREIGN KEY (<col>, ...) ON <zone.schema.table>
REFERENCES <zone.schema.table> (<col>, ...)
ALTER SEMANTIC CONTEXT <name> ADD UNIQUE (<col>, ...) ON <zone.schema.table>
ALTER SEMANTIC CONTEXT <name> DROP CONSTRAINT (<col>, ...) ON <zone.schema.table>## Overview ALTER SEMANTIC CONTEXT mutates an existing semantic context. Every change to a context after creation goes through this statement: revising its metadata, managing the tables in its data scope, curating its reusable expressions and trusted example queries, editing its starter sample questions, and declaring or removing informational virtual key constraints. The context is always addressed by its machine name, matched case-insensitively. The SQL surface speaks names; the control plane resolves the name to the stored id, then resolves each child (table, expression, query, question, constraint) by its natural key before applying the change. If the named context does not exist, the statement raises a clear not-found error. Only the control plane writes the underlying store, so every form of this statement is served through the control plane API. ## Action Forms ### SET Updates the context metadata: TITLE, DESCRIPTION, INSTRUCTIONS. Only the fields named in SET are changed; omitted fields keep their current values. SET never touches tables, expressions, queries, questions, or constraints. ### ADD TABLE / DROP TABLE Manages the data scope. ADD TABLE pins a qualified table or view (with an optional per-table DESCRIPTION); DROP TABLE unpins it by qualified name. The qualified name is split into its trailing catalog/zone, schema, and table segments and stored as the raw qualified string. Pinning and unpinning only manage membership in this context; the physical table is never read or modified. ### ADD EXPRESSION / DROP EXPRESSION Curates named, reusable SQL expressions (measures). ADD EXPRESSION registers a measure under a name unique within the context, with the SQL body as a string literal and an optional DESCRIPTION. DROP EXPRESSION removes it by name. Grounding tools return these so an assistant reuses trusted definitions. ### ADD QUERY / DROP QUERY Curates trusted example queries. ADD QUERY registers a query under a title (its natural key), with the SQL body as a string literal and an optional QUESTION giving the natural-language phrasing it answers. DROP QUERY removes it by title. ### ADD QUESTION / DROP QUESTION Edits the list of starter sample questions. ADD QUESTION appends a question string; DROP QUESTION removes the matching string. These are implemented by reading the context, mutating its sample-questions list, and writing it back, so the order of the remaining questions is preserved. ### ADD PRIMARY KEY / FOREIGN KEY / UNIQUE, DROP CONSTRAINT Declares and removes informational virtual key constraints. A primary key or uniqueness constraint lists columns on one table; a foreign key lists local columns on one table and positionally aligned referenced columns on another via REFERENCES. DROP CONSTRAINT removes the constraint on a table whose column list matches. Virtual constraints are expressed under the context for convenience but stored at the catalog level, keyed by table rather than by context. They are shared: declaring one makes it visible to every context that pins the same table, and dropping one removes it everywhere. They are informational only. ## Behavior - The context is resolved by name case-insensitively. A name that resolves to no context raises a not-found error; the statement makes no change. - SET changes only the metadata fields it names; all other context content (tables, expressions, queries, questions, constraints) is untouched. - DROP TABLE, DROP EXPRESSION, DROP QUERY, DROP QUESTION, and DROP CONSTRAINT each resolve the child by its natural key (qualified table name, expression name, query title, question text, or table-plus-column-list) and remove that child only. - Virtual constraints declared by ADD PRIMARY KEY / FOREIGN KEY / UNIQUE are informational metadata. They are never enforced, never validated against the data, and never alter the physical Delta or Iceberg table. They signal a relationship that grounding and join detection may trust; they do not change query results or table state. - Virtual constraints are stored catalog-level (per table), not per context. ADD CONSTRAINT and DROP CONSTRAINT therefore affect every context that pins the same table, even though the statement is written under one context name. The context name is still resolved and validated first, so altering a non-existent context errors cleanly before any constraint change is attempted. - Each action returns a single-row status batch summarising the change. ## Access Control Managing a semantic context is a metastore-level curation operation served by the control plane. Altering a context changes only grounding metadata and informational constraints; it grants no data access and changes no physical table. The pinned tables stay governed by their existing table-level privileges. ## Compatibility ALTER SEMANTIC CONTEXT is a DeltaForge extension. It has no ANSI SQL equivalent. The virtual key forms borrow PRIMARY KEY, FOREIGN KEY, UNIQUE, and REFERENCES syntax, but unlike a table constraint they are never enforced and never modify the table.
| Name | Type | Description |
|---|---|---|
name | Specifies the machine name (slug) of the semantic context to mutate. Matched case-insensitively. If no context with this name exists, the statement raises a clear not-found error. The name addresses the context; the control plane resolves it to the stored id before applying the change. | |
SET (TITLE=, DESCRIPTION=, INSTRUCTIONS=) | Updates the context metadata. Each assignment value is a single-quoted string literal. Only the fields named in SET are changed; fields not mentioned keep their current values. Use SET to revise the title, the description, or the grounding instructions. | |
ADD TABLE <zone.schema.table> [DESCRIPTION '...'] | Pins a table or view to the context's data scope. The qualified name is parsed the same way SHOW TABLE JOINS parses it (the trailing three segments are catalog/zone, schema, and table; fewer segments leave the leading qualifiers unset) and stored as the raw qualified string. The optional DESCRIPTION attaches a per-table note that grounding tools surface alongside the table. | |
DROP TABLE <zone.schema.table> | Unpins a table from the context's data scope, identified by its qualified name. Removes only the pin from this context; the physical table and its data are never touched. | |
ADD EXPRESSION <expr_name> AS '<sql>' [DESCRIPTION '...'] | Registers a named, reusable SQL expression (a measure) under the context. expr_name is a bare identifier unique within the context; the SQL body is a single-quoted string literal. The optional DESCRIPTION documents what the measure computes. Grounding tools return these so an assistant reuses trusted definitions instead of re-deriving them. | |
DROP EXPRESSION <expr_name> | Removes the named expression from the context, identified by its name. | |
ADD QUERY '<title>' AS '<sql>' [QUESTION '...'] | Registers a trusted example query under the context. The title and SQL body are single-quoted string literals; the title is the query's natural key within the context. The optional QUESTION attaches the natural-language question the query answers, which helps an assistant map a user's phrasing to a vetted query. | |
DROP QUERY '<title>' | Removes the trusted example query whose title matches the given string literal. | |
ADD QUESTION '<text>' | Appends a starter sample question (a single-quoted string literal) to the context's list of sample questions. Sample questions are suggested prompts shown to users entering the space. | |
DROP QUESTION '<text>' | Removes the matching sample question string from the context's list of sample questions. | |
ADD PRIMARY KEY (<col>, ...) ON <zone.schema.table> | Declares an informational primary-key virtual constraint over the listed columns of the named table. The constraint is metadata only: it is never enforced and never alters the physical Delta or Iceberg table. It is expressed under the context for convenience but stored catalog-level, so it is shared across any context that pins the same table. | |
ADD FOREIGN KEY (<col>, ...) ON <zone.schema.table> REFERENCES <zone.schema.table> (<col>, ...) | Declares an informational foreign-key virtual constraint from the local columns on the first table to the referenced columns on the second table. The two column lists are positionally aligned. Like all virtual keys it is never enforced and never alters either physical table; it only records a relationship that grounding tools and join detection can trust. | |
ADD UNIQUE (<col>, ...) ON <zone.schema.table> | Declares an informational uniqueness virtual constraint over the listed columns of the named table. Metadata only; never enforced, never alters the physical table. | |
DROP CONSTRAINT (<col>, ...) ON <zone.schema.table> | Removes the virtual constraint on the named table whose column list matches the one given. Because virtual constraints are stored catalog-level, dropping one removes it for every context that referenced it. |
-- SET: revise the context metadata; only the named fields change
ALTER SEMANTIC CONTEXT sales
SET (TITLE='Sales Analytics (FY26)', INSTRUCTIONS='Revenue is net of returns; default to the current fiscal year.');-- ADD TABLE / DROP TABLE: manage the data scope
ALTER SEMANTIC CONTEXT sales ADD TABLE gold.sales.orders DESCRIPTION 'One row per order line.';
ALTER SEMANTIC CONTEXT sales ADD TABLE gold.sales.customers;
ALTER SEMANTIC CONTEXT sales DROP TABLE gold.sales.customers;-- ADD EXPRESSION / DROP EXPRESSION: reusable measures
ALTER SEMANTIC CONTEXT sales
ADD EXPRESSION net_revenue AS 'sum(amount) - sum(refund_amount)' DESCRIPTION 'Revenue net of refunds.';
ALTER SEMANTIC CONTEXT sales DROP EXPRESSION net_revenue;-- ADD QUERY / DROP QUERY: trusted example queries with the question they answer
ALTER SEMANTIC CONTEXT sales
ADD QUERY 'Top customers by net revenue'
AS 'SELECT customer_id, sum(amount) - sum(refund_amount) AS net FROM gold.sales.orders GROUP BY customer_id ORDER BY net DESC LIMIT 10'
QUESTION 'Who are our top customers by net revenue?';
ALTER SEMANTIC CONTEXT sales DROP QUERY 'Top customers by net revenue';-- ADD QUESTION / DROP QUESTION: starter prompts shown in the space
ALTER SEMANTIC CONTEXT sales ADD QUESTION 'What were total orders last month?';
ALTER SEMANTIC CONTEXT sales DROP QUESTION 'What were total orders last month?';-- ADD PRIMARY KEY: informational virtual key, never enforced
ALTER SEMANTIC CONTEXT sales ADD PRIMARY KEY (order_id) ON gold.sales.orders;