CREATE SEMANTIC CONTEXT

Creates a named semantic context: a governed grounding space that pins a set of tables and carries the business context an assistant needs to query them.

Category: semantic-contextDeltaForge extension

Syntax

CREATE SEMANTIC CONTEXT [IF NOT EXISTS] <name>
  [WITH (TITLE='...', DESCRIPTION='...', INSTRUCTIONS='...')]

Description

## Overview CREATE SEMANTIC CONTEXT defines a named grounding space for natural-language and AI-assisted querying. A semantic context bundles everything an assistant needs to query a chosen set of tables correctly: a set of pinned tables (the data scope), general instructions, named reusable SQL expressions (measures), trusted example queries, starter sample questions, and informational virtual key constraints. It is DeltaForge's curated, governed equivalent of a query-grounding space. This statement creates the space itself (its name and optional title, description, and instructions). The data scope, expressions, example queries, sample questions, and virtual keys are added afterward with ALTER SEMANTIC CONTEXT. The SQL surface speaks context names. Internally the control plane stores each context under an id and resolves the name to that id; the name is unique case-insensitively. Only the control plane writes the underlying store, so the command is served through the control plane API rather than touching catalog storage directly. ## Behavior - The context is created with the given name and optional title, description, and instructions. Any field omitted from WITH is left unset. - The name must be unique case-insensitively. Without IF NOT EXISTS, creating a context whose name already exists raises an error. With IF NOT EXISTS, the statement is a no-op success and the existing context is unchanged (its title, description, and instructions are not overwritten). - A newly created context has no pinned tables, expressions, queries, sample questions, or virtual constraints. Populate it with ALTER SEMANTIC CONTEXT. - A semantic context is curation and grounding metadata, not an access boundary. Pinning a table to a context does not grant or restrict access to it; row and column access continue to be governed by the catalog RBAC model, unchanged. - The result is a single-row status batch confirming creation (for example, a message such as Semantic context 'sales' created). ## Access Control Managing a semantic context is a metastore-level curation operation served by the control plane. A principal that can create and manage catalog grounding metadata can create a context. Creating the context grants no data access on its own; the pinned tables remain governed by their existing table-level privileges. ## Compatibility CREATE SEMANTIC CONTEXT is a DeltaForge extension. There is no ANSI SQL equivalent. It is the SQL surface over the same semantic context model exposed by the control plane HTTP API, the Semantic Contexts UI, and the list_semantic_contexts / get_semantic_context grounding tools.

Parameters

Name	Type	Description
`name`		Specifies the machine name (slug) of the semantic context. A bare identifier that is unique case-insensitively across the metastore. This is the name every later ALTER, DROP, and DESCRIBE statement uses to address the context; storage internally keys the context by an id, and the control plane resolves the name to that id.
`IF NOT EXISTS`		Suppresses the error that is otherwise raised when a context with the same name already exists. When present and the context exists, the statement is a no-op success and the existing context is left unchanged.
`TITLE`		Specifies a human-readable display title for the context (a single-quoted string literal). Shown in SHOW SEMANTIC CONTEXTS and in the Semantic Contexts UI. Independent of the machine name; the name is the address, the title is the label.
`DESCRIPTION`		Specifies a free-text description of what the context covers (a single-quoted string literal). Surfaced to grounding tools so an assistant knows the scope of the space.
`INSTRUCTIONS`		Specifies the general instructions an assistant should follow when querying within this context (a single-quoted string literal). Stored as the context's general_instructions and returned verbatim by the get_semantic_context grounding tool.

Examples

-- Create a minimal context addressed by name only
CREATE SEMANTIC CONTEXT sales;

-- Create a context with a display title, description, and grounding instructions
CREATE SEMANTIC CONTEXT sales
  WITH (
    TITLE='Sales Analytics',
    DESCRIPTION='Curated tables and trusted queries for the sales org.',
    INSTRUCTIONS='Always filter to the current fiscal year unless the user asks otherwise. Revenue is net of returns.'
  );

-- Idempotent creation: re-running is a no-op when the context already exists
CREATE SEMANTIC CONTEXT IF NOT EXISTS sales
  WITH (TITLE='Sales Analytics');

Pitfalls

Requires a control-plane connection. An executor configured without a catalog router cannot create a context and returns an error directing you to configure catalog access.
Creating a semantic context does not grant any access to the tables it will pin. Access remains governed entirely by catalog RBAC; the context is grounding metadata, never a permission boundary.
Context names are matched case-insensitively. CREATE SEMANTIC CONTEXT Sales and CREATE SEMANTIC CONTEXT sales refer to the same context, and the second without IF NOT EXISTS will conflict.
WITH accepts only TITLE, DESCRIPTION, and INSTRUCTIONS. Any other key is a parse error. Tables, expressions, queries, questions, and virtual keys are added with ALTER SEMANTIC CONTEXT, not in the WITH clause.