Search

The SearchClientWrapper class provides methods to perform searches.

Related quickstart notebook

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:

1def query(
2 self,
3 *,
4 index_id: str,
5 search_options: typing.List[SearchCreateRequestSearchOptionsItem],
6 query_media_type: typing.Optional[typing.Literal["image"]] = OMIT,
7 query_media_url: typing.Optional[str] = OMIT,
8 query_media_file: typing.Optional[core.File] = OMIT,
9 query_text: typing.Optional[str] = OMIT,
10 adjust_confidence_level: typing.Optional[float] = OMIT,
11 group_by: typing.Optional[SearchCreateRequestGroupBy] = OMIT,
12 threshold: typing.Optional[ThresholdSearch] = OMIT,
13 sort_option: typing.Optional[SearchCreateRequestSortOption] = OMIT,
14 operator: typing.Optional[SearchCreateRequestOperator] = OMIT,
15 page_limit: typing.Optional[int] = OMIT,
16 filter: typing.Optional[str] = OMIT,
17 request_options: typing.Optional[RequestOptions] = None,
18) -> SyncPager[SearchItem]

Parameters:

NameTypeRequiredDescription
index_idstrYesThe unique identifier of the index to search.
search_optionsList
[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.
query_textstrNoThe text query to search for. This parameter is required for text queries.
query_media_typeLiteral["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.
query_media_filecore.FileNoThe media file to use as a query. This parameter is required for media queries if query_media_url is not provided.
query_media_urlstrNoThe publicly accessible URL of a media file to use as a query. This parameter is required for media queries if query_media_file is not provided.
adjust_confidence_levelfloatNoThe strictness of the thresholds for assigning the high, medium, or low confidence levels to search results. Min: 0, Max: 1, Default: 0.5.
group_bySearchCreateRequestGroupByNoUse this parameter to group or ungroup items in a response. Values: video, clip. Default: clip.
thresholdThresholdSearchNoFilter on the level of confidence that the results match your query. Values: high, medium, low, none.
sort_optionSearchCreateRequestSortOptionNoThe sort order for the response. Values: score, clip_count. Default: score.
operatorSearchCreateRequestOperatorNoLogical operator for combining search options. Values: or, and. Default: or.
page_limitintNoThe number of items to return on each page. Max: 50.
filterstrNoA stringified object to filter search results based on video metadata or custom fields.
request_optionsRequestOptionsNoRequest-specific configuration.

Return value: Returns a SyncPager[SearchItem] object that allows you to iterate through the paginated search results.

The SyncPager[T] class contains the following properties and methods:

NameTypeDescription
itemsOptional[List[T]]A list containing the current page of items. Can be None.
has_nextboolIndicates whether there is a next page to load.
get_nextOptional[Callable[[], Optional[SyncPager[T]]]]A callable function that retrieves the next page. Can be None.
responseOptional[BaseHttpResponse]The HTTP response object. Can be None.
next_page()Optional[SyncPager[T]]Calls get_next() if available and returns the next page object.
__iter__()Iterator[T]Allows iteration through all items across all pages using for loops.
iter_pages()Iterator[SyncPager[T]]Allows iteration through page objects themselves.

The SearchItem class contains the following properties:

NameTypeDescription
scoreOptional[float]The score indicating how well the clip matches the search query.
startOptional[float]The start time of the clip in seconds.
endOptional[float]The end time of the clip in seconds.
video_idOptional[str]The unique identifier of the video. Once the platform indexes a video, it assigns a unique identifier.
confidenceOptional[str]The confidence level of the match (high, medium, low).
thumbnail_urlOptional[str]The URL of the thumbnail image for the clip.
transcriptionOptional[str]A transcription of the spoken words that are captured in the video.
idOptional[str]The unique identifier of the video. Only appears when the group_by=video parameter is used in the request.
clipsOptional[List[SearchItemClipsItem]]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 class contains the following properties:

NameTypeDescription
scoreOptional[float]The score indicating how well the clip matches the search query.
startOptional[float]The start time of the clip in seconds.
endOptional[float]The end time of the clip in seconds.
confidenceOptional[str]The confidence level of the match (high, medium, low).
thumbnail_urlOptional[str]The URL of the thumbnail image for the clip.
transcriptionOptional[str]A transcription of the spoken words that are captured in the clip.
video_idOptional[str]The unique identifier of the video for the corresponding clip.
user_metadataOptional[Dict[str, Optional[Any]]]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.

For a list of errors specific to this endpoint and general errors that apply to all endpoints, see the Error codes page.