Advanced techniques

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

You can interact with the platform using one of the available SDKs or an HTTP client like requests or axios. This guide demonstrates how to use the SDKs, the recommended approach for most scenarios. If you need to make direct HTTP requests, refer to the API Reference > Make a combined search request page for details.

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:

from twelvelabs import TwelveLabs

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

search_results = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query={
        "$and": [
          {
              "text": "winning the race"
          },
            {
              "text": "car accident"
          }
        ],
        "proximity": 30
    },
    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: {
    $and: [
      {
        text: 'winning the race',
      },
      {
        text: 'car accident',
      },
    ],
    proximity: 30,
  },
  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=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.

from twelvelabs import TwelveLabs

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

search_results = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query={
        "$then": [
            {
                "text": "Player is making a long pass"
            },
            {
                "text": "Player is dribbling past a defender"
            }
        ]
    },
    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: {
    $then: [
      {
        text: 'Player is making a long pass',
      },
      {
        text: 'Player is dribbling past a defender',
      },
    ],
  },
  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 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.

from twelvelabs import TwelveLabs

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

search_results = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query={
        "$then": [
            {
                "$or": [
                    {
                        "text": "Player makes a long pass"
                    },
                    {
                        "text": "Amazing pass",
                        "search_options": ["conversation"]
                    }
                ]
            },
            {
                "text": "Player dribbles past a defender"
            }
        ]
    },
    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: {
    $then: [
      {
        $or: [
          {
            text: 'Player makes a long pass',
          },
          {
            text: 'Amazing pass',
            search_options: ['conversation'],
          },
        ],
      },
      {
        text: 'Player dribbles past a defender',
      },
    ],
  },
  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 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