CREATE POLICY

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 16.4 and above check marked yes Unity Catalog only

Creates a named policy on a securable. Policies can be row filters, column masks, or ABAC GRANT policies. Row filters and column masks are applied to catalogs, schemas, or tables, and are available on Databricks Runtime 16.4 and above. ABAC GRANT policies are applied to catalogs or schemas, and dynamically grant privileges on the securables they target. The policy name is scoped to the securable the policy is defined on.

To run this statement, you must have the MANAGE privilege on the target securable or be its owner.

Creating, modifying, or dropping an ABAC GRANT policy with SQL requires Databricks Runtime 18 LTS or above. On SQL warehouses, support depends on the warehouse's release channel. See Compute requirements.

Note

Databricks Runtime 18 is newer than Databricks Runtime 18.0, 18.1, and 18.2. Features that would previously have shipped as a later numbered version now ship as dated updates to Databricks Runtime 18 instead. For details, see About unified release notes.

Syntax

CREATE [ OR REPLACE ] POLICY policy_name
ON { CATALOG catalog_name | SCHEMA schema_name | TABLE table_name }
[ COMMENT description ]
{ row_filter_body | column_mask_body | grant_policy_body }

row_filter_body
  ROW FILTER function_name
  TO principal [, ...]
  [ EXCEPT principal [, ...] ]
  FOR TABLES
  [ WHEN condition ]
  [ MATCH COLUMNS condition [ [ AS ] alias ] [, ...] ]
  [ USING COLUMNS ( function_arg [, ...] ) ]

column_mask_body
  COLUMN MASK function_name
  TO principal [, ...]
  [ EXCEPT principal [, ...] ]
  FOR TABLES
  [ WHEN condition ]
  [ MATCH COLUMNS condition [ [ AS ] alias ] [, ...] ]
  ON COLUMN alias
  [ USING COLUMNS ( function_arg [, ...] ) ]

grant_policy_body
  TO principal [, ...]
  [ EXCEPT principal [, ...] ]
  GRANT privilege [, ...]
  FOR grant_target_type
  [ WHEN condition ]

Row filter and column mask policies can be defined on a catalog, schema, or table. GRANT policies can be defined on a catalog or a schema only.

Parameters

  • policy_name

    Name of the policy. The name is scoped to the securable the policy is defined on. If a policy with the same name already exists and OR REPLACE is not specified, Azure Databricks raises POLICY_ALREADY_EXISTS.

  • catalog_name

    The name of the catalog on which the policy is defined. If the securable type is not supported for policies, Azure Databricks raises POLICY_ON_SECURABLE_TYPE_NOT_SUPPORTED.

  • schema_name

    The name of the schema on which the policy is defined.

  • table_name

    The name of the table on which the policy is defined.

  • description

    An optional string comment for the policy.

  • function_name

    The name of the UDF used for the row filter or column mask.

  • privilege

    In grant_policy_body, a privilege to grant on each securable that matches the policy. The valid privileges depend on grant_target_type. See Supported securable types and privileges.

  • grant_target_type

    In grant_policy_body, the type of securable the granted privileges apply to. Use the plural form: MODELS, MODEL SERVICES, MODEL PROVIDER SERVICES, MCP SERVICES, or AGENT SERVICES. The underscored form, such as MODEL_SERVICES, is also accepted. Singular forms are not accepted.

  • principal

    A user, group, or service principal name. Multiple principals can be listed after TO. Principals listed after EXCEPT are excluded from the policy.

  • condition

    WHEN is a boolean expression that determines whether the policy applies, based on the securable's tags, the querying user's identity attributes, and/or the context of the request.

    MATCH COLUMNS is a boolean expression that matches columns based on their tags (for example, has_tag('pii')).

    Conditions are evaluated by the control plane. The following functions are supported in conditions:

    • Tag functions (has_tag() and has_tag_value()): supported in both WHEN and MATCH COLUMNS. When used in WHEN, they check tags set directly on the table or inherited from a parent catalog or schema. When used in MATCH COLUMNS, they check tags set directly on the column only. The older camelCase forms (hasTag, hasTagValue) continue to work for backward compatibility.
    • Identity attribute functions (has_identity_attribute_value() and has_identity_attribute_tag_match()): supported in the WHEN clause of column mask policies, where they evaluate the identity attributes of the user running the query. They aren't supported in GRANT or DENY policies or in MATCH COLUMNS. See Mask a column based on attributes of the querying user.
    • Context attribute functions (has_context_attribute() and has_context_attribute_value()): supported in the WHEN clause of row filter and column mask policies, where they evaluate the context of the request, such as the calling application. They aren't supported in MATCH COLUMNS. See Restrict access for external agents acting on behalf of a user.

    If the condition is invalid, Azure Databricks raises UC_INVALID_POLICY_CONDITION.

  • alias

    In MATCH COLUMNS, an optional identifier for the matched column. The alias can be referenced in USING COLUMNS (row filter) or in ON COLUMN and USING COLUMNS (column mask).

  • function_arg

    In USING COLUMNS, each argument is either a constant expression or an alias from MATCH COLUMNS. The arguments are passed to the policy function in order. If the options do not match the policy type, Azure Databricks raises UC_POLICY_TYPE_OPTIONS_MISMATCH.

Examples

The following example creates a column mask policy:

> CREATE FUNCTION ssn_to_last_nr (ssn STRING, nr INT) RETURNS STRING
    RETURN right(ssn, nr);

> CREATE POLICY ssn_mask
    ON CATALOG employees
    COLUMN MASK ssn_to_last_nr
    TO 'All Users' EXCEPT 'HR admins'
    FOR TABLES
    MATCH COLUMNS has_tag('ssn') AS ssn
    ON COLUMN ssn
    USING COLUMNS (4);

The following example creates a row filter policy:

> CREATE FUNCTION non_eu_region (geo_region STRING) RETURNS BOOLEAN
    RETURN geo_region <> 'eu';

> CREATE POLICY hide_eu_customers
    ON SCHEMA prod.customers
    COMMENT 'Hide European customers from sensitive tables'
    ROW FILTER non_eu_region
    TO analysts
    FOR TABLES
    WHEN has_tag_value('sensitivity', 'high')
    MATCH COLUMNS has_tag('geo_region') AS region
    USING COLUMNS (region);

The following example creates an ABAC GRANT policy that grants EXECUTE on every Anthropic-created model service:

> CREATE POLICY grant_anthropic_model_services
    ON SCHEMA system.ai
    COMMENT 'Grant EXECUTE on Anthropic model services'
    TO data_scientists
    EXCEPT contractors
    GRANT EXECUTE FOR MODEL SERVICES
    WHEN has_tag_value('ai.model_creator', 'anthropic');
  • Last updated on