API Reference / API Parameters / searchableAttributes
Feb. 26, 2019


Type: list of strings
Engine default: [] (all string attributes)
Formerly: attributesToIndex
Parameter syntax
'searchableAttributes' => [
  'attribute2, attribute3', // both attributes have the same priority
  'unordered(attribute5, attribute6)'

Can be used in these methods:

About this parameter

The complete list of attributes that will be used for searching.

This setting is critical to establishing good relevance, for 2 main reasons:

  • Limits the scope of a search to the attributes listed in this setting. Defining specific attributes as searchable is critical for relevance because it gives you direct control over what information (i.e., attributes) the search engine will look at. Not every attribute in your index is useful for search; for example, some attributes contain URLs, others are used for display purposes only. Such attributes are not relevant to search. With this setting, you guide the engine to search only those attributes relevant to search.
  • Creates an order of priority for every listed attribute that the engine uses to improve relevance. The order in which the attributes appear determine their search priority. The engine will start searching your index using the first attributes in the list. If it finds a sufficient number of records, it stops and returns the results. If it doesn’t find enough records, it will continue searching using the next set of attributes, and so on.

Usage notes:

  • Default/Empty list: If you don’t use this setting, or use it with an empty list, the engine will search for all attributes.
  • Same Priority: You can create the same priority by putting more than one attribute in the same string.
  • Ordering: In addition to creating attribute-level priority, you can also determine how the engine is going to search within an attribute. The engine favors matches at the beginning of an attribute by default, but you can change it to ignore positioning and consider any match within an attribute of equal importance. See below.
  • Nested attributes: When you specify an attribute that has children attributes, all of them will be indexed. If you don’t want the full nest to be searched, you can reference a child attribute, for example: categories.lvl0.child_attribute.sub_child_attribute


  • unordered: There is no preference: any match anywhere in the attribute has the same weight.

    By default, searchable attributes are set as ordered: matches at the beginning of an attribute are more important than in the middle, and matches in the middle are more important than towards the end. Setting them as unordered cancels out this behavior.

    Note that you can’t set searchable attributes with same priority but only modifying some of them. You can’t have modified and unmodified searchable attributes on the same line (e.g., 'unordered(attribute1), attribute2' isn’t valid).


Set searchableAttributes

The following example shows how to:

  • make some attributes searchable,
  • put several attributes at the same level,
  • set an attribute as unordered,
  • search only a child attribute.
  'searchableAttributes' => [

Did you find this page helpful?