Skip to main content

Policy

View as Markdown

PolicyInfo object​

idstring

Unique identifier of the policy. This field is output only and is generated by the system.

on_securable_typestring

Type of the securable on which the policy is defined. Only CATALOG, SCHEMA and TABLE are supported at this moment. Required on create.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

on_securable_fullnamestring

Full name of the securable on which the policy is defined. Required on create.

namestring

Name of the policy. Required on create and optional on update. To rename the policy, set name to a different value on update.

commentstring

Optional description of the policy.

to_principalsarray of string

List of user or group names that the policy applies to. Required on create and optional on update.

except_principalsarray of string

Optional list of user or group names that should be excluded from the policy.

for_securable_typestring

Type of securables that the policy should take effect on. Required on create and optional on update.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

when_conditionstring

Optional condition when the policy should take effect.

policy_typestring

Type of the policy. Required on create.

Values: POLICY_TYPE_UNSPECIFIED, POLICY_TYPE_ROW_FILTER, POLICY_TYPE_COLUMN_MASK, POLICY_TYPE_GRANT

row_filterobject

Options for row filter policies. Valid only if policy_type is POLICY_TYPE_ROW_FILTER. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
function_namestring

The fully qualified name of the row filter function. The function is called on each row of the target table. It should return a boolean value indicating whether the row should be visible to the user. Required on create and update.

usingarray of object

Optional list of column aliases or constant literals to be passed as arguments to the row filter function. The type of each column should match the positional argument of the row filter function.

Show child attributesHide child attributes
aliasstring

The alias of a matched column.

constantstring

A constant literal.

column_maskobject

Options for column mask policies. Valid only if policy_type is POLICY_TYPE_COLUMN_MASK. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
function_namestring

The fully qualified name of the column mask function. The function is called on each row of the target table. The function's first argument and its return type should match the type of the masked column. Required on create and update.

on_columnstring

The alias of the column to be masked. The alias must refer to one of matched columns. The values of the column is passed to the column mask function as the first argument. Required on create and update.

usingarray of object

Optional list of column aliases or constant literals to be passed as additional arguments to the column mask function. The type of each column should match the positional argument of the column mask function.

Show child attributesHide child attributes
aliasstring

The alias of a matched column.

constantstring

A constant literal.

grantobject

Options for grant policies. Valid only if policy_type is POLICY_TYPE_GRANT. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
privilegesarray of string

List of privileges to grant. When any of these privileges are requested, the policy will grant access if the principal and condition match. Required on create and update.

match_columnsarray of object

Optional list of condition expressions used to match table columns. Only valid when for_securable_type is TABLE. When specified, the policy only applies to tables whose columns satisfy all match conditions.

Show child attributesHide child attributes
conditionstring

The condition expression used to match a table column.

aliasstring

Optional alias of the matched column.

created_atint64

Time at which the policy was created, in epoch milliseconds. Output only.

created_bystring

Username of the user who created the policy. Output only.

updated_atint64

Time at which the policy was last modified, in epoch milliseconds. Output only.

updated_bystring

Username of the user who last modified the policy. Output only.

Get GA​

GET /api/2.1/unity-catalog/policies/{on_securable_type}/{on_securable_fullname}/{name}

Get the policy definition on a securable

API scopes: unity-catalog

Parameters​

on_securable_typestringpath

Required. The type of the securable to retrieve the policy for.

on_securable_fullnamestringpath

Required. The fully qualified name of securable to retrieve policy for.

namestringpath

Required. The name of the policy to retrieve.

Response​

Returns the PolicyInfo object.

List GA​

GET /api/2.1/unity-catalog/policies/{on_securable_type}/{on_securable_fullname}

List all policies defined on a securable. Optionally, the list can include inherited policies defined on the securable's parent schema or catalog.

PAGINATION BEHAVIOR: The API is by default paginated, a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters​

on_securable_typestringpath

Required. The type of the securable to list policies for.

on_securable_fullnamestringpath

Required. The fully qualified name of securable to list policies for.

include_inheritedbooleanquery

Optional. Whether to include policies defined on parent securables. By default, the inherited policies are not included.

max_resultsint32query

Optional. Maximum number of policies to return on a single page (page length).

  • When not set or set to 0, the page length is set to a server configured value (recommended);
  • When set to a value greater than 0, the page length is the minimum of this value and a server configured value;
page_tokenstringquery

Optional. Opaque pagination token to go to next page based on previous query.

Response​

Returns a list of PolicyInfo objects.

Create GA​

POST /api/2.1/unity-catalog/policies

Creates a new policy on a securable. The new policy applies to the securable and all its descendants.

API scopes: unity-catalog

Request body​

policy_infoobject

Required. The policy to create.

Show child attributesHide child attributes
idstring

Unique identifier of the policy. This field is output only and is generated by the system.

on_securable_typestring

Type of the securable on which the policy is defined. Only CATALOG, SCHEMA and TABLE are supported at this moment. Required on create.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

on_securable_fullnamestring

Full name of the securable on which the policy is defined. Required on create.

namestring

Name of the policy. Required on create and optional on update. To rename the policy, set name to a different value on update.

commentstring

Optional description of the policy.

to_principalsarray of string

List of user or group names that the policy applies to. Required on create and optional on update.

except_principalsarray of string

Optional list of user or group names that should be excluded from the policy.

for_securable_typestring

Type of securables that the policy should take effect on. Required on create and optional on update.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

when_conditionstring

Optional condition when the policy should take effect.

policy_typestring

Type of the policy. Required on create.

Values: POLICY_TYPE_UNSPECIFIED, POLICY_TYPE_ROW_FILTER, POLICY_TYPE_COLUMN_MASK, POLICY_TYPE_GRANT

row_filterobjectRequired

Options for row filter policies. Valid only if policy_type is POLICY_TYPE_ROW_FILTER. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
function_namestring

The fully qualified name of the row filter function. The function is called on each row of the target table. It should return a boolean value indicating whether the row should be visible to the user. Required on create and update.

usingarray of object

Optional list of column aliases or constant literals to be passed as arguments to the row filter function. The type of each column should match the positional argument of the row filter function.

Show child attributesHide child attributes
aliasstringRequired

The alias of a matched column.

constantstringRequired

A constant literal.

column_maskobjectRequired

Options for column mask policies. Valid only if policy_type is POLICY_TYPE_COLUMN_MASK. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
function_namestring

The fully qualified name of the column mask function. The function is called on each row of the target table. The function's first argument and its return type should match the type of the masked column. Required on create and update.

on_columnstring

The alias of the column to be masked. The alias must refer to one of matched columns. The values of the column is passed to the column mask function as the first argument. Required on create and update.

usingarray of object

Optional list of column aliases or constant literals to be passed as additional arguments to the column mask function. The type of each column should match the positional argument of the column mask function.

Show child attributesHide child attributes
aliasstringRequired

The alias of a matched column.

constantstringRequired

A constant literal.

grantobjectRequired

Options for grant policies. Valid only if policy_type is POLICY_TYPE_GRANT. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
privilegesarray of string

List of privileges to grant. When any of these privileges are requested, the policy will grant access if the principal and condition match. Required on create and update.

match_columnsarray of object

Optional list of condition expressions used to match table columns. Only valid when for_securable_type is TABLE. When specified, the policy only applies to tables whose columns satisfy all match conditions.

Show child attributesHide child attributes
conditionstring

The condition expression used to match a table column.

aliasstring

Optional alias of the matched column.

created_atint64

Time at which the policy was created, in epoch milliseconds. Output only.

created_bystring

Username of the user who created the policy. Output only.

updated_atint64

Time at which the policy was last modified, in epoch milliseconds. Output only.

updated_bystring

Username of the user who last modified the policy. Output only.

Response​

Returns the PolicyInfo object.

Update GA​

PATCH /api/2.1/unity-catalog/policies/{on_securable_type}/{on_securable_fullname}/{name}

Update an ABAC policy on a securable.

API scopes: unity-catalog

Parameters​

on_securable_typestringpath

Required. The type of the securable to update the policy for.

on_securable_fullnamestringpath

Required. The fully qualified name of the securable to update the policy for.

namestringpath

Required. The name of the policy to update.

update_maskstringquery

Optional. The update mask field for specifying user intentions on which fields to update in the request.

Request body​

policy_infoobject

Optional fields to update. This is the request body for updating a policy. Use update_mask field to specify which fields in the request is to be updated.

  • If update_mask is empty or "*", all specified fields will be updated.
  • If update_mask is specified, only the fields specified in the update_mask will be updated. If a field is specified in update_mask and not set in the request, the field will be cleared. Users can use the update mask to explicitly unset optional fields such as exception_principals and when_condition.
Show child attributesHide child attributes
idstring

Unique identifier of the policy. This field is output only and is generated by the system.

on_securable_typestring

Type of the securable on which the policy is defined. Only CATALOG, SCHEMA and TABLE are supported at this moment. Required on create.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

on_securable_fullnamestring

Full name of the securable on which the policy is defined. Required on create.

namestring

Name of the policy. Required on create and optional on update. To rename the policy, set name to a different value on update.

commentstring

Optional description of the policy.

to_principalsarray of string

List of user or group names that the policy applies to. Required on create and optional on update.

except_principalsarray of string

Optional list of user or group names that should be excluded from the policy.

for_securable_typestring

Type of securables that the policy should take effect on. Required on create and optional on update.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

when_conditionstring

Optional condition when the policy should take effect.

policy_typestring

Type of the policy. Required on create.

Values: POLICY_TYPE_UNSPECIFIED, POLICY_TYPE_ROW_FILTER, POLICY_TYPE_COLUMN_MASK, POLICY_TYPE_GRANT

row_filterobjectRequired

Options for row filter policies. Valid only if policy_type is POLICY_TYPE_ROW_FILTER. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
function_namestring

The fully qualified name of the row filter function. The function is called on each row of the target table. It should return a boolean value indicating whether the row should be visible to the user. Required on create and update.

usingarray of object

Optional list of column aliases or constant literals to be passed as arguments to the row filter function. The type of each column should match the positional argument of the row filter function.

Show child attributesHide child attributes
aliasstringRequired

The alias of a matched column.

constantstringRequired

A constant literal.

column_maskobjectRequired

Options for column mask policies. Valid only if policy_type is POLICY_TYPE_COLUMN_MASK. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
function_namestring

The fully qualified name of the column mask function. The function is called on each row of the target table. The function's first argument and its return type should match the type of the masked column. Required on create and update.

on_columnstring

The alias of the column to be masked. The alias must refer to one of matched columns. The values of the column is passed to the column mask function as the first argument. Required on create and update.

usingarray of object

Optional list of column aliases or constant literals to be passed as additional arguments to the column mask function. The type of each column should match the positional argument of the column mask function.

Show child attributesHide child attributes
aliasstringRequired

The alias of a matched column.

constantstringRequired

A constant literal.

grantobjectRequired

Options for grant policies. Valid only if policy_type is POLICY_TYPE_GRANT. Required on create and optional on update. When specified on update, the new options will replace the existing options as a whole.

Show child attributesHide child attributes
privilegesarray of string

List of privileges to grant. When any of these privileges are requested, the policy will grant access if the principal and condition match. Required on create and update.

match_columnsarray of object

Optional list of condition expressions used to match table columns. Only valid when for_securable_type is TABLE. When specified, the policy only applies to tables whose columns satisfy all match conditions.

Show child attributesHide child attributes
conditionstring

The condition expression used to match a table column.

aliasstring

Optional alias of the matched column.

created_atint64

Time at which the policy was created, in epoch milliseconds. Output only.

created_bystring

Username of the user who created the policy. Output only.

updated_atint64

Time at which the policy was last modified, in epoch milliseconds. Output only.

updated_bystring

Username of the user who last modified the policy. Output only.

Response​

Returns the PolicyInfo object.

Delete GA​

DELETE /api/2.1/unity-catalog/policies/{on_securable_type}/{on_securable_fullname}/{name}

Delete an ABAC policy defined on a securable.

API scopes: unity-catalog

Parameters​

on_securable_typestringpath

Required. The type of the securable to delete the policy from.

on_securable_fullnamestringpath

Required. The fully qualified name of the securable to delete the policy from.

namestringpath

Required. The name of the policy to delete