> ## 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. # Introduction A `graph` session object is a mutable property graph of vertices and edges. The envelope marks the object as a graph and holds optional metadata about it; elements themselves live in a separate element store managed by dedicated commands. ## Envelope Upload a graph envelope with `upload_session_object`, setting `value.type` to `"graph"`: ```json theme={null} { "type": "graph", "graph": { "attributes": { "id": "uuid-for-tracking", "created_at": "2026-06-06T10:00:00.000000+00:00", "name": "Task dependency graph", "description": "..." }, "metadata": {} } } ``` The `graph` object inside `value` carries two optional sub-fields: | Field | Type | Description | | :----------- | :----- | :------------------------------------------------------------------ | | `attributes` | object | Optional named metadata: `id`, `created_at`, `name`, `description`. | | `metadata` | object | Optional arbitrary JSON. | The envelope is read back as-is via `download_session_object`. No elements are included in that response — elements are fetched exclusively through the graph commands. ## Element Model The graph stores two kinds of elements: **vertices** and **edges**. ### Vertex Fields | Field | Type | Description | | :----------- | :-------------- | :-------------------------------------------------------------------------------------- | | `element_id` | string | Graph-scoped unique id. May be client-supplied or server-generated. | | `type` | string | Always `"vertex"`. | | `labels` | array of string | Label set assigned at creation. Labels are immutable after `add_vertex`. | | `props` | object | Arbitrary key/value properties. Mutable via `set_vertex_props` / `remove_vertex_props`. | | `rev` | integer | Optimistic-concurrency revision counter. Increments on every mutation. | | `created_at` | string | ISO 8601 timestamp set at creation. | | `updated_at` | string | ISO 8601 timestamp of the last mutation. | | `user_id` | string | Id of the user who last mutated this element. | ### Edge Fields | Field | Type | Description | | :----------- | :------ | :---------------------------------------------------------------------------------- | | `element_id` | string | Graph-scoped unique id. May be client-supplied or server-generated. | | `type` | string | Always `"edge"`. | | `label` | string | Single edge label (type). Set at `add_edge` and immutable thereafter. | | `from_id` | string | `element_id` of the source vertex. | | `to_id` | string | `element_id` of the target vertex. | | `props` | object | Arbitrary key/value properties. Mutable via `set_edge_props` / `remove_edge_props`. | | `rev` | integer | Optimistic-concurrency revision counter. Increments on every mutation. | | `created_at` | string | ISO 8601 timestamp set at creation. | | `updated_at` | string | ISO 8601 timestamp of the last mutation. | | `user_id` | string | Id of the user who last mutated this element. | ## Mutations All writes go through `apply_session_graph_mutations`, which accepts an ordered list of operations applied atomically. A single call may contain at most 100 operations (subject to a server-enforced action budget). | `op` | Required fields | Description | | :-------------------- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------ | | `add_vertex` | `labels` (non-empty) | Create a new vertex. `labels` is required at creation and immutable afterward; `element_id` may be client-supplied. | | `add_edge` | `label`, `from_id`, `to_id` | Create a new directed edge between two existing vertices. | | `set_vertex_props` | `element_id`, `props` | Merge `props` into the existing vertex (shallow set; does not remove unmentioned keys). | | `set_edge_props` | `element_id`, `props` | Merge `props` into the existing edge. | | `remove_vertex_props` | `element_id`, `keys` | Remove the specified property keys from the vertex. | | `remove_edge_props` | `element_id`, `keys` | Remove the specified property keys from the edge. | | `delete_vertex` | `element_id` | Delete a vertex and all of its incident edges (cascade). | | `delete_edge` | `element_id` | Delete a single edge. | Optional field available on all mutation ops: | Field | Type | Description | | :------- | :------ | :------------------------------------------------------------------------------------------ | | `if_rev` | integer | If present, the server verifies the element's current `rev` matches before applying the op. | ## Optimistic Concurrency Each element carries a `rev` integer that increments on every successful mutation. To guard against lost updates in concurrent environments, pass `if_rev` with the last-known `rev` of the element. If the stored `rev` no longer matches, the entire batch is rejected with a `graph_mutation_conflict` (HTTP 409) error and nothing is written. ```json theme={null} { "op": "set_vertex_props", "element_id": "task:1", "if_rev": 3, "props": { "status": "done" } } ``` ## Operations | Operation | Description | | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- | | [Apply Session Graph Mutations](/blob-types/workflow/operations/apply-session-graph-mutations) | Atomically apply a batch of create/update/delete operations. | | [Query Session Graph](/blob-types/workflow/operations/query-session-graph) | Traverse the graph with a structured query AST. | | [List Session Graph Elements](/blob-types/workflow/operations/list-session-graph-elements) | Paginate all elements; supports `updated_since` for incremental syncs. | | [List Session Graph Neighbors](/blob-types/workflow/operations/list-session-graph-neighbors) | Fetch edges and neighbor vertices for a set of seed vertex ids. | | [Get Session Graph Element](/blob-types/workflow/operations/get-session-graph-element) | Fetch a single element by `element_id`. | | [Get Session Graph Elements](/blob-types/workflow/operations/get-session-graph-elements) | Batch-fetch multiple elements by `element_id`. | All commands require the `alias` of the graph envelope. If the envelope does not exist or its `value.type` is not `"graph"`, the server returns `invalid_graph_envelope`. ## Events After each `apply_session_graph_mutations` call the server emits a [`session_graph_changed`](/blob-types/workflow/workflows/session-events) event carrying the change delta: ```json theme={null} { "type": "session_graph_changed", "session_object": { "alias": "task_graph", "changes": [ { "op": "upsert", "element_id": "task:1", "type": "vertex", "rev": 4 }, { "op": "delete", "element_id": "e:7", "type": "edge" } ] } } ``` Each entry in `changes` describes one logical effect of the batch: | `op` | Meaning | | :------- | :---------------------------------------------------------------------------------------- | | `upsert` | The element was created or updated. Fetch its new state via `get_session_graph_elements`. | | `delete` | The element was deleted. Remove it from any local cache. | The recommended client sync pattern is: apply `delete` entries locally, then call `get_session_graph_elements` with the `element_id` values from `upsert` entries to fetch their updated state. For a full resync, use `list_session_graph_elements` with `updated_since`. ## See also * [Session Objects — Introduction](/blob-types/workflow/session-objects/introduction) — envelope mechanics and the full list of session object types. * [Session Events](/blob-types/workflow/workflows/session-events) — full event reference.