Methods

Make a search request

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

Function signature and example:

def query(
    self,
    index_id: str,
    options: List[Literal["visual", "conversation", "text_in_video", "logo"]],
    *,
    query_text: str = None,
    query_media_type: Literal["image"] = None,
    query_media_file: Union[str, BinaryIO, None] = None,
    query_media_url: str = None,
    group_by: Optional[Literal["video", "clip"]] = None,
    threshold: Optional[Literal["high", "medium", "low", "none"]] = None,
    operator: Optional[Literal["or", "and"]] = None,
    conversation_option: Optional[Literal["semantic", "exact_match"]] = None,
    filter: Optional[Dict[str, Any]] = None,
    page_limit: Optional[int] = None,
    sort_option: Optional[Literal["score", "clip_count"]] = None,
    adjust_confidence_level: Optional[float] = None,
    **kwargs
) -> models.SearchResult

from twelvelabs.models.search import SearchData, GroupByVideoSearchData

def print_search_data(data: SearchData):
    print(f"  Score: {data.score}")
    print(f"  Start: {data.start}")
    print(f"  End: {data.end}")
    print(f"  Video ID: {data.video_id}")
    print(f"  Confidence: {data.confidence}")
    print(f"  Thumbnail URL: {data.thumbnail_url}")
    if data.metadata:
        print("  Metadata:")
        for meta in data.metadata:
            for key, value in meta.items():
                print(f"    {key}: {value}")
    if data.module_confidence:
        print("  Module confidence:")
        for module, confidence in data.module_confidence.items():
            print(f"    {module}: {confidence}")
    if data.modules:
        print("  Modules:")
        for module in data.modules:
            print(f"    {module}")

result = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    options=["visual", "conversation", "text_in_video", "logo"],
    query_text="<YOUR_QUERY>",
    group_by="clip",
    # threshold="medium",
    operator="or",
    conversation_option="semantic",
    # filter={"category": "nature"},
    page_limit=5,
    sort_option="score",
    # adjust_confidence_level=0.5
)

# Print the search pool information
print("Search pool:")
print(f"  Total count: {result.pool.total_count}")
print(f"  Total duration: {result.pool.total_duration}")
print(f"  Index ID: {result.pool.index_id}")

# Print the search results
print("Search Results:")
for item in result.data:
    if isinstance(item, GroupByVideoSearchData):
        print(f"Video ID: {item.id}")
        if item.clips:
            for clip in item.clips:
                print_search_data(clip)
    else:
        print_search_data(item)

# Print the page information
print("Page information:")
print(f"  Limit per page: {result.page_info.limit_per_page}")
print(f"  Total results: {result.page_info.total_results}")
print(f"  Page expired at: {result.page_info.page_expired_at}")
print(f"  Next page token: {result.page_info.next_page_token}")
print(f"  Previous page token: {result.page_info.prev_page_token}")

Parameters:

Name	Type	Required	Description
`index_id`	`str`	Yes	The unique identifier of the index to search.
`options`	`List[Literal["visual", "conversation", "text_in_video", "logo"]]`	Yes	Specifies the sources of information the platform uses when performing a search.
`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`	`Union[str, BinaryIO, None]`	No	The path to a media file or a file-like object 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.
`group_by`	`Optional[Literal["video", "clip"]]`	No	Use this parameter to group or ungroup items in a response.
`threshold`	`Optional[Literal["high", "medium", "low", "none"]]`	No	Filter on the level of confidence that the results match your query.
`operator`	`Optional[Literal["or", "and"]]`	No	Logical operator for combining search options.
`conversation_option`	`Optional[Literal["semantic", "exact_match"]]`	No	The type of match the platform performs.
`filter`	`Optional[Dict[str, Any]]`	No	Additional filters for the search.
`page_limit`	`Optional[int]`	No	The maximum number of results per page.
`sort_option`	`Optional[Literal["score", "clip_count"]]`	No	The sort order for the response.
`adjust_confidence_level`	`Optional[float]`	No	The strictness of the thresholds for assigning the high, medium, or low confidence levels to search results.
`**kwargs`	`dict`	No	Additional keyword arguments for the request.

Return value: Returns a models.SearchResult object containing the search results.

API Reference: For a detailed description of each field in the request and response, see the Any-to-video search page.

Related guides:

Retrieve a specific page of search results

Description: This method retrieves a specific page of search results. This method provides direct pagination. Choose it mainly when the total number of items is manageable, or you must fetch a single page of results.

Function signature and example:

def by_page_token(self, page_token: str, **kwargs) -> models.SearchResult

from twelvelabs.models.search import SearchData, GroupByVideoSearchData

def print_search_data(data: SearchData):
    print(f"  Score: {data.score}")
    print(f"  Start: {data.start}")
    print(f"  End: {data.end}")
    print(f"  Video ID: {data.video_id}")
    print(f"  Confidence: {data.confidence}")
    print(f"  Thumbnail URL: {data.thumbnail_url}")
    if data.metadata:
        print("  Metadata:")
        for meta in data.metadata:
            for key, value in meta.items():
                print(f"    {key}: {value}")
    if data.module_confidence:
        print("  Module confidence:")
        for module, confidence in data.module_confidence.items():
            print(f"    {module}: {confidence}")
    if data.modules:
        print("  Modules:")
        for module in data.modules:
            print(f"    {module}")

result = client.search.by_page_token("<YOUR_PAGE_TOKEN>")

# Print the search pool information
print("Search pool:")
print(f"  Total count: {result.pool.total_count}")
print(f"  Total duration: {result.pool.total_duration}")
print(f"  Index ID: {result.pool.index_id}")

# Print the search results
print("Search Results:")
for item in result.data:
    if isinstance(item, GroupByVideoSearchData):
        print(f"Video ID: {item.id}")
        if item.clips:
            for clip in item.clips:
                print_search_data(clip)
    else:
        print_search_data(item)

# Print the page information
print("Page information:")
print(f"  Limit per page: {result.page_info.limit_per_page}")
print(f"  Total results: {result.page_info.total_results}")
print(f"  Page expired at: {result.page_info.page_expired_at}")
print(f"  Next page token: {result.page_info.next_page_token}")
print(f"  Previous page token: {result.page_info.prev_page_token}")

Parameters:

Name	Type	Required	Description
`pageToken`	`str`	Yes	A token that identifies the page to retrieve.
`**kwargs`	`dict`	No	Additional keyword arguments for the request..

Return value: Returns a models.SearchResult object containing the search results.

API Reference: For a description of each field in the request and response, see the Retrieve a specific page of search results page.

Related guides:

Iterative pagination

If your application must retrieve a large number of items, use iterative pagination. To retrieve the first page of results, invoke the query method of the search object. To retrieve subsequent pages of results, use the iterator protocol.

from twelvelabs.models.search import SearchData, GroupByVideoSearchData

def print_search_data(data: SearchData):
    print(f"  Score: {data.score}")
    print(f"  Start: {data.start}")
    print(f"  End: {data.end}")
    print(f"  Video ID: {data.video_id}")
    print(f"  Confidence: {data.confidence}")
    print(f"  Thumbnail URL: {data.thumbnail_url}")
    if data.metadata:
        print("  Metadata:")
        for meta in data.metadata:
            for key, value in meta.items():
                print(f"    {key}: {value}")
    if data.module_confidence:
        print("  Module confidence:")
        for module, confidence in data.module_confidence.items():
            print(f"    {module}: {confidence}")
    if data.modules:
        print("  Modules:")
        for module in data.modules:
            print(f"    {module}")

def print_page(result):
    # Print the search results
    print("Search Results:")
    for item in getattr(result, 'data', result):
        if isinstance(item, GroupByVideoSearchData):
            print(f"Video ID: {item.id}")
            if item.clips:
                for clip in item.clips:
                    print_search_data(clip)
        else:
            print_search_data(item)


# Initial query
search_results = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    options=["visual", "conversation", "text_in_video", "logo"],
    query_text="man laughing",
    group_by="clip",
    # threshold="medium",
    operator="or",
    conversation_option="semantic",
    # filter={"category": "nature"},
    page_limit=2,
    sort_option="score",
    # adjust_confidence_level=0.5
)

# Print the search pool information
print("Search pool:")
print(f"  Total count: {search_results.pool.total_count}")
print(f"  Total duration: {search_results.pool.total_duration}")
print(f"  Index ID: {search_results.pool.index_id}")

# Print the first page
print_page(search_results)

# Print subsequent pages using the iterator protocol
page_number = 2
while True:
    try:
        print(f"Page {page_number}")
        print_page(next(search_results))
        page_number += 1
    except StopIteration:
        break

print("No more results.")