The Traverse Edge stage follows object edges — typed, directed, customer-owned relationships stored on a document — to fetch the documents they point to. Starting from the documents in the pipeline, it reads each document’s root-level edges, filters by edge type and direction, and returns the linked documents (carrying the edge’s attributes with each result).
Stage Category: APPLY (relationship traversal)Transformation: N documents → M linked documents (optionally including the originating documents)
When to Use
| Use Case | Description |
|---|
| Footage ↔ ad linkage | From an ad, fetch every footage clip it uses (with clip order + start-ticks); from footage, find the ads that use it |
| Bill-of-materials / composition | Follow “part-of” relationships from an assembly to its components |
| Reference expansion | Pull the documents a result explicitly links to, without a similarity search |
| Graph hops | Walk saved relationships between entities you’ve modeled as edges |
When NOT to Use
| Scenario | Recommended Alternative |
|---|
| Similarity / semantic matching | feature_search |
| Joining by a shared field value | document_enrich |
| Comparing content across collections | cross_compare |
| Filtering on an attribute | attribute_filter |
How it works
- For each document entering the stage, the stage reads its root-level
edges list.
- Edges are kept when their
type matches edge_type and their direction matches the configured direction.
- Each kept edge’s
target_object_id is resolved to the linked document(s); with target_collection_id set, only documents from that collection are returned.
- Matched documents are returned with the originating edge’s
attributes attached (e.g. clip_order, start_ticks_in/start_ticks_out), so downstream stages can use them.
Because edges are stored reciprocally (an edge and its inverse can be written on both endpoints), you can traverse the same relationship from either side by choosing the matching edge_type and direction.
Parameters
| Parameter | Type | Default | Description |
|---|
edge_type | string | string[] | Required | Edge type(s) to follow, e.g. "uses_footage" or ["uses_footage", "used_in_ad"] |
direction | string | any | Which edge directions to follow: out, in, or any |
target_collection_id | string | null | Only return traversed documents from this collection (else all collections) |
include_source | boolean | false | Also keep the originating documents in the output |
max_per_source | integer | 50 | Max edges to follow per source document (guards fan-out) |
limit | integer | 200 | Max total traversed documents to fetch across all sources |
Example
Starting from an ad document, fetch every piece of footage it uses:
Each returned footage document carries the edge attributes from the ad that referenced it — clip_order, start_ticks_in, and start_ticks_out — so you know exactly where in the footage each clip was taken.
- Objects — how edges are stored on objects and flow to documents
- Iconik integration — how footage↔ad edges are captured at ingestion
- Cross Compare — match content across collections by similarity instead of saved edges
