Set Up Data Filters in Workspaces

Workspace Data Filters (WDF) allow you to limit the data available in child workspaces. By setting a WDF, you can define what subset of the data from a parent workspace will be available in its child workspaces. For example, a parent workspace may contain a visualization displaying the data from all company departments, but a child workspace will see only the Sales department-related data in this visualization.

Child workspaces inherit the WDFs from their parent workspace the same way they inherit any other entity through the workspace hierarchy.

Only organization administrators can set up WDFs.

How Workspace Data Filters Work

A WDF relies on the following information:

• The parent workspace that holds the data that is to be limited in the child workspaces
• The child workspaces to apply the filter to (those can be direct child workspaces as well as their respective child workspaces at any hierarchy level downwards)
• The filter value assigned to a child workspace that acts as a condition for distinguishing whether the data should be available in this workspace
• Mapping rule that defines the column to look for in tables in a connected data source that holds the values to be compared to the filter value

The WDF uses the filter value assigned to a child workspace to distinguish what data should be made available in this workspace. The WDF compares the filter value to the values in the specified column in the data source tables.

If the filter value matches the column value for some data record in a table, this record is made available in this workspace. The data records not matching the filter value are not available in the child workspace.

The LDM definition must contain mapping rules that explicitly define which filter value is to be applied to which dataset. These filter mapping rules can be added in the data modeller and then activated in the dataset details.

• Data records with no value in the specified column are treated as not meeting the filter condition and are not available in the workspace.
• If a WDF is set up and a filter value for the child workspace is missing, report executions will result in a 400 status code error with a prompt to specify the filter value.
• If a WDF is set on a column in a dataset but a report is created without using this dataset, the filter won’t have any impact and no data will be filtered by it.

The data modeler automatically creates mapping rules between the dataset and the WDF if the dataset’s underlying table or SQL query contains a column defined in the WDF. This process eliminates the need for manual rule creation but only applies when creating a new dataset. If you use the wdf__ prefix in a database column name, it prevents the data modeler from generating dataset objects (such as facts or attributes) from that column. Its values are therefore not available for building insights. However, the column remains accessible for WDFs. This approach enables the automatic creation of a dataset with a linked WDF without converting the filtered column into a dataset object.

Only users with the Organization.MANAGE permission or the Workspace.MANAGE hierarchyPermission can create, read, update, or delete WDFs.

Example: Imagine that you have the following workspace hierarchy:

Head Office
  |---> Western
    |---> California

You want to define what data will be available in each workspace:

• In the Head Office parent workspace, all the data should be available.
• In the Western workspace, which is a child workspace of Head Office, only the data related to the western United States should be available.
• In the California workspace, which is a child workspace of Western, only the data related to California should be available.

The following WDFs will help you achieve your goal:

• A WDF that filters the data in the Western workspace by region

  When the WDF is applied, the Western workspace should be able to access only the data that meets the filter condition (that is, related to the Western region).

  • The parent workspace is Head Office.
  • The child workspace is Western.
  • The filter is mapped to the column wdf__region.
  • The filter value is West.

• A WDF that filters the data in the California workspace by state

  When the WDF is applied, the California workspace should be able to access only the data that meets the filter condition (that is, related to California).

  • The parent workspace is Western.
  • The child workspace is California.
  • The filter is mapped to the column wdf__state.
  • The filter value is California.

The following picture shows how a visualization in the Western workspace looks like comparing to the same visualization in the Head Office workspace when the WDF that filters the data in the Western workspace by region is applied:

Set Up Workspace Data Filters

To create the root-child workspace structure from the previous section, create a WDF wdf__region where the <parent_workspace_id> is Head Office and the <child-workspace-id> is Western.

Note that you need at least a Workspace.MANAGE level hierarchyPermission to the workspaces you are setting up the data filters for.

Steps:

Follow this procedure to create a new WDF for a workspace and apply it to its child workspace.

1. Create a new WDF and its settings using the following API call:

   curl $HOST_URL/api/v1/entities/workspaces/<parent_workspace_id>/workspaceDataFilters \
     -H "Authorization: Bearer $API_TOKEN" \
     -H "Content-Type: application/vnd.gooddata.api+json" \
     -X POST -d '
   {
     "data": {
       "id": "<data-filter-id>",
       "type": "workspaceDataFilter",
       "attributes": {
         "columnName": "<column-name>",
         "title": "<data-filter-name>"
       }
     }
   }
     '
   

   where:

   • <parent_workspace_id> is the ID of the parent workspace for whose child workspaces you are setting up the WDFs.
   • <data-filter-id> is some unique ID for the WDF.
   • <column-name> is currently used to automatically apply WDFs to LDMs. Its purpose will change in the future.
   • <data-filter-name> is the UI-friendly name of the data filter.

   ColumnName Usage

   The attribute columnName is in the process of being repurposed. Currently, it remains a required field and is used to automatically apply WDFs to LDMs, but it is no longer used to apply filters to a specific column. To do that, you must explicitly apply the filter to a source column in the dataset’s Data filtering tab, as described in the subsequent steps.

2. Define the WDF value for a child workspace:

   curl $HOST_URL/api/v1/entities/workspaces/<child-workspace-id>/workspaceDataFilterSettings \
     -H "Authorization: Bearer $API_TOKEN" \
     -H "Content-Type: application/vnd.gooddata.api+json" \
     -X POST -d '
   {
     "data": {
       "id": "<data-filter-setting-id>",
       "type": "workspaceDataFilterSetting",
       "attributes": {
         "filterValues": [
           "<filter-value>"
         ],
         "title": "<data-filter-condition-name>"
       },
       "relationships": {
         "workspaceDataFilter": {
           "data": {
             "id": "<data-filter-id>",
             "type": "workspaceDataFilter"
           }
         }
       }
     }
   }
     '
   

   where:

   • <child-workspace-id> is the ID of the child workspace that the WDF with the specified condition is applied to.
   • <data-filter-setting-id> is some unique ID for the WDF setting.
   • <data-filter-condition-name> is the UI-friendly name of the WDF condition.
   • <filter-value> is a value that acts as a condition for distinguishing whether the data should be available in the child workspace. You can define multiple values to filter for.

   Your basic filtering is set up, but in order for it to work you still need to explicitely assign this filter to a specific dataset.

3. Open your parent workspace in the LDM modeler and Edit it.

   Note that a Workspace data filters panel is available in all workspaces with at least one WDF. For the purposes of this example we chose to name our WDF Region:

   
   

4. Find the dataset that you want to filter in your child workspaces and go to More … > View details.

   
   

5. Switch to the Data filtering tab, Enable the WDF and Map it to the appropriate source column that you want to use for your filtering.

   
   

6. Click Save changes.

   Your WDF is now applied to your dataset:

   
   

7. Save the changes you made to your logical data model.

   Your sales data should now be filtered in your child workspace.

curl -v $TEST_HOST/api/v1/layout/workspaces/<parent_workspace_id>/logicalModel \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${API_TOKEN}" \
-X PUT \
-d '{
"ldm": {
  "datasets": [],
  "datasetExtensions": [
    {
      "id": "<dataset-id>",
      "workspaceDataFilterReferences": [
        {
          "filterId": {
            "id": "wdf__state",
            "type": "workspaceDataFilter"
          },
          "filterColumn": "wdf__state",
          "filterColumnDataType": "STRING"
        }
      ]
    }
  ]
}
}'