Grouping and ungrouping refer to the process of organizing the results of a search request in a specific way. The platform allows for grouping based on the unique identifiers of the videos. For example, this is useful when building a user interface, because it allows your users to better understand and navigate the search results. On the other hand, ungrouping presents your search results in a flat list. This is useful if you want to view all of the search results in a simple manner. Note that this feature can only be used with simple queries.

To group or ungroup items in a response, use the group_by parameter, specifying one of the following values:

• video: The platform will group the matching video clips in the response by video.
• clip: The matching video clips in the response will not be grouped.

For a description of each field in the request and response, see the API Reference> Make any-to-video search requests page.

Prerequisites

• You’re familiar with the concepts that are described on the Platform overview page.
• You’ve already created an index, and the Marengo video understanding engine is enabled for this index.
• You’ve already uploaded a video, and the platform has finished indexing it.

Examples

Grouping items in a response

The following example code groups the matching video clips in the response by video:

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
search_results = client.search.query(
6
  index_id="<YOUR_INDEX_ID>, 
7
  query_text="<YOUR_QUERY>, 
8
  options=["visual"],
9
  group_by="video"
10
)
11
12
# Utility function to print a specific page
13
def print_page(page):
14
    for video in page:
15
        print(f"Video id: {video.id}")
16
        for clip in video.clips:
17
            print(clip)
18
            print(
19
                f"\tscore={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
20
            )
21
22
print_page(search_results.data)
23
24
while True:
25
    try:
26
        print_page(next(search_results))
27
    except StopIteration:
28
        break

The output should look similar to the following one:

Video id: 65d60bcf48db9fa780cb415e
score=83.73 start=273.96875 end=289.0625 video_id='65d60bcf48db9fa780cb415e' metadata=[{'type': 'visual'}] confidence='high'
	score=83.73 start=273.96875 end=289.0625 confidence=high metadata=[{'type': 'visual'}]
score=83.55 start=397.921875 end=439.84375 video_id='65d60bcf48db9fa780cb415e' metadata=[{'type': 'visual'}] confidence='high'
	score=83.55 start=397.921875 end=439.84375 confidence=high metadata=[{'type': 'visual'}]
score=83.46 start=294.5625 end=311.84375 video_id='65d60bcf48db9fa780cb415e' metadata=[{'type': 'visual'}] confidence='high'
Video id: 65d5fbad48db9fa780cb415c
score=83.36 start=342.6875 end=353.140625 video_id='65d5fbad48db9fa780cb415c' metadata=[{'type': 'visual'}] confidence='high' thumbnail_url=None module_confidence=None
	score=83.36 start=342.6875 end=353.140625 confidence=high metadata=[{'type': 'visual'}]
score=83.32 start=164.671875 end=200.71875 video_id='65d5fbad48db9fa780cb415c' metadata=[{'type': 'visual'}] confidence='high' thumbnail_url=None module_confidence=None
	score=83.32 start=164.671875 end=200.71875 confidence=high metadata=[{'type': 'visual'}]
score=83.31 start=329.96875 end=337.75 video_id='65d5fbad48db9fa780cb415c' metadata=[{'type': 'visual'}] confidence='high' thumbnail_url=None module_confidence=None
	score=83.31 start=329.96875 end=337.75 confidence=high metadata=[{'type': 'visual'}]

In this example, note that the data array contains a list of objects. Each object corresponds to a video that matches your query and is composed of the following key-value pairs:

• clips: An array that groups the information about all the matching video clips in that video.
• id: The unique identifier of the video that matched your query.

Ungrouping items in a response

The following example performs a search request, and the matching video clips in the response are not grouped:

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
search_results = client.search.query(
6
  index_id="<YOUR_INDEX_ID>",
7
  query_text=  "<YOUR_QUERY>"
8
  options=["visual"],
9
  group_by='clip'
10
)
11
# Utility function to print a specific page
12
def print_page(page):
13
  for clip in page:
14
    print(
15
        f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
16
    )
17
18
print_page(search_results.data)
19
20
while True:
21
    try:
22
        print_page(next(search_results))
23
    except StopIteration:
24
        break

The output should look similar to the following one:

video_id=65d6131c48db9fa780cb415f score=52.04 start=4.5625 end=14.8125 confidence=low metadata=[{'type': 'visual'}]
 video_id=65d6131c48db9fa780cb415f score=50.94 start=20.9375 end=25.09375 confidence=low metadata=[{'type': 'visual'}]
 video_id=65d60bcf48db9fa780cb415e score=50.94 start=20.9375 end=25.09375 confidence=low metadata=[{'type': 'visual'}]