Graph rendering
A Screenplay graph declares a property graph, and a projection ... => graph builds it from events. Stage renders both for the ESM v38 pair as the model-bound graph types of Chronicle’s graph projection API, and connects the generated host to Neo4j. This page describes what is rendered, what is refused and why, and the one piece that waits for a Chronicle release.
What is rendered
Section titled “What is rendered”For the Organization sample, an application plan adds these files under Graphs/:
| Modeled construct | Generated |
|---|---|
node Person |
Graphs/Organization/Person.cs: a record named after the label, marked [Graph("Organization")], [Node] and [NoAutoMap] |
The key property of a node |
The [Key] parameter of the record. When the key is a concept that is an event source identity, the parameter is the value it holds (for example Guid), because Chronicle’s analyzer refuses [Key] on an event source identity while the graph reader requires it |
from E key <value> on a node |
[FromEvent<E>], with the event property name when the key is an event property and ConstantKey when it is a literal |
remove with E key <value> [detach] |
[RemovedWith<E>], with Detach = true for detach |
edge MEMBER_OF source Person target Group |
Graphs/Organization/MemberOf.cs: a record marked [Edge("MEMBER_OF")] whose SourceKey is [Source<Person>] and TargetKey is [Target<Group>] |
from E source <value> target <value> on an edge |
[EdgeFrom<E>(sourceKey: ..., targetKey: ...)] |
remove with E source ... target ... on an edge |
[EdgeRemovedWith<E>(sourceKey: ..., targetKey: ...)] |
identified by assignmentId |
The identifying property is the edge’s [Key], and every handler passes identity: |
set, add, subtract, increment, decrement mappings |
[SetFrom<E>], [SetFromContext<E>], [SetValue<E>], [AddFrom<E>], [SubtractFrom<E>], [Increment<E>] and [Decrement<E>] on the property |
then graph |
Graphs/Specifications/when_<name>_is_graphed.cs: a specification that appends the events to a GraphScenario, reads each node and edge back and asserts it |
The attributes are Chronicle’s own, so the engine behaves as it does for a hand-written graph. A node’s key and an edge’s identity are said once by the handler and are not mapped a second time. The fluent IGraphProjection is never needed: every construct is either expressible with attributes or refused.
A StateView slice that only hosts a graph has no read model, so it renders nothing of its own; the graph renders with the application.
Host and configuration
Section titled “Host and configuration”When the model declares a graph, the application scaffold also connects to Neo4j:
Program.cscallsWithNeo4j()on the Arc builder, so a query can inject Arc’s tenant-awareIGraphSession.- The project references
Cratis.Arc.Neo4j, pinned centrally at the Arc release Stage pins. appsettings.jsongets aCratis:Neo4jsection: the server, the event store (the application name, which is the event store Chronicle’s Neo4j sink writes), the user name andPasswordSecret: NEO4J_PASSWORD. The password itself is never written.docker-compose.ymlgets a development Neo4j server and configures Chronicle’s Neo4j sink. Both read the password from theNEO4J_PASSWORDenvironment variable of the person running Compose, and Compose refuses to start without it.- The README gets a Graphs section.
The development setup uses DatabaseMode: Single because Neo4j Community Edition has one user database. That is for development only; production uses the per-namespace default against a server that supports it.
What is refused
Section titled “What is refused”A graph construct that cannot be expressed is refused with a named diagnostic. It is never dropped.
| Code | Meaning |
|---|---|
STAGE-ESM-063 |
The model declares a graph, graph projection or graph specification, and the pinned Chronicle client does not carry the graph API yet. The whole graph is refused. |
STAGE-ESM-062 |
A graph construct Chronicle’s model-bound API cannot express: a node label that is not a PascalCase identifier (the label is the record’s name), two elements that render to one record, an edge identified by a property it does not declare, a mapping with a factor (add x by a * b), a clear mapping, a literal that is not a text, boolean or whole-number constant, a key read from something other than an event property, the event source or a literal, an event handled twice by one element, or an element built by two projections. |
STAGE-ESM-064 |
A graph specification the generated GraphScenario cannot express. A specification that seeds a graph with given graph is omitted with this code as a degradation warning (STAGE-DEGRADE-002), because the scenario builds a graph only from appended events; a Strict plan fails acceptance on it. Other malformed graph specifications are errors. |
STAGE-ESM-065 |
The live runtime (Play) registers each graph and its projection with the kernel it runs against, and the kernel’s graph sink projects them (Neo4j by default, Stage__Graph__SinkType=InMemoryGraph for a kernel with no Neo4j). It does not read a graph back, and reports that as a non-blocking note on admission; graph specifications are decided by Screenplay’s reference graph runner. |
STAGE-ESM-066 |
A scoped plan leaves out the graphs of the application. Graphs render with the application scope. |
STAGE-ESM-068 |
The model declares a query that reads a graph (query ... graph <Graph>, ESM v40), or one that collects nested rows (ESM v54). The sandbox runs both, as described in Graph queries in the sandbox; the renderer does not render a graph query yet, so rendering refuses the model rather than leave the query without an endpoint. The message says when the query collects. |
STAGE-ESM-067 |
The legacy syntax path (the structural engines that translate a parsed document rather than the executable semantic model) met a graph, graph projection, graph specification step or the collect of a graph query. It would drop it, so it refuses it. |
STAGE-ESM-016 |
ESM v38 models can also carry the v37 clock and time-zone constructs and v37.1 property order, which Stage has not audited. They are refused like the members of an unaudited pair. |
Graph queries in the sandbox
Section titled “Graph queries in the sandbox”The sandbox serves each graph query as an ordinary query of the slice that declares its read model, through Arc’s tenant-aware graph session. It is served only when the host is told where Neo4j is (Cratis:Neo4j:Server); without it the query has no endpoint and the rest of the model runs.
A flat graph query (ESM v40) is lowered to one parameterized Cypher query from its match, where and return, and returns one row per path.
A query that collects nested rows (ESM v54) has the shape of a Chronicle graph view, and Stage reads it as one:
query PeopleInGroup => PersonWithGroups[] graph Organization filter groupId GroupId match person:Person where group.groupId = $groupId return id = person.personId name = person.name groups = collect person -membership:MEMBER_OF-> group:Group id = group.groupId name = group.name since = membership.sinceThe root view is named after the read model and anchored at the label of the match; the returns from the root are its properties. Each collect is a relation of the view: it follows the edge type, outgoing or incoming as the arrow says, with the cardinality of the read-model property (a list is many, an optional row is one), to a nested view named after the row type and rooted at the reached label. A row line that reads the reached node is a property of the nested view, and one that reads the followed edge is an edge property. A where condition on the root becomes a property clause, and the conditions on one collected node become one related clause, so they select roots without narrowing what is collected.
Arc’s Cratis.Arc.Neo4j.Chronicle translates the view to one read-only Cypher query on the database of the current tenant and, in single-database mode, the current namespace. Every value is a parameter. Each root comes back as the read model with its collected rows nested: a list collect with nothing reached is an empty list, an optional one is null, and a property a bare node does not have reads as null. Roots come back ordered by key, and collected rows by the reached key and then the identity of an identified edge.
A condition whose argument the caller leaves out is left out of the query, as it is for a flat graph query. A model whose collecting query is not shaped like a view is refused by the Screenplay compiler before it reaches Stage. The translated query uses COLLECT subqueries, so the server must be Neo4j 5.6 or later.
Verifying graph specifications
Section titled “Verifying graph specifications”The specification executor runs given graph and then graph specifications with Screenplay’s reference graph runner, which applies the five graph operations (upsert node, set properties, delete node, upsert edge, delete edge) to an in-memory property graph. The results are reported with the slice kind Graph and are selected with the slice that owns them, or with any module, feature or application scope that contains it.
The Chronicle release gate
Section titled “The Chronicle release gate”ChronicleGraphSupport.FirstRelease in Source/Rendering.Cratis/Semantics/Graphs/ChronicleGraphSupport.cs is the first Chronicle release that carries the graph API, 19.129.0. The renderer admits a graph only when the Chronicle version Stage pins is at or past it; otherwise it refuses the whole graph with STAGE-ESM-063. Raising the Chronicle pins in Directory.Packages.props needs no change here, and the framework name catalog is regenerated with STAGE_WRITE_FRAMEWORK_NAME_CATALOG=1 dotnet test Source/Rendering.Cratis/Rendering.Cratis.csproj --filter "FullyQualifiedName~for_FrameworkNameCatalog".