Search

Search the Index for Objects relevant to the text query.

Key features include:

• Semantic, automatically understanding natural language queries, synonyms, typos, and multiple languages.
• Hybrid, capable of exact matching and approximate matching in one API without requiring you to develop lexical / keyword matching as well as vector-based approximate nearest neighbors (ANN) engines.
• Multimodal, enabling each Object in the index to be described by information coming from different media types such as images, audio and videos,
• Deep, surfacing relevant Highlights from different media by going inside the content and pulling out relevant bits.

Filtering results

The search API supports all common filtering use cases. See Filtering for more info.

Ranking Signals

The search API also supports Ranking Signals which enable you to influence the order in which the results are returned. See Ranking Signals for more info.

Image search

Indexes with images in them support searching by image. See Image Search for more info.

Requesting Object fields be returned

By default our API returns a "minimal" search result response containing only the ID of the resulting Object. There are several benefits to this including decreased latency, data size on the wire and network fees.

You may request additional fields are returned as part of the "object" field in the SearchResult. To do this, list the fields you want returned separated by commas in the object_fields query paramter.

For example, to return the fields called "title" and "images" you would use object_fields=title,images.

Requesting all fields in the Object

We support a shorthand to request the entire object by using the wildcard character *. To request all of the fields in the object use object_fields=*.

Pagination

The search API supports paginating through results. See Pagination for more info.

Compression

Compressing results leads to lower latency and smaller size on the wire. We suggest all clients use compression when calling our search API. You may set the content encoding via the Accept-Encoding header. We suggest using the brotli algorithm by setting Accept-Encoding: br. We support the following values: br, gzip, deflate.

Example usage:

curl --request GET \
  --url 'https://api.objective.inc/v1/indexes/idx_.../search?query=test' \
  --header 'Authorization: Bearer sk_...' \
  --header 'Accept-Encoding: br,gzip,deflate'

Relevance scores

By default the API does not return a relevance score for results. The reason is that our relevance scores are not calibrated, and thus don't follow any specific distribution. For this reason we call the default score uncalibrated_relevance. If you choose to use this score, we recommend studying the uncalibrated score for your use case, as it can change significantly based on the data and queries.

Returning relevance scores

To request the relevance score, pass the default ranking expression: ranking_expr=uncalibrated_relevance. This is the default ranking, and thus does not change the results. Pass the ranking_expr parameter causes the signals field to be returned, which contains the score for each result.

~ curl --request GET \
  --url 'https://api.objective.inc/v1/indexes/idx_.../search?query=dress&ranking_expr=uncalibrated_relevance' \
  --header 'Authorization: Bearer sk_...'
{
	"results": [
		{
			"id": "B08XX11WHX",
			"signals": {
				"score": 0.8724408,
				"uncalibrated_relevance": 0.8724408
			}
		},
  ...