Service policy function reference

Beta

This feature is in Beta. Account admins can control access to this feature from the account console Previews page. See Manage Databricks previews.

A custom SQL service policy is a SQL user-defined function (UDF) registered in Unity Catalog that Databricks evaluates on each interaction with the service it is attached to. This page is the field and syntax reference for those functions. For the end-to-end procedure, see Create a SQL policy.

Function signature

A service policy function takes a single event VARIANT parameter and returns a VARIANT:

SQL

CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;

The function runs at both evaluation points. Branch on event:type::string to tell them apart:

• 'request': the input phase (ON CALL), before the service is invoked.
• 'response': the output phase (ON RESULT), after the service responds.

The event argument

event carries the interaction data and context. The available fields depend on the service type:

Field	Applies to	Description
event:type	All services	The phase: 'request' (input, ON CALL) or 'response' (output, ON RESULT).
event:target	All services	The Unity Catalog full name of the service the policy is attached to (optional).
event:context.request_tags	Model Services, Model Provider Services, MCP Services (tools/call)	A JSON object of caller-supplied string keys and string values. See Request tags.
event:context.actor.run_as	All services	The run-as identity the request authorizes against.
event:context.actor.context.is_on_behalf_of	All services	true when an agent or app is acting on behalf of a user (on-behalf-of, or OBO). Use it to write agent-aware policies that apply only when an agent acts for a user.
event:context.actor.context.client_id	All services	The OAuth client ID of the acting identity, when present (OBO calls).
event:context.actor.context.actor_resource	All services	The resource of the acting identity, such as an agent, when present.
event:context.actor.context.is_actor_authenticated	All services	true when the acting identity authenticated as a confidential client.
event:context.tool.name, event:context.tool.arguments	MCP Services	The tool being called and its arguments (for example, event:context.tool.arguments.repo).
event:context.message	Model Services, Model Provider Services	The extracted last user or assistant message (API-agnostic). Use this for content checks.
event:data	Model Services, Model Provider Services	The full request or response payload.
event:request_data	Model Services, Model Provider Services	The original request, available during the output phase (ON RESULT).

Field	Applies to	Description
event:type	All services	The phase: 'request' (input, ON CALL) or 'response' (output, ON RESULT).
event:target	All services	The Unity Catalog full name of the service the policy is attached to (optional).
event:context.request_tags	Model Services, Model Provider Services, MCP Services (tools/call)	A JSON object of caller-supplied string keys and string values. See Request tags.
event:context.actor.run_as	All services	The run-as identity the request authorizes against.
event:context.actor.context.is_on_behalf_of	All services	true when an agent or app is acting on behalf of a user (on-behalf-of, or OBO). Use it to write agent-aware policies that apply only when an agent acts for a user.
event:context.actor.context.client_id	All services	The OAuth client ID of the acting identity, when present (OBO calls).
event:context.actor.context.actor_resource	All services	The resource of the acting identity, such as an agent, when present.
event:context.actor.context.is_actor_authenticated	All services	true when the acting identity authenticated as a confidential client.
event:context.tool.name, event:context.tool.arguments	MCP Services	The tool being called and its arguments (for example, event:context.tool.arguments.repo).
event:context.message	Model Services, Model Provider Services	The extracted last user or assistant message (API-agnostic). Use this for content checks.
event:data	Model Services, Model Provider Services	The full request or response payload.
event:request_data	Model Services, Model Provider Services	The original request, available during the output phase (ON RESULT).

note

Path access (event:...) returns a VARIANT. Cast it to a scalar type before comparing it to a literal (for example, event:type::string = 'request'); otherwise the comparison fails with a DATATYPE_MISMATCH error.

Request tags

Custom policies can evaluate the tags sent in the Databricks-Ai-Gateway-Request-Tags header:

HTTP

Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}

This support applies to Unity Gateway requests on paths where service policies run, including MCP tools/call.

Tags come from request headers and appear in event:context alongside other policy metadata. event:data and event:request_data contain payload bodies.

event:context.request_tags is an object inside the event VARIANT, with string keys and string values, logically MAP<STRING, STRING>. Read a tag with event:context.request_tags.project::string. Keys and values preserve case, punctuation, and empty strings. A request without the header has an empty object ({}). Both evaluation phases receive the same request tags, including through request transformations, retries, and model fallback.

By default, the combined size of the decoded keys and values is limited to 10 KiB of UTF-8 data. HTTP header size limits also apply. For SDK and REST examples, see Request tagging.

Model services reject malformed or oversized tag headers. For MCP tools/call requests with applicable service policies, the gateway also rejects these headers before evaluating the policies, including in Log mode.

Tags are supplied by the caller and are separate from service tags and authenticated actor context. A tag alone doesn't establish identity or permission to use a project. Use trusted identity and authorization data when checking those permissions. See Require an eligible project for an example of checking a tag value.

The following limitations apply:

• Request tags aren't included in events sent to external policy providers or automatically added to LLM-as-a-judge prompts.
• MCP ASK approvals don't distinguish request tags, and approval prompts don't display them. An approval can be reused for an otherwise matching call with different tags. Use ALLOW and DENY decisions for tag-based enforcement. Those decisions are evaluated on each request.

Return value

A custom policy is a Decision Policy: it returns a VARIANT with a result field of ALLOW, DENY, or ASK (case-insensitive) and an optional reason. The result value determines what happens:

• ALLOW: the interaction proceeds.
• DENY: Databricks blocks the interaction. Instead of an error, the caller receives a successful (HTTP 200) response whose assistant turn reports the block, with the reason in a top-level databricks_service_policy object.
• ASK: on an MCP Service, the request pauses for user approval before the tool runs. If a custom SQL or Python policy returns ASK for a Model Service or Model Provider Service, Databricks blocks the request or response because these services cannot ask the user for approval.

Build the result with named_struct and wrap it in to_variant_object so the function returns a VARIANT, keeping result and reason as top-level fields. A bare named_struct returns a STRUCT, and CAST(... AS VARIANT) is not supported.

SQL

to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))

The gateway also accepts a forward-looking envelope form:

SQL

to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))

note

Fail-closed field access: Accessing a field that does not exist in the VARIANT parameter raises an error and results in DENY (standard SQL VARIANT access returns NULL for missing fields). This prevents a policy from allowing an interaction when expected fields are missing.

Supported SQL

Databricks transpiles the policy body to CEL and evaluates it at runtime, so the function body supports only a restricted subset of SQL. Databricks rejects an unsupported function or construct when you attach the policy, and the policy fails closed (DENY) at evaluation.

Category	Supported in the policy body
Operators	Comparison, logical, and arithmetic operators; ||, IN, LIKE, and IS [NOT] NULL
Control flow	CASE and IF
Casts	CAST to INT/BIGINT, DOUBLE/FLOAT, STRING, or BOOLEAN; the :: operator
Data access	VARIANT / JSON path access
String functions	CONCAT, LENGTH, CHAR_LENGTH, UPPER, LOWER, SUBSTRING, TRIM, LTRIM, RTRIM, REPLACE, STARTSWITH, ENDSWITH, CONTAINS
Other functions	COALESCE, NULLIF, IFNULL, NVL, ABS, MOD, ISNULL, ISNOTNULL, NAMED_STRUCT, TO_VARIANT_OBJECT

Category	Supported in the policy body
Operators	Comparison, logical, and arithmetic operators; ||, IN, LIKE, and IS [NOT] NULL
Control flow	CASE and IF
Casts	CAST to INT/BIGINT, DOUBLE/FLOAT, STRING, or BOOLEAN; the :: operator
Data access	VARIANT / JSON path access
String functions	CONCAT, LENGTH, CHAR_LENGTH, UPPER, LOWER, SUBSTRING, TRIM, LTRIM, RTRIM, REPLACE, STARTSWITH, ENDSWITH, CONTAINS
Other functions	COALESCE, NULLIF, IFNULL, NVL, ABS, MOD, ISNULL, ISNOTNULL, NAMED_STRUCT, TO_VARIANT_OBJECT

Not supported: ai_query, subqueries, BETWEEN, aggregate functions, lambdas / EXISTS, and variadic CONCAT or COALESCE.

Related

• Service policies for AI securables
• Create and attach a service policy