The KnowledgeStoresClient class provides the search method to search across the items in a knowledge store using natural language.

Methods

Search a knowledge store

Description: This method searches a knowledge store using natural language and returns matching video clips and images ranked by relevance.

Provide your natural-language query in the query.text field. Use the filter parameter to choose which items to search: by type of item (the asset_type field) or by specific items (the item_id field). Use the optional search_options parameter to control how videos are matched (by visual content, audio, or both). If you omit it, videos are matched on their visual content. Images are always matched on their visual content.

By default, each result is an individual match: a video clip or an image. Set the group_by parameter to item to group clips under their parent item.

Note

This method is rate-limited. For details, see the Rate limits page.

Function signature and example:

1 def search(
2     self,
3     knowledge_store_id: str,
4     *,
5     query: KnowledgeStoreSearchQuery,
6     filter: typing.Optional[SearchKnowledgeStoreFilter] = OMIT,
7     search_options: typing.Optional[SearchKnowledgeStoreOptions] = OMIT,
8     group_by: typing.Optional[SearchKnowledgeStoreRequestGroupBy] = OMIT,
9     page_size: typing.Optional[int] = OMIT,
10     page_token: typing.Optional[str] = OMIT,
11     include_metadata: typing.Optional[bool] = OMIT,
12     request_options: typing.Optional[RequestOptions] = None,
13 ) -> SearchKnowledgeStoreResponse:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`query`	`KnowledgeStore` `SearchQuery`	Yes	The search query.
`filter`	`typing.` `Optional` `[SearchKnowledge` `StoreFilter]`	No	Narrows results to specific items in the knowledge store. Omit the filter to search all items.
`search_options`	`typing.` `Optional` `[SearchKnowledge` `StoreOptions]`	No	Specifies how videos are matched. If you omit this field, videos are matched on their visual content. Images are always matched on their visual content and have no options to configure.
`group_by`	`typing.` `Optional` `[SearchKnowledge` `StoreRequestGroupBy]`	No	Controls how the platform groups matches in the response. - `none`: Returns individual matches ordered by relevance. - `item`: Groups matches under their parent item. Default: `none`.
`page_size`	`typing.` `Optional[int]`	No	The maximum number of results per page. A result is one entry in the `data` array. With the `group_by` parameter set to its default of `none`, each result is an individual match: a video clip or an image. When set to `item`, each result is one item: a video with all its matching clips, or an image. Default: `10`. Max: `50`.
`page_token`	`typing.` `Optional[str]`	No	Pagination token used to retrieve the next page of results. Omit it on the first request. To fetch the next page, set it to the `next_page_token` field returned in the previous response and send the request again. A malformed or unrecognized token returns a `400` error. A token that has expired returns a `410` error (make a new search request to obtain a fresh page token).
`include_metadata`	`typing.` `Optional[bool]`	No	Set to `true` to include metadata in each result. Each result includes a `metadata` object with a `system` field (platform-derived file properties such as duration and resolution) and a `user` field (metadata you attached to the item).
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

The KnowledgeStoreSearchQuery class contains the following property:

Name	Type	Required	Description
`text`	`str`	Yes	Describe what you’re searching for in natural language (Examples: `A person cooking pasta` or `aerial shots of a city at night`).

The SearchKnowledgeStoreFilter class narrows results to specific items in the knowledge store. Filter by type of item or by specific identifiers. When you specify both fields, the platform applies all conditions together. It contains the following properties:

Name	Type	Required	Description
`asset_type`	`Optional` `[AssetTypeFilter]`	No	Narrows results by type of item. Provide exactly one operator: `eq` (a `KnowledgeStoreItemAssetType`) to match one type, or `in_` (a list) to match any of the listed types. Values: `video`, `image`.
`item_id`	`Optional` `[ItemIdFilter]`	No	Narrows results to specific items. Provide exactly one operator: `eq` (a `str`) to match one item, or `in_` (a list) to match any of the listed items.

The SearchKnowledgeStoreOptions class contains the following property:

Name	Type	Required	Description
`video`	`Optional` `[VideoSearchOptions]`	No	Options that control how videos are matched. By default, videos are matched on their visual content.

The VideoSearchOptions class contains the following properties:

Name	Type	Required	Description
`modalities`	`List` `[VideoSearch` `Modality]`	Yes	The video modalities used for searching. - `visual`: Searches visual content. - `audio`: Searches audio content, including speech and non-speech sounds. You can combine multiple modalities to broaden your search. For guidance, see Search options.

Return value

Returns a SearchKnowledgeStoreResponse object. The SearchKnowledgeStoreResponse class contains the following properties:

Name	Type	Description
`data`	`List` `[SearchKnowledge` `StoreHit]`	Search results, ordered by relevance.
`next_page_token`	`Optional[str]`	Pagination token for the next page. Pass this value as the `page_token` parameter in your next request to retrieve more results. Absent when no more pages exist.
`effective_search_options`	`SearchKnowledge` `StoreOptions`	The video options applied to this search, including any defaults. When the search includes videos, this object contains a `video` field with the modalities used. When the search is limited to images, this object is empty.

Each entry in the data array is a SearchKnowledgeStoreHit. The fields present depend on the asset_type field:

Name	Type	Description
`asset_type`	`Literal` `["video",` `"image"]`	The type of item that matched.
`rank`	`int`	The relevance ranking assigned by the model.
`item_id`	`str`	The unique identifier of the matching item.
`metadata`	`Optional` `[KnowledgeStore` `SearchItemMetadata]`	Metadata for the item. Returned when the `include_metadata` parameter is set to `true`.
`matches`	`List` `[VideoMatch]`	The matching clips within the video. Present only when `asset_type` is `video`.

The VideoMatch class contains the following properties:

Name	Type	Description
`start_sec`	`float`	The clip start offset, in seconds, within the source video.
`end_sec`	`float`	The clip end offset, in seconds, within the source video.
`modalities`	`List` `[VideoSearch` `Modality]`	The modalities that matched in this clip.
`transcription`	`Optional[str]`	The spoken words in the clip. Returned when spoken-word data is available for the clip, regardless of which modalities matched.

API Reference

Search a knowledge store.