Api clients / Ruby / V1 / Methods

Mar. 31, 2022

Search Index | Ruby API Client V1 (Deprecated)

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

Required API Key: any key with the search ACL

Method signature

index.search(String query)
index.search(String query, Hash searchParameters)
index.search(String query, Hash searchParameters, Hash requestOptions)

See code examples

About this method# A

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# A

Search#

Copy

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

1
2
3
4
5
6
index = client.init_index('contacts')
res = index.search('query string')
res = index.search('query string', {
  attributesToRetrieve: 'firstname,lastname',
  hitsPerPage: 20
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const client = algoliasearch('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');
const index = client.initIndex('indexName');

// only query string
index.search('query string').then(({ hits }) => {
  console.log(hits);
});

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

1
2
3
4
5
6
7
8
9
10
index = client.init_index('contacts')

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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)")
  }
}

1
2
3
4
5
6
7
8
9
10
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) {
    // [...]
  }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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)
    );

1
2
3
4
5
6
7
client.execute {
  search into "myIndex" query Query(
      query = Some("query string"),
      attributesToRetrieve = Some(Seq("firstname", "lastname")),
      hitsPerPage = Some(50)
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@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

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

1
2
3
4
5
6
7
8
index = client.init_index('contacts')

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

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

1
2
3
4
5
6
7
const index = client.initIndex('your_index_name');

index.search('query string', {
  headers: { 'X-Algolia-UserToken': 'user123' }
}).then(({ hits }) => {
  console.log(hits);
});

1
2
3
4
5
6
7
8
9
10
index = client.init_index('contacts')

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

1
2
3
4
5
6
7
8
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)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
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) {
    // [...]
  }
});

1
2
3
4
5
6
7
8
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);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//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")
    );

1
2
3
4
5
6
7
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...)

1
2
3
4
5
6
7
client.execute {
  search into "your_index_name" query Query(
      query = Some("query string")
  ) options RequestOptions(
      extraHeaders = Some(Map("X-Algolia-UserToken" => "user123"))
    )
}

1
2
3
4
5
6
7
8
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# A


            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 sent along with the query.


            requestOptions

type: key/value mapping

default: No request options

Optional

A mapping of request options sent along with the query.

Response# A

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?