GraphQL interface¶

The graphql feature gives a native, pure-Rust GraphQL surface (no async-graphql). The schema is introspected from the live graph — root fields are node labels, scalar fields are properties, and object fields are typed edges. Queries compile to label scans + BFS over the same GraphView the Cypher path uses, and produce byte-equal results; mutations map to native graph write methods.

Status snapshot: read queries and mutations (createNode/updateNode/deleteNode/addEdge/removeEdge) are supported, along with CDC subscriptions (EG-064), fragments / variables / directives (EG-KG.query.fragments-variables-directives), relay pagination (EG-KG.query.graphql-cursors), Apollo Federation v2 subgraph support (EG-295), and production hardening (APQ + depth/complexity limits, EG-KG.domains.graphql-enterprise-hardening). See the capability matrix.

Supported queries¶

{
  Agent(first: 10, region: "us") {
    id
    role
    supervises {        # an edge typed "supervises" → target nodes
      id
    }
  }
}

Root fields are node labels; unknown labels error GraphQL: no node type … (root fields must be node labels).
Arguments: first / limit (int) and property-equality filters.
Aliases (alias: field), nested selection sets, scalar property fields, and object/edge fields.
query { … }, query Name { … }, and bare { … } are all accepted.

Mutations¶

mutation {
  createNode(label: "Agent", props: {id: "AgentC", region: "us"}) { id }
  addEdge(src: "AgentC", tgt: "AgentD", type: "supervises") { ok }
}

createNode/updateNode/deleteNode/addEdge/removeEdge map to native eg-core mutations and bump the OCC version once per batch; returned objects are shaped by the same resolver the query path uses.

Subscriptions — CDC (EG-064)¶

A tokio::sync::broadcast change-stream fed by GraphCore mark_dirty backs live subscriptions over a WS/SSE carrier (EPISTEMIC_GRAPH_GRAPHQL_ADDR starts the SSE carrier — a text/event-stream frame per graph change). This replaces the earlier poll-only stub.

Fragments, variables, directives & pagination (EG-KG.query.fragments-variables-directives/066)¶

Fragments (EG-KG.query.fragments-variables-directives): named fragment-spreads and inline fragments (... on Type).
Variables (EG-KG.query.fragments-variables-directives): $var definitions/refs, resolved from the request variables.
Directives (EG-KG.query.fragments-variables-directives): @skip(if:) / @include(if:).
Relay pagination (EG-KG.query.graphql-cursors): first/after/before/cursor args with an edges/node/cursor/pageInfo envelope over a deterministic sort.

Apollo Federation subgraph (EG-295)¶

The engine is a federated subgraph in an Apollo supergraph: it serves _service { sdl } and _entities(representations: [_Any!]!) resolvers, and parses @key/@shareable/@external directives in the emitted SDL.

{ _service { sdl } }

Production hardening — APQ + limits (EG-KG.domains.graphql-enterprise-hardening)¶

For production the surface adds: automatic persisted queries (APQ — a sha256 hash registry so clients send hash-only requests), query depth + complexity/cost analysis with configurable limits (over-budget queries are rejected before execution), field/node count caps, and an introspection on/off toggle. These protect the federated subgraph.