Skip to main content

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

Returns a JSON object with a 'results' array containing SearchResult objects adhering to the schema defined below.

Filtering search results

Search results may be filtered based on conditions or exact matches on fields in the Object. Filters are applied by using the filter_query= query parameter. This parameter takes a string value that represents the filter query to be applied to the results.

URL Encoding

Filter queries should be URL encoded before being sent to the API. This means that filter_query=color:"dark green" should be sent to the API as filter_query%3Dcolor%3A%22dark%20green%22. For more info on URL encoding, see https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding.

Field types

In order to filter on a field, the Index must be configured with this field as filterable, and the field must have a type. See the create Index documentation for how to index a field as filterable. The following types are supported for filtering:

  • string
  • int
  • float
  • bool
  • datetime (we support RFC 3339 formatted dates. For example 2015-11-03T15:01:00.05Z)

Fields that are indexed as filterable must have homogenous types. This means that all of the values of the field that are indexed must share the same type. If a value in an Object does not conform to the type defined in the index configuration that Object will fail to index, and thus will not be filterable. This means this Object will not appear in results when filtered upon.

Field names

Field names must contain only alphanumeric characters or underscores (_) in order to be filterable. This means if your data has a field called "Leg/hem length", to filter by this field you should rename to leg_hem_length before pushing to the Object Store.

Supported filters

The following types of filters are supported:

  • Exact match
  • Boolean operators
  • Range filters
    • Inclusive and exclusive
    • Bounded and unbounded
  • Sets

Exact match

To filter search results by a field, give the field name and the value separated by a colon, i.e. {field name}:{value}. For example, to filter by color to only green values you would set filter_query=color:"green".

To filter by a value with spaces wrap the value in double quotes, i.e. filter_query=color:"dark green".

Boolean operators

Filters can be combined using AND, OR and NOT. So to search for items that are red or green, you would set filter_query=color:"green" OR color:"red".

Filters can also be combined across fields, so to search for items that are red and shoes you would provide filter_query=color:"red" AND category:"shoes". When providing multiple filters you may group them using parenthesis (). For example, to search for shoes that are red or green you would provide filter_query=(color:"green" OR color:"red") AND category:shoes.

Ranges

You can use interval notation to define the set to which a field's value must belong. Range filters are supported on the following field types:

  • int
  • float
  • date

Your Filter Query will include two brackets with values separated by TO, where the type of bracket on either side indicates inclusivity (a square bracket) or exclusivity (a curly bracket), for that endpoint of the set. Omitting a value on either side will unbound that side of the expression.

DescriptionInequality NotationInterval Notation
between 0 and 10, inclusive0 <= 𝑥 <= 10[0 TO 10]
between 0 and 10, exclusive0 < 𝑥 < 10(0 TO 10)
greater than or equal to 0 and less than 100 <= 𝑥 < 10[0 TO 10)
less than or equal to 9.5𝑥 <= 9.5[* TO 9.5]
greater than or equal to 9.59.5 >= 𝑥[9.5 TO *]

For example, to search for shoes that cost $10 or less, you would provide: filter_query=price:[0 TO 10] AND category:shoes. Note that in this example, the price field must be indexed as an int or float type (e.g. 10 or 10.00), and not $10, which would be interpreted as a string.

Sets

Using the IN operator, a field can be matched against a set of literals, e.g. title: IN ["a" "b" "cd"] will match documents where title is either a, b or cd, but do so more efficiently than the alternative query title:"a" OR title:"b" OR title:"c" does. Example: filter_query=title: IN ["a", "b", "cd"].

Errors when filtering

When constructing filter queries there are several types of errors that can occur. These errors result in HTTP 429 error codes, indicating that the query could not be applied. In this case the API will respond with HTTP 429 and a JSON containing a message with the error.

Example:

HTTP 429
{
"detail": "Expected a valid string, boolean, integer, float, or datetime literal. Position: 44."
}

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=*.

API Spec

GET /indexes/:index_id/search

Path parameters

(required) index_id : str - the ID of the Index

Query parameters

(required) query : str - The natural language search query to search the catalog for. Example: "black polka dotted dress".

(optional) filter_query : str - the set of filters to apply to the query. See Filtering search results

(optional) object_fields : str - fields in the object to be returned outside the default set of fields

(optional) limit : int - number of results to be returned

(optional) offset : int - offset within the total number of relevant results. Can be combined with limit to paginate the results.

Request body

None

Response

Status codes

  • 200 Successful response
  • 422 Validation error
    • Invalid filter query syntax
    • Invalid request

Schema

SearchResults
{
"results": SearchResult[]
"pagination": {
"pages": int,
"page": int,
"next": {
"offset": int,
"limit": int
}
}
}

SearchResult
{
"id": str, // ID from ingestion
"object": object, // Original Object inserted into the index
"highlights": Match[]
}

For more info about parsing Match objects, see Match objects.

Examples

By default search results return a minimal object containing only the object ID.

Example: Default search
curl 'https://api.objective.inc/v1/indexes/idx_rHlXLhCTma74w1E_xbRXl/search?query=city%20by%20the%20ocean' \
-H 'Authorization: Bearer sk_NefoODAZoyA45KsLsQu6J'

{
"results": [
{
"id": "123",
"object": {}
},
...
]
}

Request exactly which part of the object is most relevant using highlights. See highlights for more info.

Example: Request object matches
curl 'https://api.objective.inc/v1/indexes/idx_rHlXLhCTma74w1E_xbRXl/search?query=city%20by%20the%20ocean&result_fields=highlights' \
-H 'Authorization: Bearer sk_NefoODAZoyA45KsLsQu6J'

{
"results": [
{
"id": "123",
"highlights": [
{
"reference_type": "text",
"media_identifier": "...",
"highlight": {
"text": "...",
},
"position": {
"start_char": 1,
"end_char": 10
}
},
{
"reference_type": "image",
"media_identifier": "https://www.example.com/img.jpg"
}
],
"object": {}
},
...
]
}