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 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 and attach a service 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 ON CALL phase, before the service is invoked.
• 'response': the ON RESULT phase, 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' (ON CALL) or 'response' (ON RESULT).
event:target	All services	The Unity Catalog full name of the service the policy is attached to (optional).
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	The extracted last user or assistant message (API-agnostic). Use this for content checks.
event:data	Model Services	The full request or response payload.
event:request_data	Model Services	The original request, available during 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.

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. The caller receives a structured error with the reason.
• ASK: the interaction pauses for human approval before proceeding.

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

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