Api clients / JavaScript / V3 / Methods

Jan. 09, 2023

Search Index | JavaScript API Client V3 (Deprecated)

This version of the JavaScript API client has been deprecated in favor of the latest version of the JavaScript API client.

Required API Key: any key with the search ACL

Method signature

index.search({ query: string }, callback)
index.search({ query: string, object ...searchParameters }, callback)

See code examples

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

Search

Copy

Copy
$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
]);

Copy
index = client.init_index('contacts')
res = index.search('query string')
res = index.search('query string', {
  attributesToRetrieve: 'firstname,lastname',
  hitsPerPage: 20
})

Copy
const client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
const index = client.initIndex('indexName');

// only query string
index.search({
  query: 'query string'
  },
  (err, { hits } = {}) => {
    if (err) throw err;

    console.log(hits);
  }
);

// with params
index.search(
  {
    query: 'query string',
    attributesToRetrieve: ['firstname', 'lastname'],
    hitsPerPage: 50,
  },
  (err, { hits } = {}) => {
    if (err) throw err;

    console.log(hits);
  }
);

Copy
index = client.init_index('contacts')

res = index.search('query string')
res = index.search('query string', {
    'attributesToRetrieve': [
        'firstname',
        'lastname'
    ],
    'hitsPerPage': 20
})

Copy
let index = client.index(withName: "contacts")
index.search(query: "s") { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

var query = Query("s")
query.attributesToRetrieve = ["firstname", "lastname"]
query.hitsPerPage = 50

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

Copy
Index index = client.getIndex("contacts");
Query query = new Query("query string")
  .setAttributesToRetrieve("firstname", "lastname")
  .setHitsPerPage(50);
index.searchAsync(query, new CompletionHandler() {
  @Override
  public void requestCompleted(JSONObject content, AlgoliaException error) {
    // [...]
  }
});

Copy
SearchIndex index = client.SearchIndex("contacts");

var result = index.Search<Contact>(new Query("query string"));

var result = index.Search<Contact>(new Query("query string")
{
  AttributesToRetrieve = new List<string> { "firstname", "lastname" }
  HitsPerPage = 50
});

// Asynchronous
var result = await index.SearchAsync<Contact>(new Query("query string"));

var result = await index.SearchAsync<Contact>(new Query("query string")
{
    AttributesToRetrieve = new List<string> { "firstname", "lastname" }
    HitsPerPage = 50
});

Copy
SearchIndex<Contact> index = client.initIndex("contacts", Contact.class);

SearchResult<Contact> search1 = index.search(new Query("query string"));

SearchResult<Contact> search2 =
  index
    .search(new Query("query string")
      .setAttributesToRetrieve(Arrays.asList("firstname", "lastname"))
      .setHitsPerPage(50)
    );

// Async version
CompletableFuture<SearchResult<Contact>> search1 =
  index.searchAsync(new Query("query string"));

CompletableFuture<SearchResult<Contact>> search2 =
  index
    .searchAsync(new Query("query string")
      .setAttributesToRetrieve(Arrays.asList("firstname", "lastname"))
      .setHitsPerPage(50)
    );

Copy
client.execute {
  search into "myIndex" query Query(
      query = Some("query string"),
      attributesToRetrieve = Some(Seq("firstname", "lastname")),
      hitsPerPage = Some(50)
  )
}

Copy
@Serializable
data class Contact(
    val firstname: String,
    val lastname: String
)

val indexName = IndexName("contacts")
val index = client.initIndex(indexName)
val query = queryBuilder {
    query = "query string"
    hitsPerPage = 50
    attributesToRetrieve {
        +"firstname"
        +"lastname"
    }
}
val result = index.search(query)

result.hits.deserialize(Contact.serializer())

Search and send an extra header

Copy

Copy
$index = $client->initIndex('your_index_name');

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

Copy
index = client.init_index('contacts')

search_parameters = []
extra_headers = {
      'X-Algolia-UserToken': 'user123'
}

res = index.search('query string', search_parameters, extra_headers)

Copy
const index = client.initIndex('your_index_name');

client.setExtraHeader('X-Algolia-UserToken', 'user123');

index.search({ query: 'query string' }, (err, { hits } = {}) => {
  if (err) throw err;

  console.log(hits);
});

Copy
index = client.init_index('contacts')

res = index.search('query string', {
    'X-Algolia-UserToken': 'user123',
    'attributesToRetrieve': [
        'firstname',
        'lastname'
    ],
    'hitsPerPage': 20
})

Copy
let index = client.index(withName: "your_index_name")
var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-UserToken"] = "user123"
index.search(query: "s", requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

Copy
RequestOptions requestOptions = new RequestOptions()
  .setHeader("X-Algolia-UserToken", "user123");
Index index = client.getIndex("contacts");
Query query = new Query("query string")
  .setAttributesToRetrieve("firstname", "lastname")
  .setHitsPerPage(50);
index.searchAsync(query, requestOptions, new CompletionHandler() {
  @Override
  public void requestCompleted(JSONObject content, AlgoliaException error) {
    // [...]
  }
});

Copy
Index index = client.InitIndex("contacts");

RequestOptions requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-UserToken", "user123" } }
};

var result = index.Search<Contact>(new Query("query string"), requestOptions);

Copy
//Sync version
SearchIndex<Contact> index = client.initIndex("your_index_name", Contact.class);
SearchResult<Contact> search =
  index
    .search(
      new Query("query string"),
      new RequestOptions().addExtraHeader("X-Algolia-UserToken", "user123")
    );

//Async version
AsyncIndex<Contact> index = client.initIndex("your_index_name", Contact.class);
CompletableFuture<SearchResult<Contact>> search =
  index
    .search(
      new Query("query string"),
      new RequestOptions().addExtraHeader("X-Algolia-UserToken", "user123")
    );

Copy
params := []interface{}{
  opt.AttributesToRetrieve("firstname", "lastname"),
  opt.HitsPerPage(50),
  opt.ExtraHeader(map[string]string{"X-Algolia-UserToken", "94.228.178.246"}),
}

res, err := index.Search("jimmie paint", params...)

Copy
client.execute {
  search into "your_index_name" query Query(
      query = Some("query string")
  ) options RequestOptions(
      extraHeaders = Some(Map("X-Algolia-UserToken" => "user123"))
    )
}

Copy
val indexName = IndexName("contacts")
val index = client.initIndex(indexName)
val query = Query("query")
val requestOptions = requestOptions {
    header("X-Algolia-User-ID", "user123")
}

index.search(query, requestOptions)

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

Copy

        {
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433",
      "_highlightResult": {
        "firstname": {
          "value": "&lt;em&gt;Jimmie&lt;/em&gt;",
          "matchLevel": "partial"
        },
        "lastname": {
          "value": "Barninger",
          "matchLevel": "none"
        },
        "company": {
          "value": "California &lt;em&gt;Paint&lt;/em&gt; & 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?