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:

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>",
  query={
    "$or": [
      {
        "text": "red car",
      },
      {
        "text": "blue car",
      }
    ]
  },
  options=["visual"],
)

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
    )

print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

  import { TwelveLabs, SearchData } from 'twelvelabs-js';

  const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});  
  
  let searchResults = await client.search.query({
    indexId: '<YOUR_INDEX_ID>',
    query: {
      $or: [
        {
          text: 'red car',
        },
        {
          text: 'blue car',
        },
      ],
    },
    options: ['visual'],
  });
  printPage(searchResults.data);
  while (true) {
    const page = await searchResults.next();
    if (page === null) break;
    else printPage(page);
  }
  // Utility function to print a specific page
  function printPage(searchData) {
    (searchData as SearchData[]).forEach((clip) => {
      console.log(
        `video_id= ${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
      );
    });

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.

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query={
        "$not": {
            "origin": {
                "$and": [
                    {
                        "text": "Someone is cooking",
                    },
                    {
                        "text": "Italian food",
                        "search_options": ["conversation"]
                    }
                ]
            },
            "sub": {
                "$or": [
                    {
                        "text": "spaghetti",
                        "search_options": ["text_in_video"]
                    },
                    {
                        "text": "lasagna",
                        "search_options": ["conversation"]
                    }
                ]
            }
        }
    },
    options=["visual"],
)

# Utility function to print a specific page


def print_page(page):
    for clip in page:
        print(
            f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
        )


print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

import { TwelveLabs, SearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  query: {
    $not: {
      origin: {
        $and: [
          {
            text: 'Someone is cooking',
          },
          {
            text: 'Italian food',
            search_options: ['conversation'],
          },
        ],
      },
      sub: {
        $or: [
          {
            text: 'spaghetti',
            search_options: ['text_in_video'],
          },
          {
            text: 'lasagna',
            search_options: ['conversation'],
          },
        ],
      },
    },
  },
  options: ['visual'],
});
printPage(searchResults.data);
while (true) {
  const page = await searchResults.next();
  if (page === null) break;
  else printPage(page);
}
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id= ${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
    );
  });
}

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.