Custom WHERE Clause Functions

The policy builder allows you to use custom functions that reference important Immuta metadata from within your where clause. These custom functions can be seen as utilities that help you create policies easier. Using the policy builder, you can include these functions in your masking or row-level policies by choosing where in the sub-action menu or using the custom function in the masking type dropdown menu.

The @attributeValuesContains() function

This function returns true for a given row if the provided column evaluates to an attribute value for which the querying user has a corresponding attribute value. This function requires two arguments and accepts no more than three arguments.

Parameters

Parameter	Description	Required or optional
Attribute name string	The name of the attribute to retrieve values for.	Required
@columnReference('Column_Name') string	The column that contains the value to match the attribute key against.	Required
Placeholder string	A placeholder in case the list of values is empty.	Optional

The @columnReference() function

This function must be used in custom WHERE policies that reference a column name in the data source being protected. For example, to only show rows that have the value US in the Location column, you would create the following policy:

Only show rows where @columnReference('Location')='US' for everyone.

When using this function, match the casing of the column name you specify with the column name in the remote platform and escape the following characters with a backslash: \, ', ", ` .

This function should not be used to reference column names in external lookup tables. Instead, use the fully-qualified column name for external lookup tables.

Parameter

Parameter	Description	Required or optional
Column name string	The name of the column to use in the policy.	Required

The @columnTagged() function

This function returns the column name with the specified tag.

If this function is used in a global policy and the tag doesn't exist on a data source, the policy will not be applied.

Parameters

Parameter	Description	Required or optional
Tag name string	The name of the tag.	Required

The @groupsContains() function

This function returns true for a given row if the provided column evaluates to a group to which the querying user belongs. This function requires at least one argument.

Parameters

Parameter	Description	Required or optional
@columnReference('Column_Name') string	The column that contains the value to match the group against.	Required
Placeholder string	A placeholder in case the list of values is empty.	Optional

The @hasAttribute() function

This function returns a boolean indicating if the current user has the specified attribute name and value combination. If the specified attribute name or attribute value has a single quote, you will need to escape it using a \'\' expression within a custom WHERE policy.

Parameters

Parameter	Description	Required or optional
Attribute name string	The name of the attribute.	Required
Attribute value string	The value to correspond with the attribute name.	Required

The @isInGroups() function

This function returns a boolean indicating if the current user is a member of all of the specified groups. If any of the specified groups has a single quote, you will need to escape it using a \'\' expression within a custom WHERE policy.

Parameter

Parameter	Description	Required or optional
Group names array[string]	A list of group names. For example, groups('group_a', 'group_b', 'group_c').	Required

The @isUsingPurpose() function

This function returns a boolean indicating if the current user is using the specified purpose. If the specified purpose has a single quote, you will need to escape it using a \'\' expression within a custom WHERE policy.

Parameter

Parameter	Description	Required or optional
Purpose string	The name of the purpose to check the user against.	Required

The @purposesContains() function

This function returns true for a given row if the provided column evaluates to a purpose under which the querying user is currently acting. This function requires at least one argument and accepts no more than two arguments.

Parameters

Parameter	Description	Required or optional
@columnReference('Column_Name') string	The column that contains the value to match the purpose against.	Required
Placeholder string	A placeholder in case the list of values is empty.	Optional

The @username function

This function returns the current user's username.

Parameters

None.