Filters

If a report contains filters and a community connector returns unfiltered data for all fields requested then Data Studio will apply filters to the connector response. However, filters can be applied at the community connector level which can significantly improve performance in some cases. Filter information is passed in the getData() request object, and the connector can use this information to filter data before sending it back to Data Studio.

For example, if you're connecting to a SQL database, applying the filters directly in the WHERE clause (B3 in diagram below) can drastically decrease the number of rows returned to Data Studio. This, in turn, limits the amount of data that has to be processed and sent to Data Studio (B5).

Filter flowchart

Rules of applying filters

  1. Apply all filters, or none of them. See Unsupported filters
  2. Do not include forFilterOnly fields in the response.
  3. AND together each entry in the request.dimensionsFilters array.

    For example, for the following filter, the connector should only include values that have a country of USA AND a source of Social.

    {
      "dimensionsFilters": [
        [{
          "fieldName": "country",
          "values": ["USA"],
          "type": "INCLUDE",
          "operator": "EQUALS"
        }],
        [{
          "fieldName": "source",
          "values": ["Social"],
          "type": "INCLUDE",
          "operator": "EQUALS"
        }]
      ]
    }
    
  4. OR together each sub-array in the request.dimensionsFilters array.

    For example, for the following filter, the connector should only include values that have a country of USA OR a country of Canada.

    {
      "dimensionsFilters": [
        [{
          "fieldName": "country",
          "values": ["Canada"],
          "type": "INCLUDE",
          "operator": "EQUALS"
        }, {
          "fieldName": "country",
          "values": ["USA"],
          "type": "INCLUDE",
          "operator": "EQUALS"
        }]
      ]
    }
    

Example

The following example illustrates an end-to-end flow from the report user defining filters to the community connector returning filtered data.

Example Filter

  1. The report user has configured two filters:

    1. country is IN_LIST of Canada, USA
    2. source is IN_LIST of Social, Organic
  2. The report user has configured a chart component with the source dimension and sessions metric

  3. getData() is executed by Data Studio with the following request object:

    {
      "fields": [
        {"name": "source"},
        {"name": "sessions"},
        {"name": "country", "forFilterOnly": true}
      ],
      "dimensionsFilters": [
        [{
          "fieldName": "country",
          "values": ["Canada", "USA"],
          "type": "INCLUDE",
          "operator": "IN_LIST"
        }],
        [{
          "fieldName": "source",
          "values": ["Social", "Organic"],
          "type": "INCLUDE",
          "operator": "IN_LIST"
        }]
      ]
    }
    
  4. Connector responds with filtered data.

    For the example request, return the source and sessions where country is "Canada" or "USA" AND the source is "Social" or "Organic". Set filtersApplied to true since all filters were able to be successfully applied.

Original data

source sessions country
Social 60 USA
Social 50 Canada
Social 40 UK
Organic 90 USA
Organic 80 Canada
Organic 70 UK
Newspaper 30 USA
Newspaper 20 Canada
Newspaper 10 UK

Filtered data

source sessions
Social 60
Social 50
Organic 90
Organic 80

getData() response

{
  "schema": [
    {"name": "source",   "dataType": "STRING"},
    {"name": "sessions", "dataType": "NUMBER"},
  ],
  "rows": [
    {"values": ["Social", 60]},
    {"values": ["Social", 50]},
    {"values": ["Organic", 90]},
    {"values": ["Organic", 80]}
  ],
  "filtersApplied": true
}

Unsupported filters

If the connector cannot apply all filters in the request, no filtering should be performed. Return all of the requested fields (including the forFilterOnly fields) and set the filtersApplied key in your response to false.

Example:

{
  "schema": [
    {"name": "source",   "dataType": "STRING"},
    {"name": "sessions", "dataType": "NUMBER"},
    {"name": "country",  "dataType": "STRING"}
  ],
  "rows": [
    {"values": ["Social", 60, "USA"]},
    {"values": ["Social", 50, "Canada"]},
    {"values": ["Social", 40, "UK"]},
    {"values": ["Organic", 90, "USA"]},
    {"values": ["Organic", 80, "Canada"]},
    {"values": ["Organic", 70, "UK"]},
    {"values": ["Newspaper", 30, "USA"]},
    {"values": ["Newspaper", 20, "Canada"]},
    {"values": ["Newspaper", 10, "UK"]},
  ],
  "filtersApplied": false
}