Android

Parameters

Overview

Scope

Each parameter in this page has a scope. Depending on the scope, you can use the parameter within the setSettings and/or the search method.

There are three scopes:

  • settings: The setting can only be used in the setSettings method.
  • search: The setting can only be used in the search method.
  • settings search: The setting can be used in the setSettings method and be overridden in thesearch method.

Parameters List

Search

Attributes

Ranking

Filtering / Faceting

Highlighting / Snippeting

Pagination

Typos

Geo-Search

Query Strategy

Performance

Advanced

query

scope search
type string
default ""
description

The text to search for in the index. If empty or absent, the textual search will match any object.

Attributes

searchableAttributes

scope settings
type array of strings
default [] (all string attributes)
formerly known as attributesToIndex
description

List of attributes eligible for textual search. In search engine parlance, those attributes will be “indexed”, i.e. their content will be made searchable.

If not specified or empty, all string values of all attributes are indexed. If specified, only the specified attributes are indexed; any numerical values within those attributes are converted to strings and indexed.

When an attribute is listed, it is recursively processed, i.e. all of its nested attributes, at any depth, are indexed according to the same policy.

Make sure you adjust this setting to get optimal results.

This parameter has two important uses:

  1. Limit the scope of the search. Restricting the searchable attributes to those containing meaningful text guarantees a better relevance. For example, if your objects have associated pictures, you need to store the picture URLs in the records in order to retrieve them for display at query time, but you probably don’t want to search inside the URLs.

    A side effect of limiting the attributes is increased performance: it keeps the index size at a minimum, which has a direct and positive impact on both build time and search speed.

  2. Control part of the ranking. The contents of the searchableAttributes parameter impacts ranking in two complementary ways:

    • Attribute priority: The order in which attributes are listed defines their ranking priority: matches in attributes at the beginning of the list will be considered more important than matches in attributes further down the list.

      To assign the same priority to several attributes, pass them within the same string, separated by commas. For example, by specifying ["title,alternative_title", "text"], title and alternative_title will have the same priority, but a higher priority than text.

    • Importance of word positions: Within a given attribute, matches near the beginning of the text are considered more important than matches near the end. You can disable this behavior by wrapping your attribute name inside an unordered() modifier. For example, ["title", "unordered(text)"] will consider all positions inside the text attribute as equal, but positions inside the title attribute will still matter.

To get a full description of how the ranking works, you can have a look at our Ranking guide.

attributesForFaceting

scope settings
type array of strings
default []
description

List of attributes you want to use for faceting.

All strings within these attributes will be extracted and added as facets. If not specified or empty, no attribute will be faceted.

If you only need to filter on a given facet, but are not interested in value counts for this facet, you can improve performances by specifying filterOnly(${attributeName}). This decreases the size of the index and the time required to build it.

If you want to search inside values of a given facet (using the Search for facet values method) you need to specify searchable(${attributeName}).

The filterOnly() and searchable() modifiers are mutually exclusive.

unretrievableAttributes

scope settings
type array of strings
default []
description

List of attributes that cannot be retrieved at query time.

These attributes can still be used for indexing and/or ranking.

This setting is bypassed when the query is authenticated with the admin API key.

attributesToRetrieve

scope settings search
type array of strings
default * (all attributes)
formerly known as attributes
description

List of object attributes you want to retrieve. This can be used to minimize the size of the response.

You can use * to retrieve all values.

objectID is always retrieved, even when not specified.

Attributes listed in unretrievableAttributes will not be retrieved even if requested, unless the request is authenticated with the admin API key.

restrictSearchableAttributes

scope search
type array of strings
default all attributes in searchableAttributes
description

List of attributes to be considered for textual search.

It must be a subset of the searchableAttributes index setting. Consequently, searchableAttributes must not be empty nor null for restrictSearchableAttributes to be allowed.

restrictSearchableAttributes is a search time parameter, it will only affect the current query. It will not override your index settings.

Ranking

ranking

scope settings
type array of strings
default ["typo", "geo", "words", "filters", "proximity", "attribute", "exact", "custom"]
description

Controls the way results are sorted.

You must specify a list of ranking criteria. They will be applied in sequence by the tie-breaking algorithm in the order they are specified.

The following ranking criteria are available:

  • typo: Sort by increasing number of typos.
  • geo: Sort by decreasing geo distance when performing a geo search. This criterion is ignored when not performing a geo search.
  • words: Sort by decreasing number of matched query words. This parameter is useful when you use the optionalWords query parameter to rank hits with the most matched words first.
  • filters: The filter criteria is the sum of scores for filters matched by one hit. In case of OR filters, only one score is taken in account even if the two filters match.
  • proximity: Sort by increasing proximity of query words in hits.
  • attribute: Sort according to the order of attributes defined by searchableAttributes.
  • exact:
    • If the query contains only one word: The behavior depends on the value of exactOnSingleWordQuery.
    • If the query contains multiple words: Sort by decreasing number of words that matched exactly. What is considered to be an exact match depends on the value of alternativesAsExact.
  • custom: Sort according to a user-defined formula specified via the customRanking setting.
  • Sort by value of a numeric attribute. Here, ${attributeName} can be the name of any numeric attribute in your objects (integer, floating-point or boolean).
    • asc(${attributeName}): sort by increasing value of the attribute
    • desc(${attributeName}): sort by decreasing value of the attribute

To get a full description of how the ranking works, you can have a look at our Ranking guide.

customRanking

scope settings
type array of strings
default []
description

Specifies the custom ranking criterion.

Each string must conform to the syntax asc(${attributeName}) or desc(${attributeName}) and specifies a (respectively) increasing or decreasing sort on an attribute. All sorts are applied in sequence by the tie-breaking algorithm in the order they are specified.

Example: ["desc(population)", "asc(name)"] will sort by decreasing value of the population attribute, then in case of equality by increasing value of the name attribute.

To get a full description of how custom ranking works, you can have a look at our Ranking guide.

replicas

scope settings
type array of strings
default []
formerly known as slaves
description

List of indices to which you want to replicate all write operations.

In order to get relevant results in milliseconds, we pre-compute part of the ranking during indexing. Consequently, if you want to use different ranking formulas depending on the use case, you need to create one index per ranking formula.

This option allows you to perform write operations on a single, master index and automatically perform the same operations on all of its replicas.

A master index can have as many replicas as needed. However, a replica can only have one master; in other words, two master indices cannot have the same replica. Furthermore, a replica cannot have its own replicas (i.e. you cannot “chain” replicas).

Filtering / Faceting

filters

scope search
type string
default ""
description

Filter the query with numeric, facet and/or tag filters.

This parameter uses a SQL-like expression syntax, where you can use boolean operators and parentheses to combine individual filters.

The following individual filters are supported:

  • Numeric filter:

    • Comparison: ${attributeName} ${operator} ${operand} matches all objects where the specified numeric attribute satisfies the numeric condition expressed by the operator and the operand. The operand must be a numeric value. Supported operators are <, <=, =, !=, >= and >, with the same semantics as in virtually all programming languages. Example: inStock > 0.

    • Range: ${attributeName}:${lowerBound} TO ${upperBound} matches all objects where the specified numeric attribute is within the range [${lowerBound}, ${upperBound}] (inclusive on both ends). Example: publication_date: 1441745506 TO 1441755506.

  • Facet filter: ${facetName}:${facetValue} matches all objects containing exactly the specified value in the specified facet attribute. Facet matching is case sensitive. Example: category:Book.

  • Tag filter: _tags:${value} (or, alternatively, just ${value}) matches all objects containing exactly the specified value in their _tags attribute. Tag matching is case sensitive. Example: _tags:published.

Individual filters can be combined via boolean operators. The following operators are supported:

  • OR: must match any of the combined conditions (disjunction)
  • AND: must match all of the combined conditions (conjunction)
  • NOT: negate a filter

Finally, parentheses (( and )) can be used for grouping.

Putting it all together, an example is:

available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:"John Doe"

Keywords are case-sensitive.

If no attribute name is specified, the filter applies to _tags. For example: public OR user_42 will translate into _tags:public OR _tags:user_42.

If a value contains spaces, or conflicts with a keyword, you can use double quotes.

If a filtered attribute contains an array of values, any matching value will cause the filter to match.

For performance reasons, filter expressions are limited to a disjunction of conjunctions. In other words, you can have ANDs of ORs (e.g. filter1 AND (filter2 OR filter3)), but not ORs of ANDs (e.g. filter1 OR (filter2 AND filter3).

You cannot mix different filter categories inside a disjunction (OR). For example, num=3 OR tag1 OR facet:value is not allowed.

You cannot negate a group of filters, only an individual filter. For example, NOT(filter1 OR filter2) is not allowed.

facets

scope search
type array of strings
default []
description

Facets to retrieve. If not specified or empty, no facets are retrieved. The special value * may be used to retrieve all facets.

Facets must have been declared beforehand in the attributesForFaceting index setting.

For each of the retrieved facets, the response will contain a list of the most frequent facet values in objects matching the current query. Each value will be returned with its associated count (number of matched objects containing that value).

Faceting does not filter your results. If you want to filter results, you should use filters.

Example:

If your settings contain:

{
  "attributesForFaceting": ["category", "author", "nb_views", "nb_downloads"]
}

… but, for the current search, you want to retrieve facet values only for category and author, then you can specify:

"facets": ["category", "author"]

If the number of hits is high, facet counts may be approximate. The response field exhaustiveFacetsCount is true when the count is exact.

maxValuesPerFacet

scope settings search
type integer
default 100
description

Maximum number of facet values returned for each facet.

The API enforces a hard limit of 1000 on maxValuesPerFacet. Any value above that limit will be interpreted as 1000.

facetFilters

scope search
type array of strings
default []
description

Filter hits by facet value.

The filters parameter provides an easier to use, SQL-like syntax. We recommend using it instead of facetFilters.

Each string represents a filter on a given facet value. It must follow the syntax ${attributeName}:${value}.

If you specify multiple filters, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

Examples:

  • ["category:Book", "author:John Doe"] translates as category:Book AND author:"John Doe"
  • [["category:Book", "category:Movie"], "author:John Doe"] translates as (category:Book OR category:Movie) AND author:"John Doe"

Negation is supported by prefixing the value with a minus sign (-, a.k.a. dash). For example: ["category:Book", "category:-Movie"] translates as category:Book AND NOT category:Movie.

facetingAfterDistinct

scope search
type boolean
default false
description

Force faceting to be applied after de-duplication.

When using the distinct setting in combination with faceting, facet counts may be higher than expected. This is because the engine computes faceting before applying de-duplication (distinct).

When facetingAfterDistinct is set to true, you force faceting to be computed after de-duplication has been applied.

Please take precautions, though, and carefully read the limitations:

  • You should not use facetingAfterDistinct=true if you don’t have the same facet values in all records sharing the same distinct key (you would get inconsistent results).
  • facetingAfterDistinct can only be set at query time; it can’t be added as a default setting of the index.
  • facetingAfterDistinct will be ignored if you also set typoTolerance to either strict or min.
  • When the query string is empty, faceting will still happen before de-duplication, regardless of facetingAfterDistinct. In that case, we therefore recommend you to fall back to a distinct-less query.

Highlighting / Snippeting

attributesToHighlight

scope settings search
type array of strings
default all searchable attributes
description

List of attributes to highlight. If set to null, all searchable attributes are highlighted (see searchableAttributes). The special value * may be used to highlight all attributes.

Only string values can be highlighted. Numerics will be ignored.

When highlighting is enabled, each hit in the response will contain an additional _highlightResult object (provided that at least one of its attributes is highlighted) with the following fields:

  • value (string): Markup text with occurrences highlighted. The tags used for highlighting are specified via highlightPreTag and highlightPostTag.

  • matchLevel (string, enum) = {none | partial | full}: Indicates how well the attribute matched the search query.

  • matchedWords (array): List of words from the query that matched the object.

  • fullyHighlighted (boolean): Whether the entire attribute value is highlighted.

attributesToSnippet

scope settings search
type array of strings
default [] (no attribute is snippeted)
description

List of attributes to snippet, with an optional maximum number of words to snippet. If set to null, no attributes are snippeted. The special value * may be used to snippet all attributes.

The syntax for each attribute is ${attributeName}:${nbWords}. The number of words can be omitted, and defaults to 10.

Only string values can be snippeted. Numerics will be ignored.

When snippeting is enabled, each hit in the response will contain an additional _snippetResult object (provided that at least one of its attributes is snippeted) with the following fields:

  • value (string): Markup text with occurrences highlighted and optional ellipsis indicators. The tags used for highlighting are specified via highlightPreTag and highlightPostTag. The text used to indicate ellipsis is specified via snippetEllipsisText.

  • matchLevel (string, enum) = {none | partial | full}: Indicates how well the attribute matched the search query.

highlightPreTag

scope settings search
type string
default "<em>"
description

String inserted before highlighted parts in highlight and snippet results.

highlightPostTag

scope settings search
type string
default "</em>"
description

String inserted after highlighted parts in highlight and snippet results.

snippetEllipsisText

scope settings search
type string
default (U+2026)
description

String used as an ellipsis indicator when a snippet is truncated.

Defaults to an empty string for all accounts created before February 10th, 2016. Defaults to (U+2026, HORIZONTAL ELLIPSIS) for accounts created after that date.

restrictHighlightAndSnippetArrays

scope settings search
type boolean
default false
description

When true, restrict arrays in highlight and snippet results to items that matched the query at least partially. When false, return all array items in highlight and snippet results.

Pagination

page

scope search
type integer
default 0
description

Number of the page to retrieve.

Page numbers are zero-based. Therefore, in order to retrieve the 10th page, you need to set page=9.

hitsPerPage

scope settings search
type integer
default 20
description

Maximum number of hits per page.

offset

scope search
type integer
default null
description

Offset of the first hit to return (zero-based).

In most cases, page/hitsPerPage is the recommended method for pagination.

length

scope search
type integer
default null
description

Maximum number of hits to return.

In most cases, page/hitsPerPage is the recommended method for pagination.

paginationLimitedTo

scope settings
type integer
default 1000
description

Maximum number of hits accessible via pagination. By default, this parameter is set to 1000 to guarantee good performance.

We recommend keeping the default value to guarantee excellent performance. Increasing the pagination limit will have a direct impact on the performance of search queries. A too high value will also make it very easy for anyone to retrieve (“scrape”) your entire dataset.

Typos

minWordSizefor1Typo

scope settings search
type integer
default 4
description

Minimum number of characters a word in the query string must contain to accept matches with one typo.

minWordSizefor2Typos

scope settings search
type integer
default 8
description

Minimum number of characters a word in the query string must contain to accept matches with two typos.

typoTolerance

scope settings search
type string | boolean
default true
description

Controls whether typo tolerance is enabled and how it is applied:

  • TYPO_TRUE: Typo tolerance is enabled and all matching hits are retrieved (default behavior).

  • TYPO_FALSE: Typo tolerance is entirely disabled. Hits matching with only typos are not retrieved.

  • TYPO_MIN: Only keep results with the minimum number of typos. For example, if just one hit matches without typos, then all hits with only typos are not retrieved.

  • TYPO_STRICT: Hits matching with 2 typos or more are not retrieved if there are some hits matching without typos. This option is useful to avoid “false positives” as much as possible.

allowTyposOnNumericTokens

scope settings search
type boolean
default true
description

Whether to allow typos on numbers (“numeric tokens”) in the query string.

When false, typo tolerance is disabled on numeric tokens. For example, the query 304 will match 30450 but not 40450 (which would have been the case with typo tolerance enabled).

This option can be very useful on serial numbers and zip codes searches.

ignorePlurals

scope settings search
type boolean | array of strings
default false
description

Consider singular and plurals forms a match without typo. For example, “car” and “cars”, or “foot” and “feet” will be considered equivalent.

This parameter may be:

  • a boolean: enable or disable plurals for all supported languages;
  • a list of language ISO codes for which plurals should be enabled.

This option is set to false by default.

List of supported languages with their associated ISO code:

Afrikaans=af, Arabic=ar, Azeri=az, Bulgarian=bg, Catalan=ca, Czech=cs, Welsh=cy, Danis=da, German=de, English=en, Esperanto=eo, Spanish=es, Estonian=et, Basque=eu, Finnish=fi, Faroese=fo, French=fr, Galician=gl, Hebrew=he, Hindi=hi, Hungarian=hu, Armenian=hy, Indonesian=id, Icelandic=is, Italian=it, Japanese=ja, Georgian=ka, Kazakh=kk, Korean=ko, Kyrgyz=ky, Lithuanian=lt, Maori=mi, Mongolian=mn, Marathi=mr, Malay=ms, Maltese=mt, Norwegian=nb, Dutch=nl, Northern Sotho=ns, Polish=pl, Pashto=ps, Portuguese=pt, Quechua=qu, Romanian=ro, Russian=ru, Slovak=sk, Albanian=sq, Swedish=sv, Swahili=sw, Tamil=ta, Telugu=te, Tagalog=tl, Tswana=tn, Turkish=tr, Tatar=tt

disableTypoToleranceOnAttributes

scope settings search
type array of strings
default []
description

List of attributes on which you want to disable typo tolerance (must be a subset of the searchableAttributes index setting).

disableTypoToleranceOnWords

scope settings
type array of strings
default []
description

List of words on which typo tolerance will be disabled.

separatorsToIndex

scope settings
type string
default ""
description

Separators (punctuation characters) to index.

By default, separators are not indexed.

Example: Use +# to be able to search for “Google+” or “C#”.

Geo search requires that you provide at least one geo location in each record at indexing time, under the _geoloc attribute. Each location must be an object with two numeric lat and lng attributes. You may specify either one location:

{
  "_geoloc": {
    "lat": 48.853409,
    "lng": 2.348800
  }
}

… or an array of locations:

{
  "_geoloc": [
    {
      "lat": 48.853409,
      "lng": 2.348800
    },
    {
      "lat": 48.547456,
      "lng": 2.972075
    }
  ]
}

When performing a geo search (either via aroundLatLng or aroundLatLngViaIP), the maximum distance is automatically guessed based on the density of the searched area. You may explicitly specify a maximum distance, however, via aroundRadius.

The precision for the ranking is set via aroundPrecision.

aroundLatLng

scope search
type (latitude, longitude) pair
default null
description

Search for entries around a given location (specified as two floats separated by a comma).

For example, aroundLatLng=47.316669,5.016670.

aroundLatLngViaIP

scope search
type boolean
default false
description

Search for entries around a given location automatically computed from the requester’s IP address.

If you are sending the request from your servers, you must set the X-Forwarded-For HTTP header with the client’s IP address for it to be used as the basis for the computation of the search location.

aroundRadius

scope search
type integer | "all"
default null
description

Maximum radius for geo search (in meters).

If set, only hits within the specified radius from the searched location will be returned.

If not set, the radius is automatically computed from the density of the searched area. You can retrieve the computed radius in the automaticRadius response field. You may also specify a minimum value for the automatic radius via minimumAroundRadius.

The special value all causes the geo distance to be computed and taken into account for ranking, but without filtering; this option is faster than specifying a high integer value.

aroundPrecision

scope search
type integer
default 1
description

Precision of geo search (in meters).

When ranking hits, geo distances are grouped into ranges of aroundPrecision size. All hits within the same range are considered equal with respect to the geo ranking parameter.

For example, if you set aroundPrecision to 100, any two objects lying in the range [0, 99m] from the searched location will be considered equal; same for [100, 199], [200, 299], etc.

minimumAroundRadius

scope search
type integer
default null
description

Minimum radius used for a geo search when aroundRadius is not set.

This parameter is ignored when aroundRadius is set.

insideBoundingBox

scope search
type geo rectangle(s)
default null
description

Search inside a rectangular area (in geo coordinates).

The rectange is defined by two diagonally opposite points (hereafter p1 and p2), hence by 4 floats: p1Lat, p1Lng, p2Lat, p2Lng.

For example:

insideBoundingBox=47.3165,4.9665,47.3424,5.0201

You may specify multiple bounding boxes, in which case the search will use the union (OR) of the rectangles. To specify multiple rectangles, pass either:

  • more than 4 values (must be a multiple of 4: 8, 12…); example: 47.3165,4.9665,47.3424,5.0201,40.9234,2.1185,38.6430,1.9916; or
  • an array of arrays of floats (each inner array must contain exactly 4 values); example: [[47.3165, 4.9665, 47.3424, 5.0201], [40.9234, 2.1185, 38.6430, 1.9916].

insidePolygon

scope search
type geo polygon(s)
default null
description

Search inside a polygon (in geo coordinates).

The polygon is defined by a set of points (minimum 3), each defined by its latitude and longitude. You therefore need an even number of floats, with a minimum of 6: p1Lat, p1Lng, p2Lat, p2Lng, p3Lat, p3Long.

For example:

insidePolygon=47.3165,4.9665,47.3424,5.0201,47.32,4.98

You may specify multiple polygons, in which case the search will use the union (OR) of the polygons. To specify multiple polygons, pass an array of arrays of floats (each inner array must contain an even number of values, with a minimum of 6); example: [[47.3165, 4.9665, 47.3424, 5.0201, 47.32, 4.9], [40.9234, 2.1185, 38.6430, 1.9916, 39.2587, 2.0104]].

Query Strategy

queryType

scope search settings
type string
default "prefixLast"
description

Controls if and how query words are interpreted as prefixes.

It may be one of the following values:

  • PREFIX_LAST: Only the last word is interpreted as a prefix (default behavior).

  • PREFIX_ALL: All query words are interpreted as prefixes. This option is not recommended, as it tends to yield counterintuitive results and has a negative impact on performance.

  • PREFIX_NONE: No query word is interpreted as a prefix. This option is not recommended, especially in an instant search setup, as the user will have to type the entire word(s) before getting any relevant results.

removeWordsIfNoResults

scope settings search
type string
default "none"
description

Selects a strategy to remove words from the query when it doesn’t match any hits.

The goal is to avoid empty results by progressively loosening the query until hits are matched.

There are four different options:

  • REMOVE_NONE: No specific processing is done when a query does not return any results (default behavior).

  • REMOVE_LAST_WORDS: When a query does not return any results, treat the last word as optional. The process is repeated with words N-1, N-2, etc. until there are results, or the beginning of the query string has been reached.

  • REMOVE_FIRST_WORDS: When a query does not return any results, treat the first word as optional. The process is repeated with words 2, 3, etc. until there are results, or the end of the query string has been reached.

  • REMOVE_ALL_OPTIONAL: When a query does not return any results, make a second attempt treating all words as optional. This is equivalent to transforming the implicit AND operator applied between query words to an OR.

advancedSyntax

scope settings search
type boolean
default false
description

Enables the advanced query syntax.

This advanced syntax brings two additional features:

  • Phrase query: a specific sequence of terms that must be matched next to one another. A phrase query needs to be surrounded by double quotes ("). For example, "search engine" will only match records having search next to engine.

    Typo tolerance is disabled inside the phrase (i.e. within the quotes).

  • Prohibit operator: excludes records that contain a specific term. This term has to be prefixed by a minus (-, a.k.a dash). For example, search -engine will only match records containing search but not engine.

optionalWords

scope settings search
type string | array of strings
default []
description

List of words that should be considered as optional when found in the query.

This parameter can be useful when you want to do an OR between all words of the query. To do that you can set optionalWords equals to the search query.

var query = 'the query';
var params = {'optionalWords': query};

You don’t need to put commas between words. Each string will automatically be tokenized into words, all of which will be considered as optional.

removeStopWords

scope settings search
type boolean | array of strings
default false
description

Remove stop words from the query before executing it.

This parameter may be:

  • a boolean: enable or disable stop words for all supported languages; or
  • a list of language ISO codes for which stop word removal should be enabled.

In most use-cases, we don’t recommend enabling stop word removal.

Stop word removal is useful when you have a query in natural language, e.g. “what is a record?”. In that case, the engine will remove “what”, “is” and “a” before executing the query, and therefore just search for “record”. This will remove false positives caused by stop words, especially when combined with optional words (see optionalWords and removeWordsIfNoResults). For most use cases, however, it is better not to use this feature, as people tend to search by keywords on search engines (i.e. they naturally omit stop words).

Stop words removal is only applied on query words that are not interpreted as prefixes.

As a consequence, the behavior of removeStopWords also depends on the queryType parameter:

  • queryType=prefixLast means the last query word is a prefix and won’t be considered for stop word removal;
  • queryType=prefixNone means no query word is a prefix, therefore stop word removal will be applied to all query words;
  • queryType=prefixAll means all query words are prefixes, therefore no stop words will be removed.

List of supported languages with their associated ISO code:

Arabic=ar, Armenian=hy, Basque=eu, Bengali=bn, Brazilian=pt-br, Bulgarian=bg, Catalan=ca, Chinese=zh, Czech=cs, Danish=da, Dutch=nl, English=en, Finnish=fi, French=fr, Galician=gl, German=de, Greek=el, Hindi=hi, Hungarian=hu, Indonesian=id, Irish=ga, Italian=it, Japanese=ja, Korean=ko, Kurdish=ku, Latvian=lv, Lithuanian=lt, Marathi=mr, Norwegian=no, Persian (Farsi)=fa, Polish=pl, Portugese=pt, Romanian=ro, Russian=ru, Slovak=sk, Spanish=es, Swedish=sv, Thai=th, Turkish=tr, Ukranian=uk, Urdu=ur.

disablePrefixOnAttributes

scope settings
type array of strings
default []
description

List of attributes on which you want to disable prefix matching (must be a subset of the searchableAttributes index setting).

This setting is useful on attributes that contain string that should not be matched as a prefix (for example a product SKU).

disableExactOnAttributes

scope settings
type search
default []
description

List of attributes on which you want to disable computation of the exact ranking criterion (must be a subset of the searchableAttributes index setting).

exactOnSingleWordQuery

scope settings search
type string
default attribute
description

Controls how the exact ranking criterion is computed when the query contains only one word.

The following values are allowed:

  • none: the exact ranking criterion is ignored on single word queries;
  • word: the exact ranking criterion is set to 1 if the query word is found in the record. The query word must be at least 3 characters long and must not be a stop word in any supported language.
  • attribute (default): the exact ranking criterion is set to 1 if the query string exactly matches an entire attribute value. For example, if you search for the TV show “V”, you want it to match the query “V” before all popular TV shows starting with the letter V.

alternativesAsExact

scope setting search
type array of strings
default ["ignorePlurals", "singleWordSynonym"]
description

List of alternatives that should be considered an exact match by the exact ranking criterion.

The following values are allowed:

  • ignorePlurals: alternative words added by the ignorePlurals feature;
  • singleWordSynonym: single-word synonyms (example: “NY” = “NYC”);
  • multiWordsSynonym: multiple-words synonyms (example: “NY” = “New York”).

Performance

numericAttributesForFiltering

scope settings
type array of strings
default all numeric attributes
formerly known as numericAttributesToIndex
description

List of numeric attributes that can be used as numerical filters.

If not specified, all numeric attributes are automatically indexed and available as numerical filters (via the filters parameter). If specified, only attributes explicitly listed are available as numerical filters. If empty, no numerical filters are allowed.

If you don’t need filtering on some of your numerical attributes, you can use numericAttributesForFiltering to speed up the indexing.

If you only need to filter on a numeric value based on equality (i.e. with the operators = or !=), you can speed up the indexing by specifying equalOnly(${attributeName}). Other operators will be disabled.

allowCompressionOfIntegerArray

scope settings
type boolean
default false
description

Enables compression of large integer arrays.

In data-intensive use-cases, we recommended enabling this feature to reach a better compression ratio on arrays exclusively containing integers (as is typical of lists of user IDs or ACLs).

When enabled, integer arrays may be reordered.

Advanced

attributeForDistinct

scope settings
type string
default null
description

Name of the de-duplication attribute for the distinct feature.

distinct

scope settings search
type integer | boolean
default 0
description

Controls de-duplication of results.

A non-zero value enables de-duplication; a zero value disables it. Booleans are also accepted (though not recommended): false is treated as 0, and true is treated as 1.

De-duplication requires a de-duplication attribute to be configured via the attributeForDistinct index setting. If not configured, distinct will be accepted at query time but silently ignored.

This feature is similar to the SQL distinct keyword. When set to N (where N > 0), at most N hits will be returned with the same value for the de-duplication attribute.

Example: If the de-duplication attribute is show_name and distinct is set to 1, then if several hits have the same value for show_name, only the most relevant one is kept (with respect to the ranking formula); the others are removed.

To get a full understanding of how distinct works, you can have a look at our Guides.

getRankingInfo

scope search
type boolean
default false
description

Enables detailed ranking information.

When true, each hit in the response contains an additional _rankingInfo object containing the following fields:

  • nbTypos (integer): Number of typos encountered when matching the record. Corresponds to the typos ranking criterion in the ranking formula.

  • firstMatchedWord (integer): Position of the most important matched attribute in the attributes to index list. Corresponds to the attribute ranking criterion in the ranking formula.

  • proximityDistance (integer): When the query contains more than one word, the sum of the distances between matched words. Corresponds to the proximity criterion in the ranking formula.

  • userScore (integer): Custom ranking for the object, expressed as a single numerical value. Conceptually, it’s what the position of the object would be in the list of all objects sorted by custom ranking. Corresponds to the custom criterion in the ranking formula.

  • geoDistance (integer): Distance between the geo location in the search query and the best matching geo location in the record, divided by the geo precision.

  • geoPrecision (integer): Precision used when computed the geo distance, in meters. All distances will be floored to a multiple of this precision.

  • nbExactWords (integer): Number of exactly matched words. If alternativeAsExact is set, it may include plurals and/or synonyms.

  • words (integer): Number of matched words, including prefixes and typos.

  • filters (integer): This field is reserved for advanced usage. It will be zero in most cases.

In addition, the response contains the following additional top-level fields:

  • serverUsed (string): Actual host name of the server that processed the request. (Our DNS supports automatic failover and load balancing, so this may differ from the host name used in the request.)

  • parsedQuery (string): The query string that will be searched, after normalization. Normalization includes removing stop words (if removeStopWords is enabled), and transforming portions of the query string into phrase queries (see advancedSyntax).

  • timeoutCounts (boolean): Whether a timeout was hit when computing the facet counts. When true, the counts will be interpolated (i.e. approximate). See also exhaustiveFacetsCount.

  • timeoutHits (boolean): Whether a timeout was hit when retrieving the hits. When true, some results may be missing.

numericFilters

scope search
type array of strings
default []
description

Filter hits based on values of numeric attributes.

The filters parameter provides an easier to use, SQL-like syntax. We recommend using it instead of numericFilters.

Each string represents a filter on a numeric attribute. Two forms are supported:

  • Comparison: ${attributeName} ${operator} ${operand} matches all objects where the specified numeric attribute satisfies the numeric condition expressed by the operator and the operand. The operand must be a numeric value. Supported operators are <, <=, =, !=, >= and >, with the same semantics as in virtually all programming languages. Example: inStock > 0.

  • Range: ${attributeName}:${lowerBound} TO ${upperBound} matches all objects where the specified numeric attribute is within the range [${lowerBound}, ${upperBound}] (inclusive on both ends). Example: price: 0 TO 1000.

If you specify multiple filters, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

Examples:

  • ["inStock > 0", "price < 1000"] translates as inStock > 0 AND price < 1000
  • [["inStock > 0", "deliveryDate < 1441755506"], "price < 1000"] translates as (inStock > 0 OR deliveryDate < 1441755506) AND price < 1000

tagFilters

scope search
type array of strings
default []
description

Filter hits by tags.

Tags must be contained in a top-level _tags attribute of your objects at indexing time.

Tags are essentially an implicit facet on the _tags attribute. We therefore recommend that you use facets instead. See attributesForFaceting and facets.

The filters parameter provides an easier to use, SQL-like syntax. We recommend using it instead of tagFilters.

Each string represents a given tag value that must be matched.

If you specify multiple tags, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

Examples:

  • ["Book", "Movie"] translates as Book AND Movie
  • [["Book", "Movie"], "SciFi"] translates as (Book OR Movie) AND SciFi"

Negation is supported by prefixing the tag value with a minus sign (-, a.k.a. dash). For example: ["tag1", "-tag2"] translates as tag1 AND NOT tag2.

analytics

scope search
type boolean
default true
description

Whether the current query will be taken into account in the Analytics.

analyticsTags

scope search
type array of strings
default []
description

List of tags to apply to the query in the Analytics.

Tags can be used in the Analytics to filter searches.

synonyms

scope search
type boolean
default true
description

Whether to take into account synonyms defined for the targeted index.

replaceSynonymsInHighlight

scope settings search
type boolean
default true
description

Whether to replace words matched via synonym expansion by the matched synonym in highlight and snippet results.

When true, highlighting and snippeting will use words from the query rather than the original words from the objects. When false, highlighting and snippeting will always display the original words from the objects.

Multiple words can be replaced by a one-word synonym, but not the other way round. For example, if “NYC” and “New York City” are synonyms, searching for “NYC” will replace “New York City” with “NYC” in highlights and snippets, but searching for “New York City” will not replace “NYC” with “New York City” in highlights and snippets.

placeholders

scope settings
type object of array of words
default {}
description

This is an advanced use-case to define a token substitutable by a list of words without having the original token searchable.

It is defined by a hash associating placeholders to lists of substitutable words.

For example, "placeholders": { "<streetnumber>": ["1", "2", "3", ..., "9999"]} would allow it to be able to match all street numbers. We use the < > tag syntax to define placeholders in an attribute.

For example:

  • Push a record with the placeholder: { "name" : "Apple Store", "address" : "&lt;streetnumber&gt; Opera street, Paris" }.
  • Configure the placeholder in your index settings: "placeholders": { "<streetnumber>" : ["1", "2", "3", "4", "5", ... ], ... }.

altCorrections

scope settings
type array of objects
default []
description

Specify alternative corrections that you want to consider.

Each alternative correction is described by an object containing three attributes:

  • word (string): The word to correct.
  • correction (string): The corrected word.
  • nbTypos (integer): The number of typos (1 or 2) that will be considered for the ranking algorithm (1 typo is better than 2 typos).

For example:

"altCorrections": [
  { "word" : "foot", "correction": "feet", "nbTypos": 1 },
  { "word": "feet", "correction": "foot", "nbTypos": 1 }
]

minProximity

scope settings search
type integer
default 1
description

Precision of the proximity ranking criterion.

By default, the minimum (and best) proximity value between two matching words is 1.

Setting it to 2 (respectively N) would allow 1 (respectively N-1) additional word(s) to be found between two matching words without degrading the proximity ranking value.

Example: considering the query “javascript framework”, if you set minProximity to 2, two records containing respectively “JavaScript framework” and “JavaScript charting framework” will get the same proximity score, even if the latter contains an additional word between the two matching words.

The maximum value for minProximity is 7. Any higher value will disable the proximity criterion in the ranking formula.

responseFields

scope settings search
type array of strings
default * (all fields)
description

Choose which fields the response will contain. Applies to search and browse queries.

By default, all fields are returned. If this parameter is specified, only the fields explicitly listed will be returned, unless * is used, in which case all fields are returned. Specifying an empty list or unknown field names is an error.

This parameter is mainly intended to limit the response size. For example, in complex queries, echoing of request parameters in the response’s params field can be undesirable.

List of fields that can be filtered out:

  • aroundLatLng
  • automaticRadius
  • exhaustiveFacetsCount
  • facets
  • facets_stats
  • hits
  • hitsPerPage
  • index
  • length
  • nbHits
  • nbPages
  • offset
  • page
  • params
  • processingTimeMS
  • query
  • queryAfterRemoval

List of fields that cannot be filtered out:

  • message
  • warning
  • cursor
  • serverUsed
  • timeoutCounts (deprecated, please use exhaustiveFacetsCount instead)
  • timeoutHits (deprecated, please use exhaustiveFacetsCount instead)
  • parsedQuery
  • all fields triggered by getRankingInfo

maxFacetHits

scope settings search
type integer
default 10
description

Maximum number of facet hits to return during a search for facet values.

Does not apply to regular search queries.

For performance reasons, the maximum allowed number of returned values is 100. Any value outside the range [1, 100] will be rejected.