Configure Query Settings search features

16 min read

Query settings search features include options that determine what information should be sent in the query. Empathy Platform offers the following query settings features:

Faceting: Categorizes the results based on fields sent in the request.
Filtering: Delimits the results based on field values sent in the request.
Mandatory Parameters: Validates if a parameter has been included in the request.

interact

For an explanation on how to set up the features in the Search microservice, see Feature configuration.

Faceting

The Faceting (faceting) feature offers the ability to create facets for specific fields. The Faceting feature supports three types of facets: value (standard), range, and hierarchical.

Facets can be determined using:

Query parameters
Empathy Platform Playboard configuration (for navigation only)
Search configuration file

The order of preference is query parameters, then Playboard configuration (for the navigation experience only), and finally, Search configuration file. All facetable fields must be set up in the Search configuration file.

The order of the facets in the response is determined by the mechanism used for faceting. However, when using the query parameter, the order received in the service may not be the same as that the shopper sent in the request.

Important

You must have set up either a searchconfiguration or browseconfiguration collection in Elasticsearch, depending on the context (navigation or search). The endpoint returns a 500 Internal Server error code if the collection does not exist.

Query parameters

You can pass the facet to return in the response by using the facet query parameter. For example, to return the facet gender, use facet=gender. To return multiple facets, use multiple facet parameters, e.g. facet=gender&facet=brand.

You can deactivate facets for a single request by using the facets query parameter.

note

The facets query parameter overrides the enabled property in the Search configuration.

If the facet parameter is informed in the request, you can boost or bury facet values by adding the parameters f.{FACET_FIELD}.boosts and f.{FACET_FIELD}.buries, respectively (where {FACET_FIELD} represents the value of the name of the facet field). For example, to boost the gender facet field women, you use the query parameters facet=gender&f.gender.boosts=women.

To boost or bury multiple values, you separate the values by commas. The order of the values is maintained in the response. When boosting, the first value is the first one in the response. When burying, the first value is the last one in the response.
For example, to boost the brands nike and addidas in the Brand facet, where Nike appears before Addidas: facet=brand&f.brand.boosts=nike,addidas.

You can use the f.{FACET_FIELD}.sort parameter to sort each facet value in the request, either alphabetically or by the number of filters. For example, to sort gender facet values alphabetically: facet=gender&f.gender.sort=ALPHABETICALLY.

Important

All facet fields must be set up in the Search configuration to operate as query parameters. Otherwise, a 400 Bad Request error code is returned by the endpoint.

Field	Description	Type
`facet`	Facet field to return in the response	String
`facets`	Determines whether facets are enabled or not (case-insensitive). If it is set to `false`, the response won't include the `facets` section. If no value is set, the facets are returned. If you enter a value other than those accepted, the endpoint returns an exception.	Boolean
`f.{FACET_FIELD}.boosts`	Boosts the facet fields specified. Fields are separated by commas	Array
`f.{FACET_FIELD}.buries`	Buries the facet field specified. Fields are separated by commas	Array
`f.{FACET_FIELD}.sort`	Sorts the facets in the order specified. Facets can be sorted by `RESULTS_NUMBER` or `ALPHABETICALLY`	String

Playboard configuration

The Empathy Platform Playboard lets merchandisers configure the facets displayed in the Navigation experience using the Navigation configuration tool.

To determine the fields that can be used as facets in the Playboard:

the context must be set as Browse,
the facet field must be set up in the field parameter in the search configuration file, and
the field must be linked as a facetable field in the Playboard configuration.

Facet configuration for navigation can be applied hierarchically, so a parent configuration is applied over children where there is no specific configuration for the children. You can sort facet values by number of results or alphabetically. You can also you boost or bury specific facet values, so they appear at the top or at the bottom of the list in the Empathy Platform Playboard Configuration tool.

Using Faceting with Browsing Search

To retrieve the Playboard configuration of the navigation experience, you must pass the browseField and browseValue query parameters in the request. The browseField parameter must contain the field used for navigation and browseValue must contain the value of the navigation field. To set up the navigation experience, see Browsing Search.

Search configuration

The Search configuration file contains the default configuration that is used where no values are passed as query parameters or retrieved from the Empathy Platform Playboard.

All facetable fields must be included in the Search configuration file in the facets parameter. If the field is not present in the configuration and a request is sent with a facet query parameter, a 400 Bad Request error code is returned.

The facetableFields parameter determines the type of facet used: value, range, or hierarchical. You must indicate a value for facetableFields. Within each facet type, you determine the name of the field to be used as a facet in the field parameter and the name of the filter field in filterField.

Using Faceting with Filtering

When faceting is used with filtering, filtering should be executed first so that the filters are also applied to facets. Filter queries must have the same name as the filtered field. This means that filterField must use the same name as the queryParam configured in the filtering feature.

To be able to retrieve the facets set up in the Search configuration file in the Empathy Platform Playboard so they can be configured, you must set the context of the request and include all the required parameters. The context should be set as BROWSE when adding a navigation endpoint.
The SEARCH context is used for facets for the search experience and must be associated with a search endpoint. The query parameter is required for the search experience.

Config parameters

Field	Description	Type	Default value
`context`	Determines the context to use: `SEARCH` or `BROWSE` (required)	String	---
`facetableFields`	List of allowed fields to be used as facets (optional)	Array	---
`facets`	List of fields to be configured as facets (optional)	Array	Empty list
`enabled`	Enables or deactivates facets (required)	Boolean	---
`mainCollectionId`	Collection name used to compose the name of the index collection to search on (required)	String	---
`secondaryCollectionId`	Secondary collection name used to compose the name of the index collection to search on (required)	String	---

Facetable Fields parameters

Field	Description	Type	Default value
`rangeFacets`	List of allowed fields to be used as range facets	Array	Empty list
`valueFacets`	List of allowed fields to be used as value facets	Array	Empty list
`hierarchicalFacets`	List of allowed fields to be used as hierarchical facets	Array	Empty list

Value facets (valueFacets) show a list of textual values for an attribute. You determine the field and filterField values, and indicate the number of values to be returned (minCount, size).

Value Facets parameters

Field	Description	Type	Default value
`field`	Name of the field to facet. Fields must be `keyword` type in the index	String	---
`filterField`	Name of the field to filter the facet. Fields must be `keyword` type in the index	String	---
`minCount`	Minimum number of results for each facet value to appear in the response	Integer	1
`size`	Maximum number of facet values to appear in the response	Integer	100

Configuration example

{
  "name": "faceting",
  "config": {
    "context": "SEARCH",
    "mainCollectionId": "collection",
    "secondaryCollectionId": "secondaryCollection",
    "enabled": true,
    "facetableFields": {
      "valueFacets": [
        {
          "field": "field1",
          "filterField": "filterField1",
          "size": 100,
          "minCount": 1
        }
      ]
    },
    "facets": [
      "field1"
    ]
  }
}

Range facets (rangeFacets) present facet values on a range. Range facets use numeric values. You determine the field and filterField values and establish the upper and lower limits for the range (ranges).

Range Facets parameters

Field	Description	Type	Default value
`field`	Name of the field to facet. Field must be `numeric` type in the index	String	---
`filterField`	Name of the field to filter the facet. Fields must be `keyword` type in the index	String	---
`ranges`	List of ranges to be applied	Array	---

Ranges parameters

Field	Description	Type	Default value
`from`	Lower limit to use for a range	Integer	---
`to`	Upper limit to use for a range	Integer	---
`gap`	Interval used to divide up the range. Only used if `from` and `to` are informed	Integer	---

Configuration example

{
  "name": "faceting",
  "config": {
    "context": "SEARCH",
    "mainCollectionId": "collection",
    "secondaryCollectionId": "secondaryCollection",
    "enabled": true,
    "facetableFields": {
      "rangeFacets": [
        {
          "field": "numericField",
          "ranges": [
            {
              "to": 10,
              "gap": 10
            },
            {
              "from": 10,
              "to": 100,
              "gap": 50
            },
            {
              "from": 100,
              "gap": 10
            }
          ]
        }
      ]
    },
    "facets": [
      "numericField"
    ]
  }
}

Hierachical facets organize categories into subfacets for a more granular filtering experience. They establish a parent-child relationship between facets that allows shoppers to drill down from a general category to a more specific category. For hierarchical facets, each value in the hierarchy must have a name and an ID. For example:

- Pantry:01
  - Baking+%26+Cooking: 01012
    - Cake+%26+Brownie+Mix: 0101200004

The field must be stored in the index according to a specific format:

"facetField": [
"/Pantry|01",
"01/Baking+%26+Cooking|01__01012",
"01__01012/Cake+%26+Brownie+Mix|01__01012__0101200004"
]

This block indicates the path where the document belongs. It contains the following information:

Items that start with / are the first level of items.
The ID of the parent item is found before the / symbol (e.g. 01).
The escaped value of the facet is found after the / (e.g. Pantry).
The separator | is used after the value, followed by the ID corresponding to that item (e.g. 01012).
The stored ID must contain all the IDs from the root to the current value, separated by double underscore __.

coding tip

As the characters /, | and __ have a special meaning for hierarchical facets, make sure facet fields do not contain them as part of their names or IDs. In that case, you should process those characters using the client index plugin.

Hierarchical Facets parameters

Field	Description	Type	Default value
`field`	Name of the field to facet. Fields must be `keyword` type in the index	String	-
`filterField`	Name of the field to filter the facet. Fields must be `keyword` type in the index	String	-
`minCount`	Minimum number of results for each facet value to appear in the response	Integer	1
`size`	Maximum number of facet values that will appear in the response	Integer	100

To facilitate the filtering of the facet, a separated filterField is used, where only IDs are stored. For example:

"filterField": [
"01",
"01__01012",
"01__01012__0101200004"
]

Filtering

The Filtering (filtering) feature adds the ability to filter the results based on field-value and numeric range criteria.

Important

Faceting and Total hits features depend on filtering. For more information, see Faceting and Total hits.

Filters can be sent in two ways:

filter parameter value: using the format: filter=field:value or filter=field:from-to.
Query parameter: using the format field=value or field=from-to.

If a request contains filters in two formats, the values inside filter parameter have preference. For example, if the color is sent as a query parameter (color=red) and as a filter parameter (filter=color:blue) in the request color=red&filter=color:blue, only the blue color is filtered.

If the request contains multiple filters on various attributes, all of filters are evaluated (AND operation relationship). For example, if the request contains filter=color:red&filter=size:L&filter=price:5-5.99, the results are filtered to show only those that match the color red, size L, and a price range of €5 to €5.99.

For multi-value/multi-range filters, by default a single match is enough to consider the result valid (OR relationship). You can change this behavior using the operation configuration parameter. For example, if you configure the operation parameter as OR, when the request is filter=color:red&filter=color:blue, it shows results that match either the color red or the color blue.

If you want to use exclude results using filters, you need to send an exclusion filter in the request in the format exclude_configuredFieldName. For example, to filter results by color, showing those that match red and strictly excluding any results that match blue, the parameters are filter=color:red&filter=exclude_color:blue.

Field	Description	Type
`filter`	Field to be used as filter. Available formats: `filter=field:value` or `filter=field:from-to`	String
`exclude_`	Field to be used to exclude. Format: `filter=exclude_field:value`	String

Search configuration

The fields used to filter the results are configured either in the request or in the JSON configuration file of the feature. If a required filter is not included in the request, a bad request error is returned in the response.

Config parameters

Field	Description	Type	Default value
`fields`	List of allowed fields to be used as filter. It cannot be null or empty (required)	Array	-

Fields parameters

Field	Description	Type	Default value
`name`	Name of the field to filter. It cannot be null or empty (required)	String	-
`queryParam`	Name of the query parameter (optional)	String	The value specified in `name`
`type`	Type of the filter. It can be either `VALUE` or `RANGE`. It cannot be null. It must be written in upper case (required)	String	-
`mandatory`	Specifies if the filter must be provided in the request. Possible values: `true` (the filter is included in all the requests) or `false` (the filter is not included in all the requests) (optional)	Boolean	`false`
`exclusion`	Specifies if the filter is an exclusion filter. Possible values: `true` or `false` (optional)	Boolean	`false`
`operation`	Operation to be applied to different values of the same filter. It can be `AND` or `OR`	String	`OR`

Configuration example

{
  "name": "filtering",
  "config": {
    "fields": [
      {
        "name": "brandCode",
        "queryParam": "brand",
        "type": "VALUE",
        "operation": "OR"
      },
      {
        "name": "price",
        "type": "RANGE",
        "mandatory": true
      },
      {
        "name": "brandName",
        "type": "VALUE",
        "exclusion": true
      }
    ]
  }
}

Mandatory Parameters

The Mandatory Parameters (mandatoryparameters) feature adds the ability to check if a given parameter has been included in the request. It returns an 400 Bad Request error if the parameter missing.

Search configuration

The fields to be validated as mandatory are included in the mandatoryFields parameter.

Field	Description	Type	Default value
`mandatoryFields`	List of fields that must be present in the request	Array	Empty list

Configuration example

{
  "name": "mandatoryparameters",
  "config": {
    "mandatoryFields": [
      "store",
      "lang"
    ]
  }
}

Query Settings features

Faceting

Query parameters

Playboard configuration

Search configuration

Value facets

Range facets

Hierarchical facets

Filtering

Search configuration

Mandatory Parameters

Search configuration