Algolia DevCon
Oct. 2–3 2024, virtual.
Api clients / JavaScript / V3 / Methods

Search Index | JavaScript API Client V3 (Deprecated)

Deprecated content
This documentation is for a deprecated version of JavaScript API client. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of JavaScript API client for up-to-date information.
Required API Key: any key with the search ACL
Method signature
index.search({ query: string }, callback)
index.search({ query: string, object ...searchParameters }, callback)

About this method

Method used for querying an index.

The search query only allows for the retrieval of up to 1000 hits. If you need to retrieve more than 1000 hits (e.g. for SEO), you can either leverage the Browse index method or increase the paginationLimitedTo parameter.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
$index = $client->initIndex('contacts');

// without search parameters
$res = $index->search('query string');

// with search parameters
$res = $index->search('query string', [
  'attributesToRetrieve' => [
    'firstname',
    'lastname',
  ],
  'hitsPerPage' => 50
]);

Search and send an extra header

1
2
3
4
5
6
$index = $client->initIndex('your_index_name');

$res = $index->search('query string', [
  'hitsPerPage' => 10, // search parameter
  'X-Algolia-UserToken' => 'user123' // extra header
]);

Parameters

query
type: string
Required

The query used to search. Accepts every character, and every character entered will be used in the search.

An empty query can be used to fetch all records.

searchParameters
type: key value mapping
default: No search parameters
Optional

A mapping of search parameters to send along with the query.

requestOptions
type: key value mapping
default: No request options
Optional

A mapping of [`requestOptions`](/doc/api-client/getting-started/request-options/) to send along with the query.

Response

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

JSON format

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433",
      "_highlightResult": {
        "firstname": {
          "value": "<em>Jimmie</em>",
          "matchLevel": "partial"
        },
        "lastname": {
          "value": "Barninger",
          "matchLevel": "none"
        },
        "company": {
          "value": "California <em>Paint</em> & Wlpaper Str",
          "matchLevel": "partial"
        }
      }
    }
  ],
  "page": 0,
  "nbHits": 1,
  "nbPages": 1,
  "hitsPerPage": 20,
  "processingTimeMS": 1,
  "query": "jimmie paint",
  "params": "query=jimmie+paint&attributesToRetrieve=firstname,lastname&hitsPerPage=50"
}
hits
list

The hits returned by the search.

Hits are ordered according to the ranking or sorting of the index being queried.

Hits are made of the schemaless JSON objects that you stored in the index.

However, Algolia does enrich them with a few additional fields, such as _highlightResult, _snippetResult, _rankingInfo, and _distinctSeqID.

hits: [
  {
    field1 : "",
    field2 : "",
    [...],

    _highlightResult: {
      [...]
    },
    _snippetResult: {
      [...]
    },
    _rankingInfo: {
      [...]
    },
    _distinctSeqID:
  },
  [...]
]
nbHits
integer

The number of hits matched by the query.

page
integer

Index of the current page (zero-based). See the page search parameter.

Not returned if you use offset/length for pagination.

hitsPerPage
integer

The maximum number of hits returned per page. See the hitsPerPage search parameter.

Not returned if you use offset & length for pagination.

userData
array

Array of userData object.

Only returned if at least one Rule containing a custom userData consequence was applied.

nbPages
integer

The number of returned pages. Calculation is based on the total number of hits (nbHits) divided by the number of hits per page (hitsPerPage), rounded up to the nearest integer.

Not returned if you use offset & length for pagination.

processingTimeMS
integer

Time the server took to process the request, in milliseconds. This does not include network time.

exhaustiveNbHits
boolean

Whether the nbHits is exhaustive (true) or approximate (false). When the query takes more than 50ms to be processed, the engine makes an approximation. This can happen when using complex filters on millions of records, or when enough hits have been retrieved (for example, after the engine finds 10,000 exact matches). See the related discussion for more details.

exhaustiveFacetsCount
boolean

Whether the facet count is exhaustive (true) or approximate (false). See the related discussion.

query
string

An echo of the query text. See the query search parameter.

queryAfterRemoval
string

A markup text indicating which parts of the original query have been removed in order to retrieve a non-empty result set.

The removed parts are surrounded by <em> tags.

Only returned when removeWordsIfNoResults is set to lastWords or firstWords.

params
string

A url-encoded string of all search parameters.

message
string
optional

Used to return warnings about the query.

aroundLatLng
string

The computed geo location. Warning: for legacy reasons, this parameter is a string and not an object. Format: ${lat},${lng}, where the latitude and longitude are expressed as decimal floating point numbers.

Only returned when aroundLatLngViaIP or aroundLatLng is set.

automaticRadius
string

The automatically computed radius. For legacy reasons, this parameter is a string and not an integer.

Only returned for geo queries without an explicitly specified radius (see aroundRadius).

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.

Returned only if getRankingInfo is set to true.

indexUsed
string

Index name used for the query. In the case of an A/B test, the targeted index isn’t always the index used by the query.

Returned only if getRankingInfo is set to true.

abTestVariantID
integer

If a search encounters an index that is being A/B tested, abTestVariantID reports the variant ID of the index used (note, this is the ID not the name). The variant ID is the position in the array of variants (starting at 1).

For example, abTestVariantID=1 is variant A (the main index), abTestVariantID=2 is variant B (the replica you chose when creating the A/B test , or the queries with the changed query parameters if the A/B test is based on query parameters).

Returned only if getRankingInfo is set to true.

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).

Returned only if getRankingInfo is set to true.

timeoutCounts DEPRECATED
boolean

Please use exhaustiveFacetsCount instead.

Returned only if getRankingInfo is set to true.

timeoutHits DEPRECATED
boolean

Please use exhaustiveHitsCount instead.

Returned only if getRankingInfo is set to true.

facets
key value mapping

A mapping of each facet name to the corresponding facet counts.

${facet_name} => ${facet_value}

Returned only if facets is non-empty.

facets_stats
key value mapping

Statistics for numerical facets.

${facet_name} (object): The statistics for a given facet:

  • min (integer | float): The minimum value in the result set.
  • max (integer | float): The maximum value in the result set.
  • avg (integer | float): The average facet value in the result set.
  • sum (integer | float): The sum of all values in the result set.

Regardless of the number of requested facet values (as per maxValuesPerFacet), statistics are always computed on at most 1,000 distinct values (starting with the most frequent ones). If there are more than 1,000 distinct values, statistics may therefore not be 100% accurate.

Returned only if facets is non-empty and at least one of the returned facets contains numerical values.

queryID
string

Unique identifier of the search query, to be sent in Insights methods. This identifier links events back to the search query it represents.

Returned only if clickAnalytics is true.

hits ➔ _highlightResult

Highlighted attributes. Each attribute contains an object or an array of objects (if the attribute in question is an array) with the following attributes. Only returned when attributesToHighlight is non-empty.

{
  hits: [
    {
      "${attribute_name}": "Jimmie",
      "_highlightResult": {
        "${attribute_name}": {
          "value": "<em>Jimmie</em>",
          "matchLevel": "partial",
          "matchedWords": ["Jimmie"],
          "fullyHighlighted": true
      }
    }
  ]
}
value
string

Markup text with occurrences highlighted. The tags used for highlighting are specified via highlightPreTag and highlightPostTag.

matchLevel
string

Indicates how well the attribute matched the search query. Can be:

  • none (0)
  • partial (some)
  • full (all)

The matching relates to the words in the query string not in the searched text of the records.

By “meaningful” we mean: if stop words are removed, they are not taken into account. So if you match everything but stop words (and removeStopWords is enabled), then it’s a full match.

This has nothing to do with prefixes, plurals, synonyms, or typos. No matter how “accurately” a word matches, if it matches, it counts as one.

matchedWords
list

List of words from the query that matched the object.

fullyHighlighted
boolean

Whether the entire attribute value is highlighted.

hits ➔ _snippetResult

Snippeted attributes. Only returned when attributesToSnippet is non-empty.

{
  hits: [
    {
      "${attribute_name}": "Jimmie is working remote for 2 weeks",
      "_snippetResult": {
        "${attribute_name}": {
          "value": "<em>Jimmie</em> is working remote ...",
          "matchLevel": "partial"
        }
    }
  ]
}
value
string

Markup text with occurrences highlighted. The tags used for highlighting are specified via highlightPreTag and highlightPostTag. The text used to indicate ellipsis is specified via snippetEllipsisText.

matchLevel
string

Indicates how well the attribute matched the search query. Can be: none or partial or full. See highlightResult matchLevel for more details.

hits ➔ _rankingInfo

Ranking information. Only returned when getRankingInfo is true.

promoted
boolean

Present and set to true if a Rule promoted the hit.

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 (in meters). Corresponds to the proximity criterion in the ranking formula.

userScore
integer

Custom ranking for the object, expressed as a single integer value. This field is internal to Algolia and shouldn’t be relied upon.

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 (in meters).

geoPrecision
integer

Precision used when computing the geo distance, in meters. All distances will be floored to a multiple of this precision.

nbExactWords
integer

Number of exactly matched words. If alternativesAsExact 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.

matchedGeoLocation
key value mapping

Geo location that matched the query.

  • lat: Latitude of the matched location.
  • lng: Longitude of the matched location.
  • distance: Distance between the matched location and the search location (in meters). Contrary to geoDistance, this value is not divided by the geo precision.

Only returned if aroundRadius is used.

{
  "lat": 51.148056
  "lng": -0.190278,
  "distance": 35
}

hits ➔ _distinctSeqID

_distinctSeqID
integer

When two consecutive results have the same value for the attribute used for “distinct”, this field is used to distinguish between them. Only returned when distinct is non-zero.

Did you find this page helpful?