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.

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
• The name of 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 WDF is applied only to the tables that contain the specified column. If a table does not have the column, the filter is not applied, and all the data from the table is available in the workspace.
• 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, but a child workspace does not have any value specified, no data is available in this workspace.

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 column name is 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 name of the column is 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

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

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

Steps:

1. Create a new WDF 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 the name of the column in a connected data source that holds the values to be compared to the filter value specified in the <filter-value> parameter that you will define in the next step (for more information, see How Data Filters Work).
   • <data-filter-name> is the UI-friendly name of the data filter.

   ColumnName Deprecation

   The attribute columnName is in the process of being deprecated. Currently, it remains a required field, but it is not 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. Apply the WDF to a child workspace using the following API call:

   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.