> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Indexes & Search

> Understand VideoDB's new Understand → Index → Retrieve workflow.

VideoDB separates video retrieval into three steps:

```text theme={null}
Understand → Index → Retrieve
```

## The model

| Step | What it does | SDK surface |
| - | - | - |
| **Understand** | Runs analyzers over video and creates reusable artifacts such as transcripts, objects, OCR, brand signals, activity, location, or VLM scene outputs. | `video.understand(...)` |
| **Index** | Chooses which artifact fields should become searchable, filterable, aggregatable, or sortable. | `video.index(...)` |
| **Retrieve** | Searches, filters, aggregates, and returns timestamped moments as playable evidence with selected fields from indexed artifacts. | `search()`, `semantic_search()`, `query()`, `aggregate()` |

Understanding finds what is in the video. Indexing organizes those findings for retrieval. Search, semantic search, query, and aggregation use those indexes to answer user questions.

<Note>
  Sandbox Compute is an independent runtime option for supported models. Use it during the Understand step when you want open-weight or specialized models; the Index step still uses the same `video.index(...)` interface.
</Note>

<Note>
  RTStreams follow the same model with continuous jobs: `rtstream.understand(...)` keeps producing VLM artifacts from live windows, and `rtstream.index(...)` keeps materializing them for search and alerts. Initial RTStream support is VLM-only with time-based segmentation. See [Understand & Index RTStreams](/pages/ingest/live-streams/rtstream-understand-index).
</Note>

***

## Quick example

```python theme={null}
import videodb

conn = videodb.connect()
video = conn.get_collection().get_video("m-xxx")

# 1. Understand the video with defaults
understanding = video.understand(
    analyzers=[
        {"type": "spoken_words", "name": "transcript"},
        {"type": "vlm", "name": "scene"},
    ],
)

understanding.wait_until_complete()

transcript = understanding.get_analyzer("transcript")
scene = understanding.get_analyzer("scene")

# 2. Index selected artifacts and wait for semantic retrieval
transcript_index = video.index(name="transcript", source=transcript)
scene_index = video.index(name="scene", source=scene)
transcript_index.wait_until_complete()
scene_index.wait_until_complete()

# 3. Retrieve playable evidence
results = video.semantic_search(
    query="person talking about a product while holding a phone",
    index_ids=[transcript_index.index_id, scene_index.index_id],
    top_k=10,
)

for shot in results.get_shots():
    print(shot.start, shot.end)
    stream_url = shot.generate_stream()
```

***

## What is an artifact?

An artifact is the output of one analyzer. Examples:

| Analyzer | Artifact | Example contents |
| - | - | - |
| `spoken_words` | `transcript` | timed spoken text |
| `object_detection` | `objects` | labels, counts, boxes |
| `vlm` | `scene` | scene descriptions and structured visual reasoning |
| `ocr` | `ocr` | visible text |
| `brand_detection` | `brands` | detected brands/logos/signals |

Artifacts are scene-aware: each output is tied to timestamps such as `start` and `end`.

***

## Retrieval modes

| API | Use when you want to... | Example |
| - | - | - |
| `search()` | use high-level natural-language search | “find scenes where someone talks about Nike while holding a phone” |
| `semantic_search()` | directly search semantic/vector fields | “happy reunion outside a shop” against the `scene` index |
| `query()` | apply explicit structured filters | `object_labels contains "phone"` |
| `aggregate()` | count, group, or facet indexed fields | count scenes by brand |

Moment-returning retrieval APIs include playable evidence by default. A retrieval request can also combine multiple indexes. For example:

> Find scenes where a person talks about Nike.

VideoDB can combine:

* a scene index for visual/person context
* a transcript index for “talks about Nike”
* a brand index for `Nike`
* playable evidence, transcript text, frames, and timestamps requested with `return_fields`

***

## Next steps

<CardGroup cols={3}>
  <Card icon="eye" title="Understanding Artifacts" href="/pages/understand/indexing-pipelines/understanding-artifacts">
    Create reusable video artifacts with analyzers.
  </Card>

  <Card icon="layers" title="Create an Index" href="/pages/understand/indexing-pipelines/create-an-index">
    Turn artifacts into searchable, queryable indexes.
  </Card>

  <Card icon="cpu" title="Sandbox Compute" href="/pages/core-concepts/sandbox-compute">
    Run supported open-weight and specialized models.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.