> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# mask_unless_access_grants - Dimensions

> Masks dimension values with SHA-256 hash when users don't meet specified access grants.

Defines a list of [access grants](/modeling/models/access-grants) for the dimension that determine whether values should be masked. When a user doesn't satisfy the specified access grants, dimension values are replaced with a SHA-256 hash. Unlike [`required_access_grants`](/modeling/dimensions/parameters/required-access-grants), which blocks access to the field entirely, this parameter allows users to see masked values.

This parameter is useful when you want to:

* Allow users to perform aggregations and analysis on sensitive data without exposing the actual values
* Enable joins and grouping on sensitive fields while protecting personally identifiable information (PII)
* Maintain data structure and relationships in queries while masking sensitive information

## Syntax

```yaml theme={null}
<dimension_name>:
  mask_unless_access_grants: [<grants_and_conditions>]
  mask_format:
    prefix: <string>
    length: <integer>
```

## Properties

<ParamField path="dimension_name" type="object[]">
  The name of the dimension.

  <Expandable title="dimension_name properties" defaultOpen="true">
    <ParamField path="mask_unless_access_grants" type="string[]">
      An array of access grant names that control data masking for the dimension. Each value must match an [access grant](/modeling/models/access-grants) defined in the model file. When the user doesn't satisfy the access grants, values are replaced with a SHA-256 hash.

      Use `|` for `OR` conditions and `&` for `AND` conditions within the same array element.
    </ParamField>

    <ParamField path="mask_format" type="object">
      Shortens the masked hash and optionally labels it with a prefix, instead of always showing the full 64-character hash. Requires `mask_unless_access_grants` to also be set on the dimension; otherwise, there is no effect.

      Each distinct dimension value still produces one distinct masked output, so grouping, sorting, filtering, pivoting, and drilling continue to work on the masked column, whether or not `mask_format` is set. Join conditions skip masking entirely, with or without `mask_format`.

      <Expandable title="mask_format properties">
        <ParamField path="prefix" type="string">
          Text placed before the hash, for example `person-`.
        </ParamField>

        <ParamField path="length" type="integer" default="64">
          Number of hex characters of the hash to keep, from 1 to 64. Defaults to 64, which is the full hash.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Mask data unless user has marketing access" theme={null}
customer_email:
  mask_unless_access_grants: [marketing]
```

```yaml title="Mask data unless user has marketing OR sales access" theme={null}
customer_email:
  mask_unless_access_grants: [marketing|sales]
```

```yaml title="Mask data unless user has marketing OR (sales AND product) access" theme={null}
customer_email:
  mask_unless_access_grants: [marketing|sales&product]
```

```yaml title="Shorten and label the masked value" theme={null}
user_name:
  sql: ${users.name}
  mask_unless_access_grants: [see_pii]
  mask_format:
    prefix: person-
    length: 16
```

This produces a masked value like `person-3f9a2c1b4d21e07a`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.