Node.js SDK

Search

The SearchWrapper class provides methods to perform searches.

Methods

Make a search request

Description: This method performs a search across a specific index based on the provided parameters and returns a paginated iterator of search results.

If you wish to use images as queries, ensure that your images meet the following requirements:

  • Format: JPEG and PNG.
  • Dimension: Must be at least 64 x 64 pixels.
  • Size: Must not exceed 5MB.

If you wish to use images as queries, ensure that your images meet the following requirements:

  • Format: JPEG and PNG.
  • Dimension: Must be at least 64 x 64 pixels.
  • Size: Must not exceed 5MB.

If you wish to use images as queries, ensure that your images meet the following requirements:

  • Format: JPEG and PNG.
  • Dimension: Must be at least 64 x 64 pixels.
  • Size: Must not exceed 5MB.

If you wish to use images as queries, ensure that your images meet the following requirements:

  • Format: JPEG and PNG.
  • Dimension: Must be at least 64 x 64 pixels.
  • Size: Must not exceed 5MB.

Function signature and example:

1query(
2  request: TwelvelabsApi.SearchCreateRequest,
3  requestOptions?: Search.RequestOptions
4): Promise<core.Page<TwelvelabsApi.SearchItem>>

Parameters:

NameTypeRequiredDescription
request[TwelvelabsApi.SearchCreateRequest]YesThe search request parameters.
requestOptions[Search.RequestOptions]NoRequest-specific configuration.

The SearchCreateRequest interface defines the parameters for performing a search:

NameTypeRequiredDescription
indexIdstringYesThe unique identifier of the index to search.
searchOptionsTwelvelabsApi.
SearchCreateRequestSearchOptionsItem[]		YesSpecifies the sources of information the platform uses when performing a search. You must include the search options separately for each desired source of information. The search options you specify must be a subset of the model options used when you created the index.
queryTextstringNoThe text query to search for. This parameter is required for text queries.
queryMediaType"image"NoThe type of media you wish to use. This parameter is required for media queries. For example, to perform an image-based search, set this parameter to image.
queryMediaFileFile | fs.ReadStream | Blob | undefinedNoThe media file to use as a query. This parameter is required for media queries if queryMediaUrl is not provided.
queryMediaUrlstringNoThe publicly accessible URL of a media file to use as a query. This parameter is required for media queries if queryMediaFile is not provided.
adjustConfidenceLevelnumberNoThe strictness of the thresholds for assigning the high, medium, or low confidence levels to search results. Min: 0, Max: 1, Default: 0.5.
groupByTwelvelabsApi.SearchCreateRequestGroupByNoUse this parameter to group or ungroup items in a response. Values: video, clip. Default: clip.
thresholdTwelvelabsApi.ThresholdSearchNoFilter on the level of confidence that the results match your query. Values: high, medium, low, none.
sortOptionTwelvelabsApi.SearchCreateRequestSortOptionNoThe sort order for the response. Values: score, clip_count. Default: score.
operatorTwelvelabsApi.SearchCreateRequestOperatorNoLogical operator for combining search options. Values: or, and. Default: or.
pageLimitnumberNoThe number of items to return on each page. Max: 50.
filterstringNoA stringified object to filter search results based on video metadata or custom fields.

Return value: Return value: Returns a Promise that resolves to a Page<SearchItem> object that implements AsyncIterable, allowing you to iterate through the paginated search results.

The Page class contains the following properties and methods:

NameTypeDescription
dataT[]An array containing the current page of items.
getNextPage()Promise<this>Retrieves the next page and returns the updated Page object.
hasNextPage()booleanReturns whether there is a next page to load.
[Symbol.asyncIterator]()AsyncIterator<T>Allows iteration through all items across all pages using for await loops.

The SearchItem interface contains the following properties:

NameTypeDescription
scorenumberThe score indicating how well the clip matches the search query.
startnumberThe start time of the clip in seconds.
endnumberThe end time of the clip in seconds.
videoIdstringThe unique identifier of the video. Once the platform indexes a video, it assigns a unique identifier.
confidencestringThe confidence level of the match (high, medium, low).
thumbnailUrlstringThe URL of the thumbnail image for the clip.
transcriptionstringA transcription of the spoken words that are captured in the video.
idstringThe unique identifier of the video. Only appears when the group_by=video parameter is used in the request.
clipsSearchItemClipsItem[]An array that contains detailed information about the clips that match your query. The platform returns this array only when the group_by parameter is set to video in the request.

The SearchItemClipsItem interface contains the following properties:

NameTypeDescription
scorenumberThe score indicating how well the clip matches the search query.
startnumberThe start time of the clip in seconds.
endnumberThe end time of the clip in seconds.
confidencestringThe confidence level of the match (high, medium, low).
thumbnailUrlstringThe URL of the thumbnail image for the clip.
transcriptionstringA transcription of the spoken words that are captured in the clip.
videoIdstringThe unique identifier of the video for the corresponding clip.
userMetadataRecord<string, unknown>User-defined metadata associated with the video.

API Reference: Any-to-video search.

Related guides:

Error codes

This section lists the most common error messages you may encounter while performing search requests.

  • search_option_not_supported
    • Search option {search_option} is not supported for index {index_id}. Please use one of the following search options: {supported_search_option}.
  • search_option_combination_not_supported
    • Search option {search_option} is not supported with {other_combination}.
  • search_filter_invalid
    • Filter used in search is invalid. Please use the valid filter syntax by following filtering documentation.
  • search_page_token_expired
    • The token that identifies the page to be retrieved is expired or invalid. You must make a new search request. Token: {next_page_token}.
  • index_not_supported_for_search:
    • You can only perform search requests on indexes with an engine from the Marengo family enabled.