Service policy function reference

Important

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

A custom service policy is a SQL user-defined function (UDF) registered in Unity Catalog that Azure 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:

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: Azure 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.

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:

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

Azure Databricks transpiles the policy body to CEL and evaluates it at runtime, so the function body supports only a restricted subset of SQL. Azure 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.

  • Last updated on