Advanced techniques (v1.2)

This section illustrates some advanced techniques you can use to extend the functionality of combined queries.

Time-proximity search

When building combined queries, you can use the proximity parameter to extend the lower and upper boundaries of each subquery. This parameter is expressed in seconds.

Note that the proximity parameter can only be used when your combined query is composed of two or more subqueries.

The following example code uses the and operator and the proximity parameter to find all car accidents that happened within 30 seconds before someone wins a race:

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={
8         "$and": [
9           {
10               "text": "winning the race"
11           },
12             {
13               "text": "car accident"
14           }
15         ],
16         "proximity": 30
17     },
18     options=["visual"],
19 )
20 
21 # Utility function to print a specific page
22 
23 def print_page(page):
24     for clip in page:
25         print(
26             f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
27         )
28 
29 
30 print_page(search_results.data)
31 
32 while True:
33     try:
34         print_page(next(search_results))
35     except StopIteration:
36         break

The following output was truncated for brevity:

video_id=65d5fbad48db9fa780cb417a score=83.7 start=283.0 end=325.0 confidence=high
video_id=65d5fbad48db9fa780cb417a score=83.69 start=342.0 end=377.0 confidence=high
video_id=65d60bcf48db9fa780cb417a score=83.62 start=323.0 end=334.0 confidence=high

Specify the order of the matching video clips

The example code below uses the then operator to find the moments in your videos where the following occur in the specified order:

A player makes a long pass.
A player dribbles past a defender.

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={
8         "$then": [
9             {
10                 "text": "Player is making a long pass"
11             },
12             {
13                 "text": "Player is dribbling past a defender"
14             }
15         ]
16     },
17     options=["visual"],
18 )
19 
20 # Utility function to print a specific page
21 def print_page(page):
22     for clip in page:
23         print(
24             f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
25         )
26 
27 
28 print_page(search_results.data)
29 
30 while True:
31     try:
32         print_page(next(search_results))
33     except StopIteration:
34         break

The following example output was truncated for brevity:

video_id=65d60bcf48db9fa780cb412a score=83.22 start=419.0 end=444.0 confidence=high
video_id=65d5fbad48db9fa780cb412a score=82.75 start=47.0 end=75.0 confidence=medium
video_id=65d60bcf48db9fa780cb412a score=78.21 start=294.0 end=304.0 confidence=medium

The example code below combines the then and or operators to find all the moments in your videos where the following occur in the specified order:

A player makes a long pass or the words “amazing pass” are mentioned in the conversation
A player dribbles past a defender.

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={
8         "$then": [
9             {
10                 "$or": [
11                     {
12                         "text": "Player makes a long pass"
13                     },
14                     {
15                         "text": "Amazing pass",
16                         "search_options": ["conversation"]
17                     }
18                 ]
19             },
20             {
21                 "text": "Player dribbles past a defender"
22             }
23         ]
24     },
25     options=["visual"],
26 )
27 
28 # Utility function to print a specific page
29 def print_page(page):
30     for clip in page:
31         print(
32             f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
33         )
34 
35 
36 print_page(search_results.data)
37 
38 while True:
39     try:
40         print_page(next(search_results))
41     except StopIteration:
42         break

The following example output was truncated for brevity:

video_id=65d60bcf48db9fa780cb41bd score=83.53 start=339.0 end=370.0 confidence=high
video_id=65d5fbad48db9fa780cb41bd score=83.41 start=122.0 end=283.0 confidence=high
video_id=65d5fbad48db9fa780cb41bd score=83.35 start=612.0 end=640.0 confidence=high

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={
8	"$and": [
9	{
10	"text": "winning the race"
11	},
12	{
13	"text": "car accident"
14	}
15	],
16	"proximity": 30
17	},
18	options=["visual"],
19	)
20
21	# Utility function to print a specific page
22
23	def print_page(page):
24	for clip in page:
25	print(
26	f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
27	)
28
29
30	print_page(search_results.data)
31
32	while True:
33	try:
34	print_page(next(search_results))
35	except StopIteration:
36	break