Set Up Data Filters for Users

Overview

User Data Filters (UDF), also referred to as user data permissions or row-level security, allow you to restrict data that are available for specific users in specific workspaces.

By setting a UDF, you can define what subset of the data in a workspace will be available for individual users or user groups.

As opposed to workspace data filters (that point to a specific column in a specific table), user data filters use MAQL expressions. This offers you more flexibility in creating complex conditions because UDFs are applied to any connected data rather than specific database columns.

Multiple User Data Filters

You can restrict data for individual users and user groups, or combine them.

The effective filters for individual users are inherited from all user groups that the user is a member of throughout the workspace hierarchy.

For example, if a user is a member of any user groups and filters are created for these groups as well, then also all filters from these groups are applied (using the AND operator).

User data filters

Set Up User Data Filters

You can set up user UDFs via:

  • Entity API

    This enables you to create, replace, update, and delete individual UDFs.

  • Declarative API

    This enables you to update a complete set of UDFs.

To set up UDFs, do the following:

  1. Create a JSON document.
  2. Add the JSON document to the workspace.

Create JSON Document

Entity API
Declarative API

Use the following template to create a JSON document that describes the UDFs that you want to apply:

{
 "data": {
   "type": "userDataFilter",
   "id": "<data-filter-id>",
   "attributes": {
     "maql": "<maql-expression>",
     "title": "<data-filter-name>"
   },
   "relationships": {
     "user": {
       "data": {
         "id": "<user-id>",
         "type": "user"
       }
     }
   }
 }
}
  • <data-filter-id> is the unique ID of the UDF.
  • <maql-expression> is the definition of the filters using MAQL.
  • <data-filter-name> is the UI-friendly name of the UDF.
  • <user-id> is the ID of the user that the UDF with the specified condition is applied to.

Example: A sample JSON document.

{
 "data": {
   "type": "userDataFilter",
   "id": "filter1",
   "attributes": {
     "maql": "{label/l_linestatus} = \"O\"",
     "title": "Status filter"
   },
   "relationships": {
     "user": {
       "data": {
         "id": "user1",
         "type": "user"
       }
     }
   }
 }
}

Use the following template to create a JSON document that describes the UDFs that you want to apply:

{
 "userDataFilters": [
   {
     "id": "<data-filter-id>",
     "maql": "<maql-expression>",
     "title": "<data-filter-name>",
     "user": {
       "id": "<user-id>",
       "type": "user"
     }
   }
 ]
}
  • <data-filter-id> is the unique ID of the UDF.
  • <maql-expression> is the definition of the filters using MAQL.
  • <data-filter-name> is the UI-friendly name of the UDF.
  • <user-id> is the ID of the user that the UDF with the specified condition is applied to.

Example: A sample JSON document.

{
 "userDataFilters": [
   {
     "id": "filter1",
     "maql": "{label/l_linestatus} = \"O\"",
     "title": "Status filter",
     "user": {
       "id": "user1",
       "type": "user"
     }
   }
 ]
}

Add JSON Document to Workspace

Entity API
Declarative API

To add the UDF to the workspace, run the following:

curl $HOST_URL/api/v1/entities/workspaces/<workspace-id>/userDataFilters \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/vnd.gooddata.api+json" \
 -d @/path/to/your-filter-definition.json

To list all UDFs that are created in the workspace, run the following:

curl $HOST_URL/api/v1/entities/workspaces/<workspace-id>/userDataFilters/ \
-H "Authorization: Bearer $API_TOKEN"

To update the UDF, run the following:

curl $HOST_URL/api/v1/layout/workspaces/<workspace-id>/userDataFilters \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
 -d @/path/to/your-filter-definition.json