Page tree
Skip to end of metadata
Go to start of metadata

This article provides a tutorial on how to create and apply a Data Permissions filter. A Data Permissions filter is a data access control that you apply to one or more users. This filter is defined within a project and is based on the value of an attribute. It can be applied to one or more users in the project to control the data that is visible to them.

Data Permissions were formerly called Mandatory User Filters.

This article demonstrates by way of example. For more information on Data Permissions in general, see Data Permissions for Beginners.


Suppose your company has multiple departments: Engineering, Accounting, HR, Legal, Product Management, and more.

Suppose you would like to create a report yet want to define a filter for the specific user. Each user of the report should see only data that pertains to their specific department, as the other data in the report does not apply to them and may, in fact, be sensitive.

In the following steps, this filter is created and applied to the report.

Data Permissions filter concepts

Suppose the report looks like the following before any Data Permissions filter is applied:

When the Data Permissions filter is created, it filters the report by a specific attribute element (attribute value).

Attribute = Department 
Attribute element = Human Resources

You may define a Data Permissions filter based on attribute elements only. You may not filter the contents of the report by metric value. 

The Basics

The Data Permissions filter is a standard object in our platform with a URI. You can configure it using an available API or locate it using the gray pages at md/query/ context.

The basic steps to create and configure it are the following:

  1. Create a new user filter object
  2. Assign the user filter object to the user or users
  3. Verify the functionality

After you have created and assigned the Data Permissions to the current set of users in the project, you may wish to apply the Data Permissions filters to new users that you invite to the project. For more information on that workflow, see Inviting Users with Pre-Applied Data Permissions.

Creating a New Mandatory Filter

To create a new Mandatory Filter object, you must be logged as an Admin to the project where you are creating it.

Creating a new Mandatory Filter is very similar to other API calls. You must define the JSON request and POST it to the specific resource:

The API resource for creating new Data Permissions is the following:{project-id}/obj

Here is the basic JSON payload:

    "userFilter": {
        "content": {
            "expression": "[/gdc/md/{project-id}/obj/{object-id}]=[/gdc/md/{project-id}/obj/{object-id}/elements?id={element-id}]"
        "meta": {
            "category": "userFilter",
            "title": "My User Filter Name"

They key part is in the expression statement, where you define an expression for the given user filter. Inside the expression, you may use the following operators:

  • =
  • <>
  • IN
  • NOT IN

The limit on the length of a filter expression is 100,000 characters. 

You must acquire the identifiers for the attribute and the attribute element. These values are available through the gray pages for your project. Go to following page:{project-id}/query/attributes

Select the attribute and find the URI, which is located in the meta section.

For the attribute element corresponding to the Human Resources Department, use the elements link to display a list of all attribute elements. Locate it and its identifier in the JSON payload shown above.

After the POST has been submitted to create the Data Permissions filter, the API response is an HTTP Status Code 200, with the URI of newly created Data Permissions filter.

Verify that the Data Permissions filter has been created by calling GET to the following resource:{project-id}/obj/{created-object-id}

Filter propagation across the dataset

When you define a Data Permission filter for one attribute in a dataset, it impacts the available values in the other attributes of the dataset.

Suppose your dataset looks like the following:

JJ Dean, Inc.PortlandMaine10020
U. Gene, Inc.EugeneOregon9040
Sactown Example, Inc.SacramentoCalifornia11045

For some user, you create a permission filter that looks like the following:

State = "Oregon"

Since the attribute applies across all attributes in the dataset, the values for the City attribute are limited to Portland and Eugene only.

The drop-down would not contain the Sacramento value, since it is not part of the Oregon set of values and is thus not part of the hierarchy of city and state information for the state of Oregon. Note that there is another row with an instance of Portland in the data. However, since this instance is associated with the state of Maine, that row of data is filtered out of the results.

This propagation simplifies the development and maintenance of Data Permissions filters. Instead of creating multiple filter expressions to manage this hierarchy, you must create only one expression.

Limitations of filter propagation

  • Data Permissions filters do not propagate to linked Date dimensions.
  • Data Permissions filters do not propagate to other datasets linked to the specified dataset.
  • You can enable this feature for your project at /gdc/md/{project-id}/service/datasetMufs.

Assign the Data Permissions filter to the user object

After the new filter defined, you assign it to a user based on the user’s internal identifier within the project. These identifiers are located here:

You can find all users in the project and select the corresponding identifier.

The following resource and payload connects the user to the user filter.

You may specify multiple filters for one user.{project-id}/userfilters
    "userFilters": {
        "items": [
                "user": "/gdc/account/profile/{user-id}",
                "userFilters": [

In the JSON response, you can identify if the filter has been applied to the user:

  "userFiltersUpdateResult": {
      "failed": [],
      "successful": [

At this point, the filter has been applied to the user. So, any report that is passed back to the user should have this filter applied to it. To verify:

The filter has been applied. Please let us know how this works for you.

To more information about Data Permissions, see Create Data Permissions.