The SearchClientWrapper class provides methods to perform search requests.

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.

Function signature and example:

1 def 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:

Name	Type	Required	Description
`index_id`	`str`	Yes	The unique identifier of the index to search.
`search_options`	`List` `[SearchCreateRequestSearchOptionsItem]`	Yes	Specifies the sources of information the platform uses when performing a search. The search options you specify must be a subset of the model options used when you created the index. Values: `visual`, `audio`.
`query_text`	`str`	No	The text query to search for. This parameter is required for text queries.
`query_media_type`	`Literal["image"]`	No	The 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_file`	`core.File`	No	The media file to use as a query. This parameter is required for media queries if `query_media_url` is not provided.
`query_media_url`	`str`	No	The 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_level`	`float`	No	The strictness of the thresholds for assigning the high, medium, or low confidence levels to search results. Min: 0, Max: 1, Default: 0.5.
`group_by`	`SearchCreateRequestGroupBy`	No	Use this parameter to group or ungroup items in a response. Values: `video`, `clip`. Default: `clip`.
`threshold`	`ThresholdSearch`	No	Filter on the level of confidence that the results match your query. Values: `high`, `medium`, `low`, `none`.
`sort_option`	`SearchCreateRequestSortOption`	No	The sort order for the response. Values: `score`, `clip_count`. Default: `score`.
`operator`	`SearchCreateRequestOperator`	No	Logical operator for combining search options. Values: `or`, `and`. Default: `or`.
`page_limit`	`int`	No	The number of items to return on each page. Max: 50.
`filter`	`str`	No	A stringified object to filter search results based on video metadata or custom fields.
`include_user_metadata`	`bool`	No	Specifies whether to include user-defined metadata in the search results.
`request_options`	`RequestOptions`	No	Request-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:

Name	Type	Description
`items`	`Optional[List[T]]`	A list containing the current page of items. Can be `None`.
`has_next`	`bool`	Indicates whether there is a next page to load.
`get_next`	`Optional[Callable[[], Optional[SyncPager[T]]]]`	A callable function that retrieves the next page. Can be `None`.
`response`	`Optional[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:

Name	Type	Description
`score`	`Optional[float]`	The score indicating how well the clip matches the search query.
`start`	`Optional[float]`	The start time of the clip in seconds.
`end`	`Optional[float]`	The end time of the clip in seconds.
`video_id`	`Optional[str]`	The unique identifier of the video. Once the platform indexes a video, it assigns a unique identifier.
`confidence`	`Optional[str]`	The confidence level of the match (high, medium, low).
`thumbnail_url`	`Optional[str]`	The URL of the thumbnail image for the clip.
`transcription`	`Optional[str]`	A transcription of the spoken words that are captured in the video.
`id`	`Optional[str]`	The unique identifier of the video. Only appears when the `group_by=video` parameter is used in the request.
`user_metadata`	`Optional[typing.Dict[str, typping.Optional[typing.Any]]]`	User-defined metadata associated with the video.
`clips`	`Optional[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:

Name	Type	Description
`score`	`Optional[float]`	The score indicating how well the clip matches the search query.
`start`	`Optional[float]`	The start time of the clip in seconds.
`end`	`Optional[float]`	The end time of the clip in seconds.
`confidence`	`Optional[str]`	The confidence level of the match (high, medium, low).
`thumbnail_url`	`Optional[str]`	The URL of the thumbnail image for the clip.
`transcription`	`Optional[str]`	A transcription of the spoken words that are captured in the clip.
`video_id`	`Optional[str]`	The unique identifier of the video for the corresponding clip.
`user_metadata`	`Optional[typing.Dict[str, typping.Optional[typing.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.