# 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')**](#the-columnreference-function) `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

{% hint style="info" %}
**Feature flag required**

To use this function, add the following YAML to the **Advanced Configuration** on the [app settings page](https://documentation.immuta.com/latest/configuration/application-settings/how-to-guides/config-builder-guide#enable-the-columnreference-function):

```yaml
featureFlags:
  antlrFreeParsing: true
```

Once you enable this feature flag,

1. Immuta migrates all existing custom WHERE clause policies that reference column names (and apply to Snowflake and Databricks data sources) to use the `@columnReference` function. You will no longer be able to use the legacy syntax:
   * Before migration: `Only show rows where 'Location'='US'`
   * After migration: `Only show rows where @columnReference('Location')='US'`
2. Ensure that any automations pushing policy updates use the new `@columnReference` syntax.
   {% endhint %}

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')**](#the-columnreference-function) `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.

### Parameters

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

### Parameters

| 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')**](#the-columnreference-function) `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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/latest/governance/author-policies-for-data-access-control/authoring-policies-in-secure/data-policies/reference-guides/custom-where-clause-functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.