Filters

AI-generated Key Takeaways

• Looker Studio can apply filters to data from community connectors, but applying filters within the connector itself can significantly enhance performance.

• Community connectors should apply all filters provided in the getData() request or none at all, and structure them with AND and OR logic as specified.

• If a connector cannot apply all filters, it should return all data and indicate filtersApplied: false in the response, ensuring backward compatibility.

• When filters are successfully applied within the connector, the response should exclude forFilterOnly fields and include filtersApplied: true.

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).

Note: It's not required to apply filters, but it is recommended if you expect performance gains from applying them.

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"
       }]
     ]
   }
   

Caution: The difference between OR and AND is subtle. AND has the structure [[1], [2]], whereas OR has the structure [[1, 2]]

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

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
}

Key Point: response.rows[].values does not have an entry for country and filtersApplied is set to 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.

Key Point: This is the standard response for getData(). All existing connectors are backwards compatible with this change.

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
}