Registers an external LLM inference endpoint (chat or embeddings) as a governed catalog object callable from SQL through AI_GENERATE, AI_GENERATE_EMBEDDINGS, and the AI task functions.
CREATE MODEL [IF NOT EXISTS] <name>
WITH (API_FORMAT = 'openai' | 'azure_openai' | 'anthropic' | 'ollama',
MODEL = '<provider-model-id>',
[MODEL_TYPE = CHAT | EMBEDDINGS,]
[CONNECTION = <connection_name>,]
[SYSTEM_PROMPT = '<text>',]
[PARAMETERS = '<json-object>',]
[<extra_key> = '<value>' ...])## Overview CREATE MODEL is DeltaForge's equivalent of SQL Server 2025's CREATE EXTERNAL MODEL: it registers an external AI inference endpoint as a named, governed catalog object so SQL can invoke an LLM per row and get the response back. The model row carries only non-secret configuration; the provider base URL and the API key live on the referenced CONNECTION and its vault credential, reusing the exact transport, credential, and retry stack that powers INVOKE / CALL API ENDPOINT. ## What a model binds together - the provider dialect (API_FORMAT) that shapes requests and extracts responses, - the provider model id (MODEL), - the kind (MODEL_TYPE) that decides which SQL functions may bind to it, - the transport (CONNECTION, or a self-contained endpoint option), - a governed model-level SYSTEM_PROMPT (chat only), and - default request PARAMETERS merged under any per-call overrides. ## Consumption Chat models are invoked per row through AI_GENERATE('<model>', prompt [, parameters_json]) or the task functions; embeddings models through AI_GENERATE_EMBEDDINGS('<model>', text). The SQL-Server-style sugar AI_GENERATE(expr USE MODEL <model>) is accepted and rewritten to the leading-model-argument form. The model registry lives in the control-plane catalog, so models are shared across sessions and nodes; SHOW MODELS lists them and DESCRIBE MODEL shows one (never including secrets). ## Key aliases Inside the WITH clause, API_FORMAT may be written API, MODEL_TYPE as TYPE, SYSTEM_PROMPT as SYSTEM, and PARAMETERS as PARAMS.
| Name | Type | Description |
|---|---|---|
name | Specifies the model's registry name, unique case-insensitively. This is the name the AI functions reference: AI_GENERATE('<name>', ...) or the <expr> USE MODEL <name> sugar. | |
IF NOT EXISTS | Suppresses the error raised when a model with the same name already exists. When present and the model exists, the statement is a no-op success and the existing model is left unchanged. | |
API_FORMAT | Specifies the provider request/response dialect: 'openai' (OpenAI and OpenAI-compatible gateways such as vLLM, Together, Groq, LM Studio), 'azure_openai' (deployment-scoped paths with an api-version query parameter), 'anthropic' (the Messages API), or 'ollama' (a local Ollama runtime). Decides how the request body is shaped, which default endpoint path is used, and how the response is extracted. | |
MODEL | Specifies the provider-side model identifier, e.g. 'gpt-5', 'claude-sonnet-5', 'text-embedding-3-small', or 'nomic-embed-text'. Sent in the request body (OpenAI, Anthropic, Ollama) or used as the default Azure deployment name. | |
MODEL_TYPE | CHAT registers a text/chat-completion model consumed by AI_GENERATE and the task functions (AI_SUMMARIZE, AI_CLASSIFY, AI_EXTRACT, AI_ANALYZE_SENTIMENT, AI_TRANSLATE, AI_FIX_GRAMMAR). EMBEDDINGS registers a vector model consumed by AI_GENERATE_EMBEDDINGS. A function called with the wrong kind fails with a pointed error. | |
CONNECTION | Names an existing REST connection (CREATE CONNECTION <name> TYPE rest_api ...) that carries the provider base URL and the vault credential. Authentication material never lives on the model row; it is resolved server-side from the connection's credential at invocation time, exactly like INVOKE API ENDPOINT. Required unless an explicit endpoint option supplies a full URL for an unauthenticated local runtime. | |
SYSTEM_PROMPT | A model-level system prompt injected into every chat invocation (the Anthropic system field, the leading role:system message for OpenAI/Azure, the system message for Ollama). A per-call system_prompt key inside the PARAMETERS argument of AI_GENERATE overrides it; the task functions append their task instruction after it so both apply. Only valid for MODEL_TYPE = CHAT. | |
PARAMETERS | Default request parameters as a JSON object string, e.g. '{"temperature":0.2,"max_tokens":256}'. Merged into every request body (nested under options for Ollama). Per-call parameters passed to AI_GENERATE override these key-by-key. Keys that look like secrets (token, api_key, password, ...) are rejected. | |
extra options | Additional non-secret keys: endpoint = '<full URL>' (overrides the connection base URL + dialect default path; required instead of CONNECTION for unauthenticated local runtimes), api_version = '...' (required for azure_openai; also overrides the anthropic-version header), deployment = '...' (Azure deployment name when it differs from MODEL), timeout_secs = '<n>' (per-attempt HTTP timeout, default 120), retry_count = '<n>' (retry budget honoring Retry-After, default 3), header.<name> = '<value>' (extra request headers). |
-- Chat model over an OpenAI-compatible connection
CREATE CONNECTION openai TYPE rest_api
OPTIONS (base_url = 'https://api.openai.com', auth_mode = 'bearer')
CREDENTIAL openai_key;
CREATE MODEL gpt5
WITH (API_FORMAT = 'openai', MODEL = 'gpt-5', MODEL_TYPE = CHAT,
CONNECTION = openai,
PARAMETERS = '{"temperature":0.2,"max_tokens":256}');-- Claude with a governed system prompt
CREATE MODEL support_triage
WITH (API_FORMAT = 'anthropic', MODEL = 'claude-sonnet-5', MODEL_TYPE = CHAT,
CONNECTION = anthropic,
SYSTEM_PROMPT = 'You are a support-ticket triage assistant. Reply with only the category name.');-- Azure OpenAI: api_version is required, deployment defaults to MODEL
CREATE MODEL azure_chat
WITH (API_FORMAT = 'azure_openai', MODEL = 'gpt-5', MODEL_TYPE = CHAT,
CONNECTION = azure_oai,
api_version = '2024-08-01-preview', deployment = 'my-gpt5-deployment');-- Embeddings model for RAG indexing
CREATE MODEL embedder
WITH (API_FORMAT = 'openai', MODEL = 'text-embedding-3-small',
MODEL_TYPE = EMBEDDINGS, CONNECTION = openai,
PARAMETERS = '{"dimensions":1536}');-- Local Ollama without a connection: explicit endpoint, no auth
CREATE MODEL IF NOT EXISTS local_llama
WITH (API_FORMAT = 'ollama', MODEL = 'llama3.2', MODEL_TYPE = CHAT,
endpoint = 'http://localhost:11434/api/chat');