GuidesSearch

Pagination

The SDKs provide two distinct methods, each suited to different use cases and requirements. Selecting the most efficient method is important for optimizing the performance of your application:

  • Iterative pagination: Choose this method mainly when your application must retrieve a large number of items.
  • Direct pagination: Choose this method mainly when the total number of items is manageable, or you must fetch a single page of results.

Iterative pagination

To retrieve the first page of results, invoke the search.query method:

Python
1search_results = client.search.query(
2    index_id="<YOUR_INDEX_ID", 
3    query_text="<YOUR_QUERY>", 
4    options=["visual"]
5)

To retrieve subsequent pages of results, use the iterator protocol:

Python
1search_results = client.search.query(
2    index_id="<YOUR_INDEX_ID>", 
3    query_text="<YOUR_QUERY>", 
4    options=["visual"]
5)
6
7
8def print_page(page):
9    for clip in page:
10        print(
11            f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
12        )
13
14print_page(search_results.data)
15
16while True:
17    try:
18        print_page(next(search_results))
19    except StopIteration:
20        break

Use the page_limit parameter to specify a limit of items on each page. The example below sets the limit to 5:

Python
1search_results = client.search.query(
2    index_id="<YOUR_INDEX_ID>, 
3    query_text="<YOUR_QUERY>", 
4    options=["visual"],
5    page_limit=5
6)

When the response is grouped by video, you can use the page_limit parameter to specify the number of videos the platform will return on each page. The following example code sets the page limit to three and specifies that the result must be grouped by video:

Python
1search_results = client.search.query(
2    index_id="<YOUR_INDEX_ID>", 
3    query_text="<YOUR_QUERY>", 
4    options=["visual"],
5    page_limit=3,
6    group_by="video"
7)

Direct pagination

To retrieve the first page of results, invoke the search.query method:

Python
1search_results = client.search.query(
2    index_id="<YOUR_INDEX_ID>", 
3    query_text="<YOUR_QUERY>", 
4    options=["<YOUR_SEARCH_OPTIONS>"]
5)

The response will contain an object named page_info containing the following properties:

  • limit_per_page: The maximum number of results per page.
  • total_results: The total number of results.
  • page_expires_at: The time when the current page expires.
  • next_page_token: A token you can use to retrieve the results on the next page. The platform doesn’t return this field when you’ve reached the end of the dataset
  • prev_page_token: A token you can use to retrieve the results on the previous page. The platform doesn’t return this field when you’ve retrieved the first page.

To retrieve a specific page of results, invoke the search.by_page_token method, passing the next_page_token property of the page_info object as the value of the page_token parameter. The response will be similar to the one returned when retrieving the first page of results. When the platform does not return the next_page_token field, you’ve reached the end of the dataset.

Python
1search_results = client.search.by_page_token(page_token="<YOUR_PAGE_TOKEN>")

Use the page_limit parameter to specify a limit of items on each page. The example below sets the limit to 5:

Python
1search_results = client.search.query(
2    index_id="<YOUR_INDEX_ID", 
3    query_text="<YOUR_QUERY>", 
4    options=["<YOUR_SEARCH_OPTIONS>"],
5    page_limit=5
6)
Note

When the response is grouped by video, you can use the page_limit parameter to specify the number of videos the platform will return on each page.