Search Options

Search Options

There are a number of fields that are common to all search endpoints.

Collection Identification (required)

You can have many collections with various types and composition of data. The collection fields instruct the Vantage platform which collection within your account to perform the search against.

  • collection.account_id: The Vantage account ID that the collection is contained within. This can be found in the Console UI and it is typically your company or organization name.
  • collection.collection_id: The unique identifier of the collection you are searching. You specified this ID when you created the collection. This can be found in the Console UI or by API request.
{
  ...
  "collection": {
    "account_id": "docs-account",
    "collection_id": "docs-sample-collection"
    ...
  }
  ...
}

Accuracy (required)

The Vantage platform lets you tune the recall of every search query, controlling how much of your collection data to search over. Generally, a lower accuracy number give great results, with exceptional speed (tens of milliseconds). A higher accuracy number may provide additional or better results, but take longer to process (one to three seconds).

  • collection.accuracy: A number between 0.001 and 1.000 that tells the Vantage platform how much of the collection to search across. A higher number will search across more of the collection but take longer. If unsure, a good place to start is 0.2.
{
  ...
  "collection": {
    "accuracy" : 0.15
    ...
  }
  ...
}
{
  ...
  "collection": {
    "accuracy" : 0.5
    ...
  }
  ...
}

Pagination (required)

Pagination lets you control which results you receive within the larger set of results. You can call the endpoint repeatedly to page your results, requesting batches of results up to a total of 1000 results.

  • pagination.page: A number, starting at 0, that indicates the page of results to return, where each page is of size pagination.count.
  • pagination.count: The number of results to return for this request. Must be greater than 0.
{
	...
  "pagination": {
    "page": 0,
    "count": 40
  }
	...
}
{
	...
  "pagination": {
    "page": 1,
    "count": 40
  }
	...
}

🚧

Result order determinism

The overall search result set for a given query may change for a variety of reasons between requests. While it's very likely that the next page of results will begin on the precise next result from the overall set, it's possible that new content being ingested into the collection may alter the overall result set.

Filtering (required)

Filters enable your collection's ingested features or categorical data to be used in conjunction with semantic similarity search. Using filters generally results in lightning quick results. They are frequently used in traditional faceted search interfaces. For example, in product catalog search, you may only want product results within a single category, brand, size or color.

  • filter.boolean_filter: Either an empty string (no filters) or a boolean clause that will filter the results while the Vantage platform scores for semantic similarity. The string itself is comprised of:
    • field:"value": Limits results based on exact, case sensitive matching to a meta_ field provided during ingestion. Both field and value are case sensitive.
    • Combinations of these limits put together with AND and OR.
    • These filters can be composed together and compositely to create trees of complex filters using parentheses ( and ).
# product_category was ingested as meta_product_category
product_category:"Fashion"
product_BrandName:"Brand XYZ"
(product_category:"Fashion" AND product_BrandName:"Brand XYZ")
(product_category:"Fashion" OR product_category:"Clothing")
(
  (product_category:"Fashion" OR product_category:"Clothing")
  AND 
  product_BrandName:"Brand XYZ"
)
  • boolen_filter is sent in JSON, so a filter typically has the quotes (") escaped in the JSON request. Most JSON libraries do this automatically on your behalf when you create JSON from an object string containing quotes.
{
  filter: {
    boolean_filter: "((product_category:\"Fashion\" OR product_category:\"Clothing\") AND product_BrandName:\"Brand XYZ\")"
  }
}

🚧

filter.boolean_filter is a required field, so if there is no filter then pass in an empty string.

Request ID (required)

To enable asynchronous calls to the search endpoints, an identifier is included in the request which is then returned with the results.

  • request_id: An integer that will be returned with the results. It should be unique across all in-progress calls to any search endpoint.

πŸ“˜

Reference Guide for Search API