Identity filter API

The Identity filter API allows you to create a visual that can filter categorical data using a semantic query.
It filters the data by data points rather than mathematical expressions.

The API keeps track of user selections and which data points to display. The data points are saved in an array and referenced by their position in the array.

This API is useful in the following scenarios:

• For custom visuals that use semantic models with group on keys
• Migrating visuals that used an older API (earlier than 2.2) to a newer API
• Allow selections using identifying index arrays

Note

The Identity filter API is available from API version 5.1 To find out which version you’re using, check the apiVersion in the pbiviz.json file.

The Identity filter model is based on the IIdentityFilter interface.

TypeScript

    private filter: IIdentityFilter = {
        $schema: “”,
        filterType: FilterType.Identity,
        operator: "In",
        target: []
    }

For example, if the visual received the following data view update:

The array is of type number[] and it contains the identity fields of the items that the user selected.

The identityIndex corresponds to the index of the value in the semantic model's value array (see the following example).

In the above example: {identityIndex: 0} = "Aaliyah" {identityIndex: 1} = "Aaliyah" {identityIndex: 02 = "Aaliyah" etc.

How to use the Identity filter API

To use the Identity filter API, your powerbi-models version needs to be 1.9.1 or higher.

• Add the following property as a member of the visual.ts class:

  TypeScript

      private filter: IIdentityFilter = {
          $schema: “”,
          filterType: FilterType.Identity,
          operator: "In",
          target: []
      }
  

• To handle Power BI updates, read the target array from the 'jsonFilters' in the 'VisualUpdateOptions' and translate it to the corresponding values. These values are the ones that were selected. In the previous example, a target array of [0,10] corresponds to the values of Aliyah and Abigail.

• To handle user selections in the previous example, click on the first Abigail to add the value 8 to the filter target array and send it using the following command:

TypeScript

this.visualHost.applyJsonFilter(this.filter, "general", "filter", powerbi.FilterAction.merge);

Migrating visuals with old API

Starting from API 5.1.0, to support the identity filter on visuals that were created using a version earlier than 2.2, add the following lines to your capabilities.json file:

JSON

    "migration": {
        "filter": {
            "shouldUseIdentityFilter": true
        }
    }

These lines convert the selections to identity filters.

Note

This step is only necessary for existing visuals created with older APIs. Newer visuals don't need to add this.

Related content

Use Power BI visuals selections to add interactivity to a visual

More questions? Try the Power BI Community.