ALTER MODEL

Changes a registered AI model's provider model id, connection, system prompt, default parameters, or options, or renames it.

Category: ai-modelPrivilege: catalog:write on the control plane.DeltaForge extension

Syntax

ALTER MODEL [IF EXISTS] <name>
  { SET MODEL = '<provider-model-id>'
  | SET CONNECTION = <connection_name>
  | SET SYSTEM_PROMPT = '<text>'
  | SET PARAMETERS = '<json-object>'
  | SET OPTIONS (<key> = '<value>', ...)
  | RENAME TO <new_name> } ...

Description

## Overview ALTER MODEL mutates one or more fields of a registered AI model. Actions are folded left to right; a later action overrides an earlier one targeting the same field. Every mutation goes through the control plane, so a change is visible to all sessions on their next model resolution (sessions cache a resolved model for up to five minutes; a just-altered model can serve from the previous configuration until that per-session cache expires). ## Semantics - SET SYSTEM_PROMPT may be written SET SYSTEM, and SET PARAMETERS as SET PARAMS. - SET PARAMETERS and SET OPTIONS replace the whole stored value; they do not merge key-by-key. - SET CONNECTION validates the target connection exists before persisting. - MODEL_TYPE is intentionally immutable: changing a model's kind changes which functions may bind to it, which is a different model. Drop and recreate instead.

Parameters

Name	Type	Description
`name`		The registry name of the model to alter, matched case-insensitively.
`IF EXISTS`		Turns a missing model into a no-op success instead of an error.
`SET MODEL`		Replaces the provider-side model id (e.g. upgrade 'gpt-4.1' to 'gpt-5') without touching the registry name any SQL references.
`SET CONNECTION`		Rebinds the model to a different REST connection (validated to exist). Changes the base URL and the credential used at invocation time.
`SET SYSTEM_PROMPT`		Replaces the model-level system prompt. Only valid for MODEL_TYPE = CHAT models.
`SET PARAMETERS`		Replaces (does not merge with) the default request parameters JSON object.
`SET OPTIONS`		Replaces the model's extra options map (endpoint, api_version, deployment, timeout_secs, retry_count, header.*). Secret-looking keys are rejected.
`RENAME TO`		Renames the model. SQL referencing the old name fails on its next resolution; update AI_GENERATE call sites accordingly.

Examples

-- Upgrade the provider model without touching call sites
ALTER MODEL gpt5 SET MODEL = 'gpt-5.1';

-- Tighten the governed system prompt
ALTER MODEL support_triage SET SYSTEM_PROMPT = 'Reply with only one of: billing, outage, feature_request.';

-- Move a model onto a new gateway connection and lower the temperature
ALTER MODEL gpt5
  SET CONNECTION = corp_llm_gateway
  SET PARAMETERS = '{"temperature":0.0,"max_tokens":128}';

-- Tolerant alter in idempotent scripts
ALTER MODEL IF EXISTS legacy_model RENAME TO archived_model;

Pitfalls

Requires a control-plane connection (catalog router); offline executors return a clear configuration error.
SET SYSTEM_PROMPT on an EMBEDDINGS model is rejected: system prompts only exist on the chat request shape.
SET PARAMETERS / SET OPTIONS replace the stored JSON wholesale rather than merging; re-state every key you want to keep.
Running sessions cache the resolved model (including its credential) for up to five minutes, so an ALTER can take up to that long to be observed by an in-flight session; new sessions resolve fresh.