View Indexes

After you create indexes, use index inspection APIs to see what exists, whether each index is ready, which fields are available, and what records were indexed.

In V2, use get_index() plus index.records() instead of legacy get_scene_index(). Keep using get_scene_index() only with legacy scene indexes.

List indexes

Use list_indexes() to see the indexes available on a video.

indexes = video.list_indexes()

for index in indexes:
    print(index.name, index.status, index.use_for)

Example response:

[
  {
    "index_id": "idx_scene_123",
    "name": "scene",
    "status": "ready",
    "use_for": ["semantic", "query", "aggregate"],
    "source": {
      "understanding_id": "und_123",
      "artifact": "scene",
      "analyzer": {"name": "scene", "type": "vlm"}
    },
    "record_count": 128
  },
  {
    "index_id": "idx_objects_456",
    "name": "objects",
    "status": "ready",
    "use_for": ["query", "aggregate"],
    "source": {
      "understanding_id": "und_123",
      "artifact": "objects",
      "analyzer": {"name": "objects", "type": "object_detection"}
    },
    "record_count": 128
  }
]

You can filter by capability when you only want indexes that support a retrieval mode:

semantic_indexes = video.list_indexes(use_for="semantic")
query_indexes = video.list_indexes(use_for="query")
aggregate_indexes = video.list_indexes(use_for="aggregate")

Get one index

Use get_index() to inspect one index manifest.

index = video.get_index(name="scene")

print(index.status)
print(index.use_for)
print(index.fields)

You can also fetch by index ID:

index = video.get_index(index_id="idx_scene_123")

get_index() returns metadata and schema. It does not return every indexed record by default.

{
  "index_id": "idx_scene_123",
  "name": "scene",
  "status": "ready",
  "use_for": ["semantic", "query", "aggregate"],
  "record_count": 128,
  "source": {
    "understanding_id": "und_123",
    "artifact": "scene",
    "analyzer": {"name": "scene", "type": "vlm"}
  },
  "fields": {
    "semantic": ["scene_description", "activity", "setting"],
    "filter": ["activity", "setting"],
    "aggregate": ["activity", "setting"]
  }
}

Inspect field schema

Because V2 indexes can support query() and aggregate(), users need to know which fields are available for each capability.

index = video.get_index(name="scene")

for field, schema in index.field_schema.items():
    print(field, schema.type, schema.groups)

Example schema:

{
  "scene_description": {
    "type": "text",
    "groups": ["semantic"]
  },
  "activity": {
    "type": "string",
    "groups": ["semantic", "filter", "aggregate"],
    "operators": ["==", "!=", "contains", "in", "exists"]
  },
  "setting": {
    "type": "string",
    "groups": ["semantic", "filter", "aggregate"],
    "operators": ["==", "!=", "contains", "in", "exists"]
  }
}

Use this schema to decide which retrieval API to call:

Field group	Retrieval API
`semantic`	`video.semantic_search()` / `collection.semantic_search()`; also used by high-level `search()`
`filter`	`video.query()` / `collection.query()`; optional filters in `search()` and `semantic_search()`
`aggregate`	`video.aggregate()` / `collection.aggregate()`
`sort`	result ordering in `query()` / `search()`

Preview indexed records

Use record preview when you want to inspect what was indexed.

page = index.records(limit=20)

for record in page.records:
    print(record.start, record.end, record.data)

Example record:

{
  "video_id": "m-123",
  "understanding_id": "und-123",
  "scene_id": "scene-000002",
  "start": 3.42,
  "end": 7.1,
  "data": {
    "scene_description": "A person walks through a retail aisle while holding a phone.",
    "activity": "walking through store",
    "setting": "retail aisle",
    "frames": [
      {"timestamp": 4.8, "asset": {"type": "s3_object", "key": "..."}}
    ]
  }
}

Records are paginated:

page = index.records(limit=50)
next_page = index.records(limit=50, cursor=page.next_cursor)

index.records() is for inspection and debugging. For retrieval, filtering, ranking, and analytics, use search(), semantic_search(), query(), and aggregate().

Search APIs remain separate from index inspection

get_index() tells you what is possible. It does not duplicate retrieval APIs. For direct semantic search:

results = video.semantic_search(
    query="person holding a phone",
    index_names=["scene"],
)

For structured filtering on the scene index:

results = video.query(
    index_name="scene",
    filter={"activity": "walking through store"},
)

For object filters, query the objects index:

results = video.query(
    index_name="objects",
    filter={"object_labels": {"contains": "phone"}},
)

For counts and facets, use the index that owns the field:

response = collection.aggregate(
    index_name="brands",
    group_by="brand_names",
)
counts = response["results"]

Delete an index

Delete by id from the video, or call delete() on an Index object you already hold:

video.delete_index(index_id="idx_scene_123")

# or, given an Index object
index = video.get_index(name="scene")
index.delete()

Deleting an index removes the retrieval structures for that index. It does not delete the original video or stored understanding artifacts.

Start Here

Core Concepts

Ingest

Understand

Act

Automate

Open Source Frameworks

List indexes

Get one index

Inspect field schema

Preview indexed records

Search APIs remain separate from index inspection

Delete an index

Next steps

Search APIs

Index Fields

​List indexes

​Get one index

​Inspect field schema

​Preview indexed records

​Search APIs remain separate from index inspection

​Delete an index

​Next steps

Search APIs

Index Fields

List indexes

Get one index

Inspect field schema

Preview indexed records

Search APIs remain separate from index inspection

Delete an index

Next steps