Subsets

Subsets are a way to slice the dataset based on predefined criteria. They consist of an identifier and one or more filters. The identifier is used in the requests to ILSA: ?_subset=identifier.

An important aspect of subsets is that they are considered before applying any normal filters. This is best explained with an example:

Suppose you have separate sections for used and new vehicles on your site. To get the number of available exterior colours for the used vehicles you might be tempted to use /dropdowncontents?_fields=body.colour.primary&condition.used=true resulting in:

{
	"num_results": 139,
	"fields": {
		"body.colour.primary": [
			{"key": "black", "display_value": "Black", "count": 93},
			{"key": "white", "display_value": "White", "count": 46},
			{"key": "red",   "display_value": "Red",   "count": 0}
		]
	}
}

Notice the 0 results for red? Apparently there are red vehicles in the dataset, but none of them match the given filter (condition.used=true). In this case the option “red” should not be shown, because there is no way for the visitor to ever get a red vehicle in the search results.

Now let’s define a subset with identifier usedvehicles that uses the filter condition.used=true. This allows you to pass ?_subset=usedvehicles to every ILSA request. The request above would now be /dropdowncontents?_fields=body.colour.primary&_subset=usedvehicles, resulting in:

{
	"num_results": 139,
	"fields": {
		"body.colour.primary": [
			{"key": "black", "display_value": "Black", "count": 93},
			{"key": "white", "display_value": "White", "count": 46}
		]
	}
}

ILSA now first applies the subset (removing all new vehicles) and then proceeds normally with the regular filters (of which there are currently none). Since there are no red vehicles in the usedvehicles dataset, this option is not returned. The other options are unchanged.

It is important to know when to use static filters, subsets and normal filters.

Static filters should be used to reject vehicles that should never be on your site. This improves performance, reduces costs and gives proper feedback to your advertisers.
Subsets should be used if you want to split your dataset in one or more slices, for example on satellite websites.
Regular filters should only be used to pass the search criteria of a website visitor to ILSA.

If you need different filters, ordering and fieldsets for your website sections or satellite websites it’s better to use a different instances instead of subsets.

Static filters vs subsets vs filters