Traverse query #

A bounded graph traversal over a relation-typed edge field: starting from seed documents, walk the edges up to max_depth hops and emit every reached node as a hit.

Scores encode distance — 1.0 / (1.0 + depth) — so seeds outrank 1-hop neighbors, which outrank 2-hop neighbors, and the standard top-K collector orders the results.

Examples #

POST /my-collection/_search
{
  "query": {
    "traverse": {
      "field": "related_to",
      "seed": {
        "query": { "term": { "field": "topic", "value": "search-engines" } }
      },
      "max_depth": 2,
      "direction": "outgoing"
    }
  }
}

Seeds by document _key (the string ids you index with):

POST /my-collection/_search
{
  "query": {
    "traverse": {
      "field": "related_to",
      "seed": { "keys": ["A01", "A05"] },
      "max_depth": 1
    }
  }
}

Shard placement #

Edge endpoints resolve against the key map of the shard that stores the edge document. Endpoints living on a different shard cannot be resolved there, and the edge is dropped with a warning — so keep a graph collection (or at least its edge documents and the nodes they reference) on a single shard:

{
  "settings": {
    "rolling": {
      "partitions_sharding_strategy": { "hash": { "number_of_shards": 1 } }
    }
  },
  "schema": { "properties": { "related_to": { "type": "relation" } } }
}

Parameters for traverse #

• field
  (Required, string) Edge field to traverse; must be declared in the schema with the relation type.
• seed
  (Required) Seed selector, one of:
  • query — a sub-Query resolved before the traversal dispatches.
  • keys — document _keys; resolved through the store’s key map, keys that do not exist are dropped.
  • ids — pre-resolved internal _ids (u32).
• max_depth
  (Required, integer) Maximum hop count. Seeds are at depth 0, so max_depth: 0 returns just the seeds.
• direction
  (Optional, string) Traversal direction along the edges: outgoing, incoming or both (the default).