Search results
You can sort your search results using the sort_option
and group_by
parameters. Note that, for each matching video clip, the platform returns a field named confidence
representing the level of confidence that a specific video clip matches your query.
When you don't specify the group_by
parameter, the platform returns your search results as a flat list, sorted on the confidence
field in descending order.
When you set the group_by
parameter to video
, the platform returns your search results grouped by video, sorts the clips belonging to each video on the confidence
field in descending order, and you can use the sort_option
parameter as follows:
- Set it to
clip_count
to specify that the platform must determine the number of matching video clips in each video, and sort the list of videos on that value in descending order. - Set it to
score
to specify that the platform must determine the maximum value of theconfidence
field for each video, and sort the list of videos on that value in descending order.
Note that the platform doesn't support grouping when using combined queries.
For a description of each field in the request and response, see the API Reference > Make any-to-video search request page.
Prerequisites
- You're familiar with the concepts that are described on the Platform overview page.
- You've already created an index, and the Marengo video understanding engine is enabled for this index.
- You've already uploaded a video, and the platform has finished indexing it.
Examples
Sorting video clips
The following example code illustrates the default behavior of the platform. The search results are sorted on the level of confidence in descending order.
from twelvelabs import TwelveLabs
client = TwelveLabs(api_key="<YOUR_API_KEY>")
search_results = client.search.query(
index_id="YOUR_INDEX_ID",
query_text="<YOUR_QUERY>",
options=["visual"],
group_by="clip", # This parameter is optional
sort_option="score" # This parameter is optional
)
# 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} metadata={clip.metadata}"
)
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>'
queryText: '<YOUR_QUERY>',
options: ['visual'],
groupBy: 'clip', // This parameter is optional
sortOption: 'score', // This parameter is optional
});
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} metadata=${JSON.stringify(clip.metadata)}`,
);
});
}
The following output was truncated for brevity:
video_id=65e013b448db9fa780cb4379 score=56.75 start=366.4375 end=372.140625 confidence=low metadata=[{'type': 'visual'}]
video_id=65e013b448db9fa780cb4379 score=56.53 start=377.46875 end=382.25 confidence=low metadata=[{'type': 'visual'}]
video_id=65e013b448db9fa780cb4379 score=54.1 start=17.71875 end=22.875 confidence=low metadata=[{'type': 'visual'}]
In this example, note that the data
array contains a list of objects, and each object corresponds to a video clip that matched your query. The data
array is sorted on the value of the score
field in descending order.
Sorting videos
When your search results are grouped by vides, you can use the sort_option
to sort the list of videos in the response.
Sorting videos on the number of matches
The following example code groups the response by video and sorts the list of videos on the number of matches:
from twelvelabs import TwelveLabs
client = TwelveLabs(api_key="<YOUR_API_KEY>")
search_results = client.search.query(
index_id="<YOUR_INDEX_ID>,
query_text="<YOUR_QUERY>",
options=["visual"],
group_by="video",
sort_option="clip_count"
)
# Utility function to print a specific page
def print_page(page):
for video in page:
print(f"Video id: {video.id}")
for clip in video.clips:
print(
f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
)
print_page(search_results.data)
while True:
try:
print_page(next(search_results))
except StopIteration:
break
import { TwelveLabs, GroupByVideoSearchData } from 'twelvelabs-js';
const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});
let searchResults = await client.search.query({
indexId: '<YOUR_INDEX_ID>',
queryText: '<YOUR_QUERY>',
options: ['visual'],
groupBy: 'video',
sortOption: 'clip_count',
});
printPage(searchResults);
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.data as GroupByVideoSearchData[]).forEach((video) => {
console.log(`videoId=${video.id}`);
video.clips?.forEach((clip) => {
console.log(
` score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
);
});
});
}
The following output was truncated for brevity:
video_id=65e013b448db9fa780cb4379 score=85.21 start=253.484375 end=270.71875 confidence=high metadata=[{'type': 'visual'}]
video_id=65e013b448db9fa780cb4379 score=85.18 start=438.0625 end=447.09375 confidence=high metadata=[{'type': 'visual'}]
video_id=65e013b448db9fa780cb4379 score=85.11 start=541.96875 end=578.34375 confidence=high metadata=[{'type': 'visual'}]
Note the following about this example:
- The
data
array contains a list of objects. Each object corresponds to a video and is composed of the following key-value pairs:id
: The unique identifier of the video to which the items in theclips
array belong.clips
: A list of the video clips that match your search terms.
- The list of videos is sorted on the number of video clips in each video in descending order.
- The video clips in the
clips
arrays are sorted on theconfidence
field in descending order.
Sorting videos on the level of confidence
The following example code groups the response by video and sorts the list of videos on the maximum value of the confidence
field:
from twelvelabs import TwelveLabs
client = TwelveLabs(api_key="<YOUR_API_KEY>")
search_results = client.search.query(
index_id="<YOUR_INDEX_ID>",
query_text="<YOUR_QUERY",
options=["visual"],
group_by="video",
sort_option="score"
)
# Utility function to print a specific page
def print_page(page):
for video in page:
print(f"Video id: {video.id}")
for clip in video.clips:
print(
f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
)
print_page(search_results.data)
while True:
try:
print_page(next(search_results))
except StopIteration:
break
import { TwelveLabs, GroupByVideoSearchData } from 'twelvelabs-js';
const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});
let searchResults = await client.search.query({
indexId: '<YOUR_INDEX_ID>',
queryText: '<YOUR_QUERY>',
options: ['visual'],
groupBy: 'video',
sortOption: 'score',
});
printPage(searchResults);
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.data as GroupByVideoSearchData[]).forEach((video) => {
console.log(`videoId=${video.id}`);
video.clips?.forEach((clip) => {
console.log(
` score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
);
});
});
}
The following output was truncated for brevity:
Video id: 65d6131c48db9fa780cb415f
video_id=65d6131c48db9fa780cb415f score=83.3 start=273.96875 end=289.0625 confidence=high metadata=[{'type': 'visual'}]
video_id=65d6131c48db9fa780cb415f score=83.21 start=357.40625 end=370.78125 confidence=high metadata=[{'type': 'visual'}]
video_id=65d6131c48db9fa780cb415f score=83.18 start=388.0234375 end=439.84375 confidence=high metadata=[{'type': 'visual'}]
Note the following about this example:
- The
data
array contains a list of objects. Each object corresponds to a video and is composed of the following key-value pairs:id
: The unique identifier of a video to which the items in theclips
array belong.clips
: A list of the video clips that match your search terms.
- The list of videos is sorted on the maximum value of the
confidence
field in descending order. - The video clips in the
clips
arrays are sorted on theconfidence
field in descending order.
Updated 25 days ago