Search Patterns and Results

Find moments from a natural-language request

Use intelligent search when the user knows the goal but the application should not have to select indexes or retrieval methods.

response = collection.search(
    query="Find scenes where a red car enters a parking garage at night",
    top_k=10,
    return_fields=["scene", "objects"],
)

for shot in response:
    print(shot.video_id, shot.start, shot.end)

The same pattern works inside one video:

response = video.search(
    query="Find the moment the presenter reveals the final design",
    top_k=10,
)

Search by meaning

Use semantic search when the application should control which semantic indexes are searched.

results = video.semantic_search(
    query="a cyclist riding through heavy rain at night",
    index_names=["scene"],
    top_k=20,
    score_threshold=0.7,
)

Add exact conditions when a semantic match must satisfy additional criteria:

results = collection.semantic_search(
    query="an athlete using a phone near the finish line",
    index_names=["scene"],
    filter=[
        {"field": "brand_names", "op": "contains", "value": "Nike"},
        {"field": "object_labels", "op": "contains", "value": "cell phone"},
    ],
    top_k=20,
)

Filter search results

Filters are supported by default-mode search(), semantic_search(), query(), and aggregate(). A top-level list combines conditions with AND.

filter=[
    {"field": "brand_names", "op": "contains", "value": "Nike"},
    {"field": "max_score", "op": ">=", "value": 0.8},
]

Use an explicit OR or NOT when the conditions should be combined differently:

filter={
    "or": [
        {"field": "brand_names", "op": "contains", "value": "Nike"},
        {"field": "brand_names", "op": "contains", "value": "Adidas"},
    ]
}

filter={
    "not": {"field": "location_type", "op": "==", "value": "indoor"}
}

Filter operators

Operator	Example	Meaning
`==`	`{"field": "emotion", "op": "==", "value": "joy"}`	Field equals the value
`contains`	`{"field": "label", "op": "contains", "value": "car"}`	Text or an array contains the value
`in`	`{"field": "brand_names", "op": "in", "value": ["Nike", "Adidas"]}`	Field matches one of the values
`>=`	`{"field": "max_score", "op": ">=", "value": 0.8}`	Numeric lower bound
`<=`	`{"field": "max_score", "op": "<=", "value": 0.9}`	Numeric upper bound
`exists`	`{"field": "text", "op": "exists", "value": True}`	Field exists

See How index and field targeting works for selector and filter scoping examples.

Find every exact match

Use query for deterministic filtering and sorting on one index. This works well for review queues, inventories, dataset preparation, and compliance workflows.

results = collection.query(
    index_name="objects",
    filter=[
        {"field": "label", "op": "contains", "value": "cell phone"},
        {"field": "max_score", "op": ">=", "value": 0.8},
    ],
    limit=100,
    sort=[("max_score", "desc")],
)

Turn indexed signals into analytics

Use aggregation for counts, groups, and facets rather than moment playback.

response = collection.aggregate(
    index_name="brands",
    group_by="brand_names",
    metric="count",
    limit=100,
)

for row in response["results"]:
    print(row)

Apply a filter before grouping when the analysis should cover only part of the indexed data:

response = collection.aggregate(
    index_name="scene",
    filter=[
        {"field": "location_type", "op": "==", "value": "indoor"},
    ],
    group_by="emotion",
    metric="count",
    limit=100,
)

indoor_emotions = response["results"]

Aggregation returns its rows in response["results"], so playback methods do not apply to them. Read optional migration information with response.get("warnings", []).

Investigate and refine

Use DeepSearch for questions that benefit from multiple retrieval steps or follow-up requests.

response = collection.search(
    query="Trace how the crowd changes before, during, and after the winning goal",
    mode="deepsearch",
    top_k=10,
)

followup = collection.search(
    query="Only include moments where the home supporters are visible",
    mode="deepsearch",
    session_id=response.session_id,
    top_k=10,
)

Answer with supporting moments

Use Ask when the application should present a synthesized answer. Request sources when users should be able to inspect the supporting video moments.

answer = collection.ask(
    question="How does the storefront change from daytime to night?",
    include_sources=True,
)

print(answer.answer)

for source in answer.sources:
    print(source.video_id, source.start, source.end)

Inspect a result

Moment-returning methods provide Shot objects. A shot identifies where the result came from and where it occurs in the video.

shot = response.shots[0]

print(shot.video_id)
print(shot.video_title)
print(shot.start, shot.end)
print(shot.search_score)
print(shot.text)

Use return_fields when the interface should also show stored index evidence:

response = collection.search(
    query="Find someone discussing Nike while holding a phone",
    return_fields=["scene", "transcript", "objects", "brands"],
)

for shot in response:
    evidence = shot.metadata.get("indexes", {})
    print(evidence.get("transcript", []))
    print(evidence.get("objects", []))
    print(evidence.get("brands", []))

Play one matching moment

Call play() to open an individual shot in the VideoDB player:

shot = response.shots[0]
shot.play()

Use generate_stream() when the application needs the playable HLS URL:

stream_url = shot.generate_stream()
print(stream_url)

generate_stream() returns an existing stream URL when one is already available and generates one otherwise.

Compile several results

Direct semantic search and query return a SearchResult. Compile all of its shots into one stream:

results = video.semantic_search(
    query="sunset over a city skyline",
    index_names=["scene"],
)

stream_url = results.compile()

High-level Search and DeepSearch return a SearchResponse. Compile the nested SearchResult when the response contains shots:

response = collection.search(
    query="Find the best wildlife moments",
)

if response.response_type in {"shots", "deepsearch"}:
    stream_url = response.results.compile()

You can also play the compiled result directly:

response.results.play()

Embed a result

Generate an iframe for an individual moment:

shot = response.shots[0]
iframe = shot.get_embed_code()

Or embed a compiled set of results:

iframe = response.results.get_embed_code()

The embed helper generates the required player URL when it is not already available.

Build common search experiences

Experience	Useful result workflow
Search results page	Iterate over shots and show title, timestamps, score, and a play action
Evidence panel	Request `return_fields` and render `shot.metadata["indexes"]`
Highlight reel	Compile a `SearchResult` into one stream
Video Q&A	Call `ask(include_sources=True)` and make each source playable
Investigation workspace	Continue DeepSearch with `session_id` and preserve prior results
Analytics dashboard	Render aggregate rows as counts, groups, or facets

Video and collection scope

Use video.* when the search should stay inside one known video. Use collection.* when a result may come from any indexed video in the collection.

video.search(query="Find the red car entering the garage")
collection.search(query="Find red cars across the traffic footage")

The result and playback workflows remain the same at both scopes.

Next steps

Intelligent Search

Learn when to use Search, DeepSearch, and Ask.

Results and Evidence

Explore Shot fields, returned index data, and stream generation in detail.

Start Here

Core Concepts

Ingest

Understand

Act

Automate

Open Source Frameworks

Find moments from a natural-language request

Search by meaning

Filter search results

Filter operators

Find every exact match

Turn indexed signals into analytics

Investigate and refine

Answer with supporting moments

Inspect a result

Play one matching moment

Compile several results

Embed a result

Build common search experiences

Video and collection scope

Next steps

Intelligent Search

Results and Evidence

​Find moments from a natural-language request

​Search by meaning

​Filter search results

​Filter operators

​Find every exact match

​Turn indexed signals into analytics

​Investigate and refine

​Answer with supporting moments

​Inspect a result

​Play one matching moment

​Compile several results

​Embed a result

​Build common search experiences

​Video and collection scope

​Next steps

Intelligent Search

Results and Evidence

Find moments from a natural-language request

Search by meaning

Filter search results

Filter operators

Find every exact match

Turn indexed signals into analytics

Investigate and refine

Answer with supporting moments

Inspect a result

Play one matching moment

Compile several results

Embed a result

Build common search experiences

Video and collection scope

Next steps