Operators

The platform allows you to build combined queries using the following operators:

  • and: A dictionary where the key is the $and string, and the value is an array of objects. Each object is a subquery. The platform returns the video clips for which all the specified queries match.
  • or: A dictionary where the key is the $or string, and the value is an array of objects. Each object is a subquery. The platform returns the video clips for which at least one of the queries matches.
  • not: A dictionary where the key is the $not string and the value is a dictionary composed of two queries named origin and sub. The platform returns the video clips that match the origin query but do not match the sub query. Note that the origin and sub queries can include any number of subqueries.
  • then: A dictionary where the key is the $then string, and the value is an array of objects. Each object is a subquery. The platform will return only the results for which the order of the matching video clips is the same as the order of your queries.

The following is an example of a combined query that finds the moments in your videos where a blue or a red car appears:

1from twelvelabs import TwelveLabs
2
3client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5search_results = client.search.query(
6  index_id="<YOUR_INDEX_ID>",
7  query={
8    "$or": [
9      {
10        "text": "red car",
11      },
12      {
13        "text": "blue car",
14      }
15    ]
16  },
17  options=["visual"],
18)
19
20# Utility function to print a specific page
21def 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
27print_page(search_results.data)
28
29while True:
30    try:
31        print_page(next(search_results))
32    except StopIteration:
33        break

The following output was truncated for brevity:

 video_id=65d60bcf48db9fa780cb415e score=64.6 start=191.0 end=192.0 confidence=low
 video_id=65d6131c48db9fa780cb415f score=64.6 start=191.0 end=192.0 confidence=low
 video_id=65d60bcf48db9fa780cb415e score=64.6 start=368.0 end=369.0 confidence=low
 video_id=65d6131c48db9fa780cb415f score=64.6 start=368.0 end=369.0 confidence=low

The following is an example of a combined query that finds the moments in your video where:

  • Someone is cooking
  • Italian food is mentioned in the conversation
  • Neither the word spaghetti is displayed on the screen nor lasagna is mentioned in the conversation.
1from twelvelabs import TwelveLabs
2
3client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5search_results = client.search.query(
6    index_id="<YOUR_INDEX_ID>",
7    query={
8        "$not": {
9            "origin": {
10                "$and": [
11                    {
12                        "text": "Someone is cooking",
13                    },
14                    {
15                        "text": "Italian food",
16                        "search_options": ["conversation"]
17                    }
18                ]
19            },
20            "sub": {
21                "$or": [
22                    {
23                        "text": "spaghetti",
24                        "search_options": ["text_in_video"]
25                    },
26                    {
27                        "text": "lasagna",
28                        "search_options": ["conversation"]
29                    }
30                ]
31            }
32        }
33    },
34    options=["visual"],
35)
36
37# Utility function to print a specific page
38
39
40def print_page(page):
41    for clip in page:
42        print(
43            f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
44        )
45
46
47print_page(search_results.data)
48
49while True:
50    try:
51        print_page(next(search_results))
52    except StopIteration:
53        break

The following output was truncated for brevity:

video_id=65d6131c48db9fa780cb415f score=92.28 start=25.0 end=36.0 confidence=high
video_id=65d5fbad48db9fa780cb415c score=84.39 start=408.0 end=438.0 confidence=high
video_id=65d5fbad48db9fa780cb415c score=83.85 start=22.0 end=47.0 confidence=high

In the example code above, note that the value of the search_options parameter is set to ["visual"] for the entire query, and it is overridden on a per-subquery basis.

Built with