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

# Query Session Graph

Traverse a graph session object using a structured query AST.

## **POST** `/revisions/:id/data/query` (Command: `query_session_graph`)

### Request Body

| Parameter    | Type   | Required | Description                                         |
| :----------- | :----- | :------- | :-------------------------------------------------- |
| `engine`     | string | Yes      | Must be `workflow_blobhub`.                         |
| `command`    | string | Yes      | Must be `query_session_graph`.                      |
| `session_id` | string | Yes      | The ID of the session that owns the graph envelope. |
| `alias`      | string | Yes      | Alias of the graph session object.                  |
| `query`      | object | Yes      | Traversal query AST. See structure below.           |

#### Query AST

The `query` object has two fields:

| Field   | Type            | Required | Description                                |
| :------ | :-------------- | :------- | :----------------------------------------- |
| `start` | array           | Yes      | Selects the initial working set.           |
| `steps` | array of arrays | No       | Ordered traversal steps. Defaults to `[]`. |

**`start`** — a list of one or two elements: `["V"]`, `["E"]`, `["V", "<id>"]`, or `["E", "<id>"]`.

* `"V"` — start from all vertices in the graph (no id) or a single vertex by id.
* `"E"` — start from all edges in the graph (no id) or a single edge by id.

**`steps`** — each step is a non-empty list where the first element is the step name and the
remaining elements are its arguments:

| Step name    | Arguments            | Description                                                                                          |
| :----------- | :------------------- | :--------------------------------------------------------------------------------------------------- |
| `out`        | `type?` (string)     | Follow outgoing edges; optionally filter by edge label.                                              |
| `in`         | `type?` (string)     | Follow incoming edges; optionally filter by edge label.                                              |
| `both`       | `type?` (string)     | Follow edges in both directions; optionally filter by edge label.                                    |
| `outE`       | `type?` (string)     | Move to outgoing edge elements (instead of neighbor vertices).                                       |
| `inE`        | `type?` (string)     | Move to incoming edge elements.                                                                      |
| `bothE`      | `type?` (string)     | Move to edge elements in both directions.                                                            |
| `inV`        | —                    | From edge elements, resolve the `to_id` vertex.                                                      |
| `outV`       | —                    | From edge elements, resolve the `from_id` vertex.                                                    |
| `hasLabel`   | `label` (string)     | Retain elements whose `labels` array contains the given label.                                       |
| `has`        | `key`, `op`, `value` | Retain elements where `props[key] <op> value`. `op` is one of `eq`, `neq`, `lt`, `lte`, `gt`, `gte`. |
| `values`     | `key` (string)       | Extract `props[key]` for each element (terminal — result becomes a list of scalars).                 |
| `properties` | —                    | Extract the full `props` object for each element (terminal).                                         |
| `project`    | `keys` (string\[])   | Extract a subset of `props` keys for each element (terminal).                                        |
| `path`       | —                    | Return the traversal path (list of element\_ids) for each walker (terminal).                         |
| `limit`      | `n` (integer)        | Keep at most `n` elements from the current working set.                                              |
| `dedup`      | —                    | Remove duplicate elements (by `element_id`) from the working set.                                    |
| `count`      | —                    | Return the count of elements in the working set (terminal — result is an integer).                   |

Terminal steps (`values`, `properties`, `project`, `path`, `count`) convert the working set to a
non-element result. Only `limit`, `dedup`, and `count` are valid after a terminal step.

#### Hard Caps

The server enforces four hard caps on every query regardless of the AST:

| Cap            | Description                                          |
| :------------- | :--------------------------------------------------- |
| `max_depth`    | Maximum number of steps allowed in a single query.   |
| `max_fanout`   | Maximum elements expanded by a single adjacency hop. |
| `max_results`  | Maximum size of the working set / final result.      |
| `max_elements` | Maximum cumulative element fetches across all steps. |

Exceeding any cap returns `graph_traversal_limit_exceeded`.

### Response

| Parameter | Type                               | Description                                                                                                                                            |
| :-------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result`  | array of object, array, or integer | Traversal result. A list of elements (default), a list of scalars/dicts (after `values`/`properties`/`project`/`path`), or an integer (after `count`). |

### Errors

* `invalid_graph_envelope` — the alias does not exist or its `value.type` is not `"graph"`.
* `invalid_graph_query` — the query AST is malformed or contains unsupported step types.
* `graph_traversal_limit_exceeded` — the query hit a server-side traversal cap.

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "query_session_graph",
    "session_id": "sess_001",
    "alias": "task_graph",
    "query": {
      "start": ["V"],
      "steps": [
        ["hasLabel", "task"],
        ["has", "status", "eq", "open"],
        ["out", "depends_on"],
        ["limit", 10]
      ]
    }
  }
  ```

  ```json Response theme={null}
  {
    "result": [
      {
        "element_id": "task:1",
        "type": "vertex",
        "labels": ["task"],
        "props": { "title": "Research", "status": "in_progress" },
        "rev": 2,
        "created_at": "2026-06-06T10:00:00.000000+00:00",
        "updated_at": "2026-06-06T10:00:01.000000+00:00",
        "user_id": "usr_001"
      }
    ]
  }
  ```
</CodeGroup>

### See also

* [Graph session object](/blob-types/workflow/session-objects/graph/introduction) — envelope shape and element schema.
* [Apply Session Graph Mutations](/blob-types/workflow/operations/apply-session-graph-mutations) — write vertices and edges.
* [List Session Graph Elements](/blob-types/workflow/operations/list-session-graph-elements) — paginate all elements.
* [List Session Graph Neighbors](/blob-types/workflow/operations/list-session-graph-neighbors) — fetch neighbors of a set of vertices.
* [Get Session Graph Element](/blob-types/workflow/operations/get-session-graph-element) — fetch a single element.
* [Get Session Graph Elements](/blob-types/workflow/operations/get-session-graph-elements) — fetch multiple elements by id.