创建和管理行筛选器和列掩码策略

本页介绍如何在 Unity 目录中创建、编辑、查看和删除 ABAC 行筛选器和列掩码策略。有关策略概念的概述，请参阅 ABAC 的核心概念。

要求

修改策略（创建、编辑、删除）需要 MANAGE 对可保护对象或对象所有权进行修改。查看策略（SHOW、DESCRIBE）需要对可保护对象具有 READ METADATA 或 MANAGE 权限，或者拥有该对象的所有权。制定保单还需要以下条件：

Databricks Runtime 16.4 或更高版本，或无服务器计算。请参阅计算要求。
对于筛选或屏蔽逻辑，可以使用您在 Unity 目录中启用的用户定义函数（UDF），或者在创建策略时内联定义的 SQL 函数。
应用于目标对象的受治理标记。请参阅受管控的标签。

创建策略

可以使用目录资源管理器 UI、CREATE POLICY SQL 语句或 Azure Databricks REST API、SDK 和 Terraform 来创建策略。

若要创建策略，您必须在策略所附加到的安全对象（目录、架构或表）上具有 MANAGE 权限，或拥有该安全对象，并且在实现筛选或掩码逻辑的 UDF 上具有 EXECUTE 权限。

目录资源管理器

在 Azure Databricks 工作区中，单击目录。
选择确定策略范围的对象，例如目录、架构或表。
单击“策略”选项卡。
单击“新建策略”。

完成 “策略标识 ”部分。下表汇总了每个字段：

字段	Description	示例
Name	策略的名称。在同一安全对象上定义的所有策略中必须是唯一的。	`hide_eu_customers`、`mask_ssn`
Description	Optional. 策略的说明。显示在审核日志中，并帮助管理员了解策略意向。	`Restrict EU customer rows from US analysts`、`Mask SSN for all account users`

完成 “主体和范围 ”部分。下表汇总了每个字段：

字段	Description	示例
应用于...	受策略约束的用户、组或服务主体。当这些主体查询作用域中的表时，将应用行筛选器或列掩码。若要将策略应用于帐户中的所有主体，请选择 `All account users`。	`us_analysts`、`All account users`
除了	主要负责人豁免于该策略。豁免主体不受筛选或掩码的约束，并查看完整、未修改的数据。	`admins`、`compliance_team`
Scope	附加策略的安全对象。该策略针对所选范围内的所有表进行评估。选择目录、架构或表。 Azure Databricks建议在最高适用级别附加策略。	选择目录 `prod`，然后选择架构 `customers`。
表状态	确定策略应用于的范围中的哪些表。无条件：将策略应用于作用域中的所有表。与这些标记中的任何一个匹配的表：将策略应用于标记键或标记键值对的指定列表。其中任何一个匹配策略的表。与自定义表达式匹配的表：可以使用`has_tag`和`has_tag_value`构建布尔表达式，结合`ANDOR`以及`NOT`以实现更复杂的匹配逻辑。在表达式计算结果为`TRUE`且符合策略的情况下，将该策略应用于相关表。如果作用域中的表与条件不匹配，则策略不适用于该表。	选择与这些标记中的任何一个匹配的表，然后选择具有值的`sensitivity`标记键`high`，以仅将策略限制为敏感表。

用于主体和范围部分的 ABAC 策略设置示例。

对于 策略类型，请选择要强制实施的访问控制类型：

选项	Description	何时使用
行筛选器	创建行筛选器策略。 UDF 计算每行并返回布尔值。从查询结果中排除 UDF 返回的 `FALSE` 行。	Access 取决于每行的值，例如按包含地理区域的列中的值进行筛选。
列掩码	创建列掩码策略。 UDF 将列值作为输入，并返回原始版本或掩码版本。返回类型必须能够转换为目标列的数据类型。	需要对敏感字段（如 SSN、电话号码或电子邮件地址）进行修订，同时仍允许主体查询表。

接下来的几个部分取决于 策略类型 选择。展开与所选内容匹配的部分：
行筛选器

在 “行筛选器函数 ”部分中，选择如何指定行筛选器函数：
- 选择现有：选择已在 Unity 目录中定义的 UDF。 UDF 计算每行并返回布尔值。从查询结果中排除函数返回的 FALSE 行。必须在 UDF 上具有 EXECUTE 。
- 创建：定义要用作行筛选器逻辑的 SQL 函数。
在 “函数输入 ”部分中，为每个函数参数提供一个值。每个输入可以是由标记匹配的列、由自定义表达式匹配的列或常量值。
列掩码

在 列条件 部分，选择如何识别要掩码的列：
- 与任何这些标签匹配的列：指定标签键或标签键值对的列表。包含这些数据类型之一的列将被策略屏蔽。
- 与自定义表达式匹配的列：构建布尔表达式，使用has_tag并结合has_tag_value，以及通过AND、OR和NOT为更复杂的匹配逻辑。表达式计算结果为 TRUE 时被掩盖的列。
然后，选择要应用于匹配列的 掩码函数 ：
- 选择现有：选择已在 Unity 目录中定义的 UDF。 UDF 返回原始值或掩码值。返回类型必须能够转换为目标列的数据类型。必须在 UDF 上具有 EXECUTE 。
- 创建：定义要用作列掩码逻辑的 SQL 函数。
在 “函数输入 ”部分中，为每个附加函数参数提供一个值。每个输入可以是由标记匹配的列、由自定义表达式匹配的列或常量值。

此示例使用常量值 4 来显示 SSN 的最后 4 个字符。
单击“创建策略”。

SQL

有关完整文档，请参阅 CREATE POLICY。

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

行筛选器正文：

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

列掩码主体：

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

参数：

policy_name：策略的名称。在同一安全对象上定义的所有策略中必须是唯一的。
ON { CATALOG | SCHEMA | TABLE }：附加策略的范围。该策略会对作为此安全对象下级对象的所有表进行评估。
function_name：实现筛选或掩码逻辑的 UDF 的完全限定名称。
TO principal [, ...]：策略适用的用户、组或服务主体。
EXCEPT principal [, ...]：负责人豁免于政策。豁免主体不受筛选或掩码的约束。
FOR TABLES：指定策略面向表。表当前是唯一受支持的安全对象类型，其中包括流式处理表和具体化视图。
WHEN condition：一个布尔表达式，用于根据表的标签确定策略适用的表。使用内置函数 has_tag('tag_name') 和 has_tag_value('tag_name', 'tag_value'). 如果省略，则默认为 TRUE （适用于作用域中的所有表）。
MATCH COLUMNS condition [[AS] alias] [, ...]：标识策略所针对列的列条件。每个条件都是一个布尔表达式，由has_tag('tag_name')和has_tag_value('tag_name', 'tag_value')构建，并可以选择与AND、OR以及NOT组合。可以为每个条件分配一个别名，以便在ON COLUMN和USING COLUMNS中使用。策略最多可以包含 3 MATCH COLUMNS 个表达式，并且所有表达式都必须匹配才能应用策略。
ON COLUMN alias：对于列掩码策略，指定要掩码的匹配列，通过其在 MATCH COLUMNS中的别名引用。
USING COLUMNS (function_arg [, ...])：传递给 UDF 的参数。每个参数可以是别名 MATCH COLUMNS ，也可以是常量文本。

示例：列掩码策略。在pii:ssn架构中，屏蔽所有用prod.customers标记的列，仅显示最后 4 个字符。策略适用于 us_analysts，但不适用于 admins。

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

CREATE POLICY mask_ssn
ON SCHEMA prod.customers
COLUMN MASK ssn_to_last_nr
TO us_analysts EXCEPT admins
FOR TABLES
MATCH COLUMNS has_tag_value('pii', 'ssn') AS ssn
ON COLUMN ssn
USING COLUMNS (4);

示例：行筛选器策略。从架构中sensitivity:high标记的prod.customers表中排除具有欧洲客户的行。策略适用于 us_analysts 并根据 geo_region 列筛选行。

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

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

Python SDK

有关完整文档，请参阅 Databricks SDK for Python 文档。

此示例创建一个行筛选策略，该策略为美国的分析师排除欧洲客户的行：

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import (
    FunctionArgument,
    MatchColumn,
    PolicyInfo,
    PolicyType,
    RowFilterOptions,
    SecurableType,
)

w = WorkspaceClient()

w.policies.create_policy(PolicyInfo(
    name="hide_eu_customers",
    comment="Exclude rows with European customers from sensitive tables",
    on_securable_type=SecurableType.SCHEMA,
    on_securable_fullname="prod.customers",
    for_securable_type=SecurableType.TABLE,
    policy_type=PolicyType.POLICY_TYPE_ROW_FILTER,
    to_principals=["us_analysts"],
    match_columns=[
        MatchColumn(condition="has_tag('geo_region')", alias="region"),
    ],
    row_filter=RowFilterOptions(
        function_name="prod.customers.non_eu_region",
        using=[FunctionArgument(alias="region")],
    ),
))

此示例创建了一个列掩码策略，用于掩盖美国分析师的社会保障号码，但admins组中的成员除外。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import (
    ColumnMaskOptions,
    FunctionArgument,
    MatchColumn,
    PolicyInfo,
    PolicyType,
    SecurableType,
)

w = WorkspaceClient()

w.policies.create_policy(PolicyInfo(
    name="mask_ssn",
    comment="Mask social security numbers",
    on_securable_type=SecurableType.SCHEMA,
    on_securable_fullname="prod.customers",
    for_securable_type=SecurableType.TABLE,
    policy_type=PolicyType.POLICY_TYPE_COLUMN_MASK,
    to_principals=["us_analysts"],
    except_principals=["admins"],
    match_columns=[
        MatchColumn(condition="has_tag_value('pii', 'ssn')", alias="ssn"),
    ],
    column_mask=ColumnMaskOptions(
        function_name="prod.customers.ssn_to_last_nr",
        on_column="ssn",
        using=[FunctionArgument(constant="4")],
    ),
))

编辑策略

目录资源管理器

在 Azure Databricks 工作区中，单击目录。
选择策略所附加到的对象。
单击“策略”选项卡。
选择想要编辑的策略。
更新您想要更改的字段。可以修改说明、主体、策略类型、条件和函数输入映射。无法编辑应用策略的策略名称和安全对象。有关字段说明，请参阅 “创建策略”。
单击“更新策略”。

SQL

CREATE OR REPLACE POLICY 替换整个策略定义。指定所有子句，而不仅仅是要更改的字段。替换策略必须具有相同的名称，并且位于同一安全对象上。

CREATE OR REPLACE POLICY mask_ssn
ON SCHEMA prod.customers
COLUMN MASK ssn_to_last_nr
TO us_analysts EXCEPT admins, compliance_team
FOR TABLES
MATCH COLUMNS has_tag_value('pii', 'ssn') AS ssn
ON COLUMN ssn
USING COLUMNS (4);

Python SDK

与在 SQL 中不同 CREATE OR REPLACE POLICY ， update_policy 支持部分更新。使用 update_mask 参数指定要更改的字段。只更新这些字段。如果 update_mask 为 "*" 或为空，则应用所有 policy_info 字段。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import PolicyInfo

w = WorkspaceClient()

w.policies.update_policy(
    on_securable_type="SCHEMA",
    on_securable_fullname="prod.customers",
    name="mask_ssn",
    policy_info=PolicyInfo(
        except_principals=["admins", "compliance_team"],
    ),
    update_mask="except_principals",
)

删除策略

目录资源管理器

在 Azure Databricks 工作区中，单击目录。
选择策略所附加到的对象。
单击“策略”选项卡。
选择策略。
单击“ 删除策略”。

SQL

使用DROP POLICY删除策略。

DROP POLICY policy_name ON { CATALOG | SCHEMA | TABLE } securable_name

示例：

DROP POLICY mask_ssn ON SCHEMA prod.customers;
DROP POLICY hide_eu_customers ON SCHEMA prod.customers;

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.policies.delete_policy(
    on_securable_type="SCHEMA",
    on_securable_fullname="prod.customers",
    name="mask_ssn",
)

显示策略

使用 SHOW POLICIES 列出在安全对象上定义的策略。用 SHOW EFFECTIVE POLICIES 来同时包括父级范围中的策略，例如影响表的目录级策略。

SHOW [EFFECTIVE] POLICIES ON { CATALOG | SCHEMA | TABLE } securable_name

结果包括策略名称、策略类型和定义每个策略的目录、架构或表。

查看表的有效策略不需要对父目录或架构具有权限。这允许表管理员查看应用的规则，而无需读取对同级表策略的访问权限。

Example:

SHOW EFFECTIVE POLICIES ON SCHEMA prod.customers;

策略名称	policy_type	目录	架构	注释
隐藏_EU_客户	行筛选器	生产	客户
mask_ssn	列掩码	生产	客户

描述策略

用于 DESCRIBE POLICY 查看特定策略的详细信息。需要在目标安全对象上具有 READ METADATA 或 MANAGE，或者拥有该对象的所有权。

{ DESC | DESCRIBE } POLICY policy_name ON { CATALOG | SCHEMA | TABLE } securable_name

结果将策略的属性显示为键值对，包括名称、安全对象类型、安全对象名称、主体、条件、函数名称和时间戳。

Example:

DESCRIBE POLICY hide_eu_customers ON SCHEMA prod.customers;

info_name	info_value
Name	隐藏_EU_客户
在安全对象类型上	SCHEMA
在 Securable 上	prod.customers (生产环境.客户)
致负责人	us_analysts
对于可保护类型	表格
匹配列	HAS_TAG（“geo_region”） AS 区域
策略类型	ROW_FILTER
函数名称	prod.customers.非欧盟地区
使用列	区域

查询 ABAC 策略定义

INFORMATION_SCHEMA.ABAC_POLICY_DEFINITIONS 返回当前目录中的 ABAC 策略定义。要查询跨目录的策略，请使用 SYSTEM.INFORMATION_SCHEMA.ABAC_POLICY_DEFINITIONS。

你可以使用这些视图大规模审核你的策略清单，包括策略附加在何处、适用于哪些主体，以及每项策略允许哪些操作。

注释

只有当你对附加了该策略的可保护对象拥有 MANAGE 时，才能看到这些策略。

-- View all grant policies in a metastore.
SELECT *
FROM system.information_schema.abac_policy_definitions
WHERE policy_type = 'GRANT'
ORDER BY policy_name;

-- List all row filter and column mask policies in a catalog.
SELECT *
FROM <catalog-name>.information_schema.abac_policy_definitions
WHERE policy_type IN ('ROW_FILTER', 'COLUMN_MASK')
ORDER BY policy_type, policy_name;

审计日志

Azure Databricks在审核日志系统表中记录受管理标记和 ABAC 策略的操作。下面是示例查询。有关详细信息，请参阅审核日志。

-- All tag assignment and deletion events from the audit log
SELECT
  event_time,
  action_name,
  user_identity.email AS actor,
  request_params.workspace_id,
  request_params.metastore_id,
  request_params.tag_assignment,
  response.status_code,
  source_ip_address
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name IN (
    'createEntityTagAssignment',
    'deleteEntityTagAssignment'
  )
ORDER BY event_time DESC;

-- All ABAC policy CRUD operations
SELECT
  event_time,
  action_name,
  user_identity.email AS actor,
  request_params.name AS policy_name,
  request_params.on_securable_type,
  request_params.on_securable_fullname,
  request_params.policy_info,
  response.status_code
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name IN ('createPolicy', 'deletePolicy', 'getPolicy', 'listPolicies')
ORDER BY event_time DESC;

其他资源

Last updated on 2026-08-24