Cratis Screenplay graph projections: project events onto a property graph
A graph projection builds a graph from events the way a projection builds a read model. Write => graph <Name> after the projection name, then describe each node label and edge type the events produce.
concept PersonId : Uuidconcept GroupId : Uuidconcept PersonName : String
module Organization feature Chart slice StateView OrganizationChart event PersonRegistered name PersonName
event PersonRemoved
event GroupCreated name String
event MemberAdded groupId GroupId
event MemberRemoved groupId GroupId
graph Organization node Person personId PersonId key name PersonName node Group groupId GroupId key name String edge MEMBER_OF source Person target Group since DateTime
projection OrganizationChart => graph Organization node Person from PersonRegistered key $eventSourceId name = name remove with PersonRemoved key $eventSourceId detach node Group from GroupCreated key $eventSourceId name = name edge MEMBER_OF from MemberAdded source $eventSourceId target groupId since = $eventContext.occurred remove with MemberRemoved source $eventSourceId target groupIdA graph projection is declared in a slice, next to the graph it builds. It holds node and edge blocks and nothing else; a standalone projection document cannot declare one (PLAY0877).
Syntax
Section titled “Syntax”projection <Name> => graph <Graph> [description "<text>"] node <Label> from <Event> [foreach <collection>] key <expression> <mapping> every <mapping> remove with <Event> [foreach <collection>] key <expression> [detach] edge <TYPE> from <Event> [foreach <collection>] source <expression> target <expression> [identified by <expression>] <mapping> remove with <Event> [foreach <collection>] source <expression> target <expression> [identified by <expression>]Node blocks
Section titled “Node blocks”node <Label> names a label the graph declares (PLAY0867). Inside it:
from <Event> key <expression>creates the node the expression names, or updates it when it exists, and applies the mappings under it. The expression is any projection expression: an event property,$eventSourceId, a template or an$eventContextmember.everyapplies its mappings whenever anyfromof the block handles an event, so properties shared by every event are written once.remove with <Event> key <expression>deletes the node. Adddetachto delete the edges attached to the node with it. A node removal withoutdetachwhile the graph declares edges that attach to the label is a warning (PLAY0870): the edges would be left dangling.
Edge blocks
Section titled “Edge blocks”edge <TYPE> names an edge type the graph declares. Inside it:
from <Event> source <expression> target <expression>creates the edge between the two nodes and applies the mappings. If either endpoint node does not exist it is created bare, with only its key.remove with <Event> source <expression> target <expression>deletes that edge.detachhas no meaning on an edge and is refused (PLAY0869).- When the edge declares
identified by, every handler writesidentified by <expression>aftertarget, and the edge is identified by that value as well (PLAY0871,PLAY0873).
Mappings
Section titled “Mappings”A mapping inside from or every is the property mapping of a read-model projection: property = expression, $eventContext.<member>, and the counters increment, decrement, count, add ... by and subtract ... by. They set or change node and edge properties. A property the node or edge does not declare is PLAY0868. As with a read model, properties an event shares with the node or edge by name are mapped automatically, so name = name above can be left out.
One element per item of a collection
Section titled “One element per item of a collection”An event that carries a list can draw one node or edge per item. Write foreach <collection> after the event name; the handler then runs once per item, the item’s properties are written <collection>.<property>, and every other expression is the event’s:
type ModelSlot slot String series Uuid
module Scoring feature Models slice StateView ModelScores event ModelDefined slots ModelSlot[]
event ModelRetired slots ModelSlot[]
graph Scoring node Model modelId Uuid key node Series seriesId Uuid key edge SCORES source Model target Series identified by slot slot String
projection ModelScores => graph Scoring edge SCORES from ModelDefined foreach slots source $eventSourceId target slots.series identified by slots.slot slot = slots.slot remove with ModelRetired foreach slots source $eventSourceId target slots.series identified by slots.slotThe collection is a property of the event that is a list of a composite type (PLAY0886 otherwise), and iteration goes one level deep: foreach slots.parts is refused. An absent or empty list does nothing. A model that uses foreach selects ESM version 41; see decision 0140. Chronicle runs the handler once per item (Chronicle 19.134 and later).
What a graph projection cannot say
Section titled “What a graph projection cannot say”The read-model constructs children, nested, join, all, clear with, variant, a projection-level key or sequence, and automap blocks have no meaning for a graph and are refused (PLAY0872). remove via join is read as a malformed graph removal and refused with PLAY0873. A malformed block, or a handler without its key (node) or source and target (edge), is PLAY0873. A node or edge built twice by one projection is PLAY0874. A projection for a graph that is not declared is PLAY0866.
Executable model
Section titled “Executable model”Graphs and graph projections are part of the executable semantic model from ESM version 38. A projection yields five idempotent operations on the graph; every sink, whatever the engine, implements the same five:
| Operation | Produced by |
|---|---|
UpsertNode |
a node from |
SetProperties |
the mappings of a node or edge from and every |
DeleteNode (with detach or without) |
a node remove with |
UpsertEdge |
an edge from |
DeleteEdge |
an edge remove with |
A node is identified by its label and key; an edge by its type, its source and target keys, and the identified by value when the edge declares one. An edge operation ensures its two endpoint nodes exist. A projection owns the edges and the node properties it declares and never deletes a node it did not declare.
The reference executor keeps an in-memory graph and applies these operations, which is what given graph and then graph specifications run against.
What the tools do not follow yet
Section titled “What the tools do not follow yet”The event model board, dependency and lineage queries, find-references and rename follow read-model projections only. A graph projection is compiled, printed, bound and executed like any other construct, but those tools do not draw it or rewrite its event references; renaming an event leaves a graph projection that the compiler then reports as unknown. Graph queries, flat or collecting, are the same: renaming a read model, a composite type or one of their properties does not rewrite the return lines and collect rows that name them, and the compiler then reports them (PLAY0881, PLAY1145).
See also graph declarations.
Reading a graph
Section titled “Reading a graph”A query that ends in graph <Graph> follows a path over the graph’s declared nodes and edges and returns an ordinary read model (decision 0139, ESM v40):
concept PersonId : Uuidconcept GroupId : Uuidconcept Name : String
module Organization feature Chart slice StateView OrganizationChart graph Organization node Person personId PersonId key name Name node Group groupId GroupId key title Name edge MEMBER_OF source Person target Group since DateTime optional
readmodel Membership personId PersonId key person Name since DateTime optional
query MembersOf => Membership[] graph Organization filter groupId GroupId match person:Person -link:MEMBER_OF-> group:Group where group.groupId = $groupId return personId = person.personId person = person.name since = link.sincematchis a path ofalias:Label,-alias:TYPE->(outgoing) and<-alias:TYPE-(incoming) steps; an alias is needed only wherewhereorreturnnames it.optional matchfollows a path that may be absent, so what it returns must go to optional read-model properties (PLAY0883).wherejoins equality tests withand; each compares a node or edge property with a$argumentor a literal.returnassigns every required read-model property from a node or edge property of the pattern.- Not in this version (
PLAY0885): variable-length paths,or, ranges, functions and aggregates. There is no engine-native query text. returncan also collect nested rows along an edge from the root, with<property> = collect <root> -TYPE-> <alias>:<Label>.- A specification asserts it with
then query <Name>aftergiven graph, or after events a projection turns into nodes and edges.given clock "<instant>"sets$eventContext.occurredfor those events; without it the reference runner uses a fixed instant.
Collect nested rows
Section titled “Collect nested rows”A graph query can return rows that hold other rows: a person with the groups they belong to, a group with its members. Inside return, <property> = collect <root> -[alias:]TYPE-> [alias:]Label assigns a read-model property the rows reached along one edge from the query’s root, and the lines under it fill each row from the reached node or the edge that was followed (decision 0163, ESM v54):
concept PersonId : Uuidconcept GroupId : Uuidconcept Name : String
type GroupMembership id GroupId name Name since DateTime optional
type GroupSummary id GroupId name Name
module Organization feature Chart slice StateView OrganizationViews graph Organization node Person personId PersonId key name Name node Group groupId GroupId key name Name edge MEMBER_OF source Person target Group since DateTime optional edge PART_OF source Group target Group
readmodel PersonWithGroups id PersonId key name Name groups GroupMembership[]
readmodel GroupWithParent id GroupId key name Name parent GroupSummary optional
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.since
query GroupsWithParent => GroupWithParent[] graph Organization match group:Group return id = group.groupId name = group.name parent = collect group -PART_OF-> parent:Group id = parent.groupId name = parent.name- The root. A query that collects reads like a view: one
match <alias>:<Label>of its root node alone, no hops and nooptional match. Its scalar returns come from the root. Every row of the result is one root node, distinct by key and ordered by the key (PLAY1147otherwise). - The edge. A collect follows one declared edge from the root, outgoing (
-TYPE->) or incoming (<-TYPE-), to the node it leads to. The arrow gives the direction, so an edge whose source and target are the same label (PART_OFabove) is never ambiguous. Name the edge (-membership:MEMBER_OF->) when a row reads one of its properties. - The rows. The collected property is a list of a composite type (
GroupMembership[]) or an optional composite type (GroupSummary optional). The lines under the collect assign the type’s properties, each from the reached node or the followed edge, and every required property of the type is assigned (PLAY1145). A list holds one row per edge reached, ordered by the reached node’s key and then by the edge’sidentified byvalue, so two roles in the same group are two rows; with nothing reached it is empty. An optional row is the first of those, or null. - Conditions select roots. A
wherecondition on a collected node keeps the roots with at least one reached node that satisfies every condition on that alias. It never narrows what is collected:PeopleInGroupreturns everyone in the group, each with all of their groups. A condition on a collected edge isPLAY1147. - Absent properties. A node created only by an edge (see the graph is ensured by its edges) has none of its other properties yet; a row reads them as null.
- One level. A collect inside a collect is
PLAY1146; follow the edge from the root in a collect of its own. A malformed collect isPLAY1144.
A specification asserts collected rows with structured values under then query, one item per row and none for an empty list:
concept PersonId : Uuidconcept GroupId : Uuidconcept Name : String
type GroupMembership id GroupId name Name
module Organization feature Chart slice StateView OrganizationViews graph Organization node Person personId PersonId key name Name node Group groupId GroupId key name Name edge MEMBER_OF source Person target Group
readmodel PersonWithGroups id PersonId key name Name groups GroupMembership[]
query PeopleWithGroups => PersonWithGroups[] graph Organization match person:Person return id = person.personId name = person.name groups = collect person -MEMBER_OF-> group:Group id = group.groupId name = group.name
specification SeeingEveryoneWithTheirGroups given graph Organization has node Person "6fa459ea-ee8a-4ca4-894e-db77e160355e" name = "Ada" has node Person "3fa85f64-5717-4562-b3fc-2c963f66afa6" name = "Linus" has node Group "0f8fad5b-d9cb-469f-a165-70867728950e" name = "Engineering" has edge MEMBER_OF from "6fa459ea-ee8a-4ca4-894e-db77e160355e" to "0f8fad5b-d9cb-469f-a165-70867728950e" then query PeopleWithGroups result id = "6fa459ea-ee8a-4ca4-894e-db77e160355e" name = "Ada" groups item id = "0f8fad5b-d9cb-469f-a165-70867728950e" name = "Engineering" result id = "3fa85f64-5717-4562-b3fc-2c963f66afa6" name = "Linus" groups noneThe executable model carries each collect on its graph query as collects: the read-model property, the root alias, the followed hop (edge type, outgoing, the reached label), the cardinality (many or one), the row’s composite type and its members, each of kind property (a property of the reached node) or edgeProperty (a property of the followed edge) with its source. A query that collects selects ESM v54; a query that does not keeps its version and bytes. A sink answers it with the same rows the reference runner gives, as for any graph query. The Organization sample reads its graph this way; see the Organization sample.