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
Updated 2 months ago