Filters

If a report contains filters and a community connector returns unfiltered data for all fields requested then Looker 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 Looker 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 Looker Studio. This, in turn, limits the amount of data that has to be processed and sent to Looker Studio (B5).

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.

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 Looker 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

Filtered data

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
}