Graph Database (graph)

Category: data | Form: | Symbol: Gr

Store and traverse graph-structured data

Graph storage for nodes, edges, and traversals. Supports add-node, add-edge, traverse, and shortest-path operations. Backed by Apache AGE (PostgreSQL extension). Attach to action elements to inject the connection.

Guide

Store and traverse graph-structured data

What It Does

Graph is a data-storage element that holds a labeled property graph — nodes with types and JSON properties, plus directed edges with types and properties. It is a storage substrate, not compute: you put a graph in it and run node/edge mutations and traversal queries against it through operations.

The graph is stored in per-element PostgreSQL tables (graph_{slug}_nodes and graph_{slug}_edges) inside the circle’s schema. Tables are created lazily on the first operation, so there is nothing to provision up front. The element reads no spec fields at runtime — all behavior is driven by per-operation inputs declared below.

Other elements attach to a graph by reference. Action elements (python, javascript, …) reference a graph via uses, and the runtime injects the graph’s connection string as an environment variable so the action can read and write the graph directly. Graph is a data atom (a leaf) with no wired ports — it is always accessed through its operations.

Element Definition

Property	Value
Type	graph
Category	data
Form	atom
Symbol	Gr / icon share / #8B5CF6
Storage backend	age
Workbench	graph-workbench (workbench-graph-canvas)

Properties

Field	Type	Required	Constraint	Description
description	string	No	maxLength 512	Human-readable description of what domain this graph models

The executor reads no element-level spec fields; description exists for documentation and future configuration hooks. All operation behavior comes from per-op inputs.

Ports

Graph is a data atom and has no wired ports — it is accessed through its operations, not by wiring. Action elements reach it via uses, and the runtime injects the connection string as an environment variable.

Attaches

Modifier elements that can be attached to a graph:

Modifier	Purpose
auth-policy	Access control
rate-limit	Request rate limiting
variable	Variable injection

Capabilities

Capability	Description
property-graph	Labeled property-graph: nodes with types and JSON properties, directed edges with types
postgres-backed	Stored in per-element PostgreSQL tables using the circle’s schema (no external graph DB)
cypher-queries	Cypher-style pattern matching (label/type/variable-length paths) translated to SQL via the query op — a hand-rolled pattern extractor, not a full openCypher engine
bfs-traversal	Breadth-first traversal from a starting node with configurable depth and direction
shortest-path	BFS shortest-path between two nodes via the shortest-path op
bulk-import	Atomic batch insert of nodes and edges in a single transaction via bulk-import

Error Codes

Code	Class	Retryable	Description
GRAPH_NODE_NOT_FOUND	validation	No	Referenced node ID does not exist in the graph
GRAPH_EDGE_NODES_MISSING	validation	No	add-edge was called but source or target node does not exist
GRAPH_QUERY_FAILED	internal	Yes	Cypher-pattern or SQL query execution failed
GRAPH_TABLE_INIT_FAILED	internal	Yes	Failed to create graph node/edge tables on first operation
GRAPH_BULK_IMPORT_FAILED	internal	No	Bulk import transaction was rolled back

Operations

add-node

POST nodes · auth: write

Create a node with a label and optional properties (JSON object). Labels are used for type-based queries (e.g. Person, Product). An ID is auto-generated. Input: label (required), properties (object). Output: id, added.

add-edge

POST edges · auth: write

Create a directed edge between two existing nodes. The edge has a type (relationship type, e.g. KNOWS, OWNS) and optional properties. Input: source, target, type (all required), properties (object). Output: id, added.

query

POST query · auth: read

Execute a Cypher query against the graph. Returns nodes and edges matching the query pattern; use for complex traversals and pattern matching. Input: query (required), params (object). Output: results (array).

traverse

POST traverse · auth: read

Perform a breadth-first or depth-first traversal from a starting node, returning all reachable nodes within the depth limit. Input: start (required), direction (outgoing | incoming | both, default outgoing), max_depth (integer, default 3), edge_label (filter by edge label). Output: nodes (array), edges (array).

shortest-path

POST shortest-path · auth: read

Find the shortest path between two nodes using BFS. Returns the sequence of nodes and edges in the path. Input: source, target (both required), max_depth (integer, default 10). Output: path (array), length (integer), found (boolean).

delete-node

DELETE nodes/{node_id} · auth: write

Remove a node and all its connected edges from the graph. Output: deleted (boolean). (UI section: danger.)

bulk-import

POST bulk-import · auth: write

Batch-insert nodes and edges in a single all-or-nothing transaction — the natural ingest path for analytical workloads that produce large graph snapshots. Optionally truncates the graph before insert with replace: true. Input: nodes (array; each item requires id, optional type/label/properties), edges (array; each item requires source/target, optional id/type/properties), replace (boolean, default false). Output: nodes_added, edges_added, elapsed_ms (all integers).

Quick Start

Creating via API

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "graph",
  "slug": "social-graph",
  "name": "Social Graph",
  "spec": {
    "description": "People and the relationships between them"
  }
}

Adding nodes and an edge

POST /api/{circle}/{project}/social-graph/ops/add-node
Content-Type: application/json

{ "label": "Person", "properties": { "name": "Alice" } }

POST /api/{circle}/{project}/social-graph/ops/add-edge
Content-Type: application/json

{ "source": "<alice-id>", "target": "<bob-id>", "type": "KNOWS" }

Traversing and pathfinding

POST /api/{circle}/{project}/social-graph/ops/traverse
Content-Type: application/json

{ "start": "<alice-id>", "direction": "both", "max_depth": 2 }

POST /api/{circle}/{project}/social-graph/ops/shortest-path
Content-Type: application/json

{ "source": "<alice-id>", "target": "<carol-id>" }

Bulk ingest

POST /api/{circle}/{project}/social-graph/ops/bulk-import
Content-Type: application/json

{
  "replace": true,
  "nodes": [
    { "id": "a", "type": "Person", "properties": { "name": "Alice" } },
    { "id": "b", "type": "Person", "properties": { "name": "Bob" } }
  ],
  "edges": [
    { "source": "a", "target": "b", "type": "KNOWS" }
  ]
}

Common Mistakes

Adding an edge before its nodes exist. add-edge requires both source and target to reference existing nodes — otherwise it fails with GRAPH_EDGE_NODES_MISSING. Create both nodes with add-node first (or include them in the same bulk-import).

Traversing or referencing a node ID that was never created. Operations against a missing node ID fail with GRAPH_NODE_NOT_FOUND. Create the node with add-node before adding edges or traversing from it.

Bulk-import edges that point at unknown nodes. A bulk-import is all-or-nothing; if any edge references an ID that is not in the nodes list (or already in the graph), the whole transaction is rolled back with GRAPH_BULK_IMPORT_FAILED. Make sure every edge’s source/target ID is present.

Description longer than 512 characters. The description field is capped at 512 characters; a longer value is rejected on create/update.

Relationships

• Attaches to: auth-policy, rate-limit, variable

Capabilities

• property-graph: Labeled property-graph: nodes with types and JSON properties, directed edges with types
• postgres-backed: Stored in per-element PostgreSQL tables using the circle’s schema (no external graph DB)
• cypher-queries: Cypher-style pattern matching (label/type/variable-length paths) translated to SQL via the query op — a hand-rolled pattern extractor, not a full openCypher engine
• bfs-traversal: Breadth-first traversal from a starting node with configurable depth and direction
• shortest-path: BFS shortest-path between two nodes via the shortest-path op
• bulk-import: Atomic batch insert of nodes and edges in a single transaction via bulk-import

Properties

Property	Type	Default	Description
description	string	—	Human-readable description of what domain this graph models

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

add-edge

Post /ops/edges | Auth: Write

Create an edge between two nodes

Creates a directed edge between two existing nodes. The edge has a label (relationship type) and optional properties.

add-node

Post /ops/nodes | Auth: Write

Create a node with a label and properties

Creates a node with a label and optional properties (JSON object). Labels are used for type-based queries (e.g., “Person”, “Product”). An ID is auto-generated. Backed by Apache AGE (PostgreSQL graph extension).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

bulk-import

Post /ops/bulk-import | Auth: Write

Batch-insert nodes and edges in a single transaction

Inserts many nodes and edges in a single all-or-nothing transaction. Optionally truncates the graph before insert (replace=true). Returns counts and elapsed_ms. The natural ingest path for analytical workloads that produce large graph snapshots.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

delete-node

Delete /ops/nodes/{node_id} | Auth: Write

Delete a node and its edges

Removes a node and all its connected edges from the graph.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

query

Post /ops/query | Auth: Read

Execute a Cypher query

Runs an openCypher query against the graph. Returns nodes and edges matching the query pattern. Use for complex graph traversals and pattern matching.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

shortest-path

Post /ops/shortest-path | Auth: Read

Find the shortest path between two nodes

Finds the shortest path between two nodes using BFS. Returns the sequence of nodes and edges in the path.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_fixtures

Post /ops/source/fixtures | Auth: Write

Dry-run or apply approved Source seed fixtures

Scans .triform/fixtures/ manifests from the addressed data element Source repo. Defaults to dry_run=true and never imports live runtime data. Apply requires dry_run=false plus confirm=true and dispatches approved records through existing generated element ops.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

traverse

Post /ops/traverse | Auth: Read

Traverse the graph from a starting node

Performs a breadth-first or depth-first traversal from a starting node. Returns all reachable nodes within the specified depth limit.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
GRAPH_NODE_NOT_FOUND	validation	no	Referenced node ID does not exist in the graph
GRAPH_EDGE_NODES_MISSING	validation	no	add-edge was called but source or target node does not exist
GRAPH_QUERY_FAILED	internal	yes	Cypher-pattern or SQL query execution failed
GRAPH_TABLE_INIT_FAILED	internal	yes	Failed to create graph node/edge tables on first operation
GRAPH_BULK_IMPORT_FAILED	internal	no	Bulk import transaction was rolled back