API/behavior changes

This PRD extends the filterableAttributes setting format, allowing users to customize filters with more granularity.

⚠️ Activating a feature on a field can impact the indexing time! The goal of this new API is to reduce the average indexing time by allowing the user to activate only the needed features, we should strongly advise him to choose wisely what should be activated or not depending on the needs. The worst case scenario would be to activate everything for every fields.

Format change

The filterableAttributes support a new format expressed as below:

{
	"filterableAttributes": [
	  {
	    "attributePatterns": ["genre", "artist"], 
	    "features": { "facetSearch": true, "filter": {"equality": true, "comparison": false } }
	  },
	  {
	    "attributePatterns": ["*rank"],
	    "features": { "facetSearch": false, "filter": {"equality": true, "comparison": true } }
	  },
	  {
	    "attributePatterns": ["albumId"],
	    "features": { "facetSearch": false, "filter": {"equality": true, "comparison": false } }
	  },
	]
}

Attributes description

attributePatterns

Like localizedAttributes, Attribute patterns may begin or end with a * wildcard to match multiple fields: en_*, *-ar. If a field matches several patterns, only the features of the first matching pattern in the list will be applied to the field.

features

The object containing the features that can be activated for the fields matching the upper attributePatterns:

• facetSearch : allows the field to be searchable by the facet search route, if the facet search is globally deactivated with the facetSearch setting, then the feature is ignored. (activating this feature implies creating a dedicated facet-search database), variants:
  • false: Deactivate the facet search on the matching fields
  • true: Activate facet search
• filter: deactivate or customize the filtering for the matching fields
  • equality: allows the field to be filterable using only the =, != EXISTS, IN, NOT, AND, or OR operators (This is a low-cost filter that should be encouraged over orderFilter)
  • comparison: allows the field to be filterable using the >, >=, <, <=, TO, EXISTS, IN, NOT, AND, or OR operators (activating this feature implies creating the level-based database for the field (high-cost))
  • contains (Future possibility 🔭): allows the field to be filterable using the =, != EXISTS, IN, NOT, AND OR or CONTAINS operators
• sortFacetValuesBy (Future possibility 🔭): overrides the sortFacetValuesBy fields of the faceting settings for the fields matching the patterns. Adding it here would be more relevant regarding API design but deprecates sortFacetValuesBy fields of the faceting settings. Variants:
  • alpha: Facet distribution is ordered lexicographically
  • count: Facet distribution is ordered by count (activating this feature implies creating the level-based database for the field (high-cost))

Default behavior features

"filterableAttributes": [
	{
	  "attributePatterns": ["albumId"]
	}
]

would be equivalent to the low-cost filtering:

"filterableAttributes": [
	{
	  "attributePatterns": ["albumId"],
		"features": { "facetSearch": false, "filter": {"equality": true, "comparison": false } }  
	}
]

Forcing the user to activate the features depending on his needs. However, for retro-compatibility reasons, the old way of specifying filterableAttributes (array):