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.

Use the query.text field to specify your natural-language query. Use the filter parameter to choose which items to search. Use the search_options parameter to choose how the platform matches videos.

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:

def search(
    self,
    knowledge_store_id: str,
    *,
    query: KnowledgeStoreSearchQuery,
    filter: typing.Optional[SearchKnowledgeStoreFilter] = OMIT,
    search_options: typing.Optional[SearchKnowledgeStoreOptions] = OMIT,
    group_by: typing.Optional[SearchKnowledgeStoreRequestGroupBy] = OMIT,
    page_size: typing.Optional[int] = OMIT,
    page_token: typing.Optional[str] = OMIT,
    include_metadata: typing.Optional[bool] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> 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 provide options in the `search_options.video` field when the `filter.asset_type` field excludes videos, the platform returns a `400` error. 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. If a token is malformed or unrecognized, the platform returns a `400` error. If a token has expired, the platform 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 these fields: - `system`: System-generated metadata, such as duration and resolution. - `user`: The custom metadata of the source asset. - `item`: The custom metadata of the knowledge store 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. Omit the filter to search all items. An item must match all of the fields that you specify. The tags field also limits which clips of an item the search returns. When you use any of the user_metadata, enrichment, created_at, or location fields, the platform counts the items that match those conditions together. If more than 10,000 items match, the platform returns a 422 error with the metadata_filter_too_broad code. To reduce the count, add conditions or use the item_id field. The asset_type field does not reduce the count. When you use the tags field, the platform does not count items, and this limit does not apply. It counts the matching tags instead, as the TagFilter class describes. 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.
`user_metadata`	`Optional` `[UserMetadataFilter]`	No	Narrows results by custom metadata. Map each key to a `MetadataValueFilter` object with exactly one of the `eq` or `in_` operators. You can specify 1 to 50 keys. An item must match all of the keys that you specify. A key matches the custom metadata of the source asset (the `metadata` field of the knowledge store item) and the custom metadata of the knowledge store item (the `item_metadata` field). An item matches a key when the value matches in either field. For the names of these fields in search results, see the Custom metadata field names section on The knowledge store item object page. `eq` (a `str`, `int`, `float`, or `bool`): Match items that have this value for the key. The value must have the same type as the value that the item has for the key. For example, the number `2026` does not match the string `"2026"`. If the item has a list for the key, the item matches when the list contains the value. `in_` (a list of `str`, `int`, `float`, or `bool` values): Match items that have any of these values for the key. You can specify 1 to 100 values. Each value follows the rules for the `eq` operator. For example, `["tutorial", "guide"]` matches items that have the value `tutorial` or `guide`.
`enrichment`	`Optional` `[EnrichmentFilter]`	No	Narrows results by enrichment values. The platform extracts these values as the enrichment configuration of the knowledge store defines (the `ingestion_config.enrichment_config` field). Map each top-level property that the enrichment configuration defines to a `MetadataValueFilter` object with exactly one of the `eq` or `in_` operators. You can specify 1 to 50 keys. If you specify a key that the enrichment configuration does not define, the platform returns a `400` error. The `granularity` keyword of a property sets how often the platform extracts its value. The keyword also sets which items the key matches: - `video`: One value for each video. The key matches video items only. - `image`: One value for each image. The key matches image items only. - `shot`: One value for each shot of a video. A shot is a continuous part of a video between two scene changes. The key matches video items only. If you specify more than one `shot` key, one shot must have all of the values. For example, a filter with the keys `topic` and `sentiment` at the `shot` granularity matches a video only when one shot has both values. An item must match all of the keys that you specify. A filter with a `video` key and an `image` key matches no items, because an item is a video or an image. Use the filter to choose which items to search. The search can return any clip of a matching item, including clips that do not match the filter. `eq` (a `str`, `int`, `float`, or `bool`): Match items that have this value for the key. The value must have the same type as the value that the item has for the key. For example, the number `2026` does not match the string `"2026"`. If the item has a list for the key, the item matches when the list contains the value. `in_` (a list of `str`, `int`, `float`, or `bool` values): Match items that have any of these values for the key. You can specify 1 to 100 values. Each value follows the rules for the `eq` operator. For example, `["tutorial", "guide"]` matches items that have the value `tutorial` or `guide`.
`created_at`	`Optional` `[CreatedAtFilter]`	No	Narrows results by the creation time of the item. Use `gte` (a `datetime`) to set the earliest time and `lte` (a `datetime`) to set the latest time. You can use one or both. When you use both, the `gte` time must be equal to or earlier than the `lte` time. The creation time is the time when you create the item with the `create` method of `client.knowledge_store_items`. It is not the time when the item reaches the `ready` status. To read the creation time of an item, use the `retrieve` method of `client.knowledge_store_items`. The time is in the `created_at` field.
`location`	`Optional` `[GeoCircleFilter]`	No	Narrows results to items captured within a circle.
`tags`	`Optional` `[TagFilter]`	No	Narrows results to the moments and ranges that matching tags mark on video items.

The GeoCircleFilter class narrows results to items captured within a circle. An item matches when the GPS coordinates embedded in its source media are within radius_meters of the center, measured as great-circle distance. Items with no coordinates never match. To read the GPS coordinates of the source media, use the retrieve method of client.assets. The coordinates are the geospatial_latitude and geospatial_longitude fields of the technical_metadata object. It contains the following properties:

Name	Type	Required	Description
`latitude`	`float`	Yes	The latitude of the center, in decimal degrees. The value must be between -90 and 90.
`longitude`	`float`	Yes	The longitude of the center, in decimal degrees. The value must be between -180 and 180.
`radius_meters`	`float`	Yes	The radius of the circle, in meters. The value must be greater than 0 and at most 20,037,508.

The TagFilter class narrows results to the moments and ranges that matching tags mark on video items. A tag matches when its tag_metadata field matches the metadata field. Only video items have tags, so images do not appear in the results. The search returns only the clips within a matching tag:

For a tag on a range, a clip matches when it lies entirely within the range. A clip that extends past either end of the range does not appear in the results.
For a tag on a single moment, a clip matches when it contains that moment.

A clip within more than one matching tag appears once. With the group_by parameter set to item, each item groups only its clips within matching tags. When you specify other fields of the filter, a tag counts only when its item matches every other field. The asset_type field does not reduce the count. If more than 100 tags match, the platform returns a 422 error with the metadata_filter_too_broad code. To tag a moment or a range of a video item, use the create method of client.knowledge_store_item_tags. It contains the following property:

Name	Type	Required	Description
`metadata`	`Dict` `[str, Metadata` `ValueFilter]`	Yes	The metadata to match against the `tag_metadata` field of each tag. Map each key to a `MetadataValueFilter` with exactly one operator: `eq` to match one value, or `in_` (a list of 1 to 100 values) to match any of the listed values. Specify 1 to 50 keys. When you specify more than one key, every key must match on the same tag. A value is a string, a number, or a boolean. The platform matches it with the JSON type the tag stores, so `2026` does not match a tag that stores `"2026"`. A key that stores a list matches when the list contains the value.

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` `[VideoSearch` `ItemMetadata] or` `Optional` `[ImageSearch` `ItemMetadata]`	Metadata attached to the item. Returned when you set the `include_metadata` parameter to `true`. A `VideoSearchItemMetadata` object for video results, an `ImageSearchItemMetadata` object for image results.
`matches`	`List` `[VideoMatch]`	The matching clips within the video. Present only when `asset_type` is `video`.

The VideoSearchItemMetadata class contains metadata attached to a video knowledge store item in search results. It contains the following properties:

Name	Type	Description
`system`	`Optional` `[VideoSearch` `SystemMetadata]`	System-generated metadata for the source video.
`user`	`Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata.
`item`	`Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	The custom metadata of the knowledge store item. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the `user` field and in the `item` field. The `item_metadata` field of the knowledge store item contains the same metadata. This field is absent when no item metadata has been set.

The ImageSearchItemMetadata class contains metadata attached to an image knowledge store item in search results. It contains the following properties:

Name	Type	Description
`system`	`Optional` `[ImageSearch` `SystemMetadata]`	System-generated metadata for the source image.
`user`	`Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata.
`item`	`Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	The custom metadata of the knowledge store item. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the `user` field and in the `item` field. The `item_metadata` field of the knowledge store item contains the same metadata. This field is absent when no item metadata has been set.

The VideoSearchSystemMetadata class contains system-generated metadata for a video item in search results. It contains the following properties:

Name	Type	Description
`duration`	`Optional[float]`	The duration of the video in seconds.
`width`	`Optional[int]`	The width of the video in pixels.
`height`	`Optional[int]`	The height of the video in pixels.
`size`	`Optional[int]`	The file size of the video in bytes.

The ImageSearchSystemMetadata class contains system-generated metadata for an image item in search results. It contains the following properties:

Name	Type	Description
`width`	`Optional[int]`	The width of the image in pixels.
`height`	`Optional[int]`	The height of the image in pixels.
`size`	`Optional[int]`	The file size of the image in bytes.

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.