eliasdb/ecal.md

EliasDB Event Condition Action Language

EliasDB supports a scripting language called Event Condition Action Language (ECAL) to enable rule based scripting functionality.

EliasDB specific events which can be handled:

The ECAL interpreter in EliasDB receives the following events:

EliasDB Graph Event | ECAL event kind | Event state contents | Description -|-|-|- graph.EventNodeCreated | db.node.created | part, trans, node | A node was created. graph.EventNodeUpdated | db.node.updated | part, trans, node, old_node | A node was updated. graph.EventNodeDeleted | db.node.deleted | part, trans, node | A node was deleted. graph.EventEdgeCreated | db.edge.created | part, trans, edge | An edge was created. graph.EventEdgeUpdated | db.edge.updated | part, trans, edge, old_edge | An edge was updated. graph.EventEdgeDeleted | db.edge.deleted | part, trans, edge | An edge was deleted. graph.EventNodeStore | db.node.store | part, trans, node | A node is about to be stored (always overwriting existing values). graph.EventNodeUpdate | db.node.update | part, trans, node | A node is about to be updated. Only thrown when graph.UpdateNode is called directly. graph.EventNodeDelete | db.node.delete | part, trans, key, kind | A node is about to be deleted. graph.EventEdgeStore | db.edge.store | part, trans, edge | An edge is about to be stored. graph.EventEdgeDelete | db.edge.delete | part, trans, key, kind | An edge is about to be deleted.

TODO: Explaination Add special function to signal that an event has been handled

Note: EliasDB will wait for the event cascade to be finished before performing the actual operation (e.g. inserting a node). If the event handling requires a time consuming operation then a new event cascade should be started using addEvent with a scope:

addEvent("request", "foo.bar.xxx", {
   "payload" : 123
}, {
   "": true  # This scope allows all events
})

EliasDB specific functions:

The ECAL interpreter in EliasDB supports the following EliasDB specific functions:

db.storeNode(partition, nodeMap, [transaction])

Inserts or updates a node in EliasDB.

Parameter | Description -|- partition | Partition of the node nodeMap | Node object as a map with at least a key and a kind attribute transaction | Optional a transaction to group a set of changes

Example:

db.storeNode("main", {
  "key" : "foo",
  "kind" : "bar",
  "data" : 123,
})

db.removeNode(partition, nodeKey, nodeKind, [transaction])

Removes a node in EliasDB.

Parameter | Description -|- partition | Partition of the node nodeKey | Key attribute of the node to remove nodeKind | Kind attribute of the node to remove transaction | Optional a transaction to group a set of changes

Example:

db.removeNode("main", "foo", "bar")

db.fetchNode(partition, nodeKey, nodeKind)

Fetches a node in EliasDB.

Parameter | Description -|- partition | Partition of the node nodeKey | Key attribute of the node to fetch nodeKind | Kind attribute of the node to fetch

Example:

db.fetchNode("main", "foo", "bar")

db.storeEdge(partition, edgeMap, [transaction])

Inserts or updates an edge in EliasDB.

Parameter | Description -|- partition | Partition of the edge edgeMap | Edge object as a map with at least the main attributes: key, kind, end1cascading, end1key, end1kind, end1role, end2cascading, end2key, end2kind, end2role transaction | Optional a transaction to group a set of changes

Example:

db.storeEdge("main", {
  "key":           "123",
  "kind":          "myedges",
  "end1cascading": true,
  "end1key":       "foo",
  "end1kind":      "bar",
  "end1role":      "role1",
  "end2cascading": false,
  "end2key":       "key2",
  "end2kind":      "kind2",
  "end2role":      "role2",
})

db.removeEdge(partition, edgeKey, edgeKind, [transaction])

Removes an edge in EliasDB.

Parameter | Description -|- partition | Partition of the edge edgeKey | Key attribute of the edge to remove edgeKind | Kind attribute of the edge to remove transaction | Optional a transaction to group a set of changes

Example:

db.removeEdge("main", "123", "myedges")

db.fetchEdge(partition, edgeKey, edgeKind)

Fetches an edge in EliasDB.

Parameter | Description -|- partition | Partition of the edge edgeKey | Key attribute of the edge to fetch edgeKind | Kind attribute of the edge to fetch

Example:

db.fetchEdge("main", "123", "myedges")

db.traverse(partition, nodeKey, nodeKind, traversalSpec)

Traverses an edge in EliasDB from a given node. Returns a list of nodes which were reached and a list of edges which were followed.

Parameter | Description -|- partition | Partition of the node nodeKey | Key attribute of the node to traverse from nodeKind | Kind attribute of the node to traverse from traversalSpec | Traversal spec

Example:

[nodes, edges] := db.traverse("main", "foo", "bar", "role1:myedges:role2:kind2")

db.newTrans()

Creates a new transaction for EliasDB.

Example:

trans := db.newTrans()

db.newRollingTrans(n)

Creates a new rolling transaction for EliasDB. A rolling transaction commits after n entries.

Parameter | Description -|- n | Rolling threshold (number of operations before rolling)

Example:

trans := db.newRollingTrans(5)

db.commit(transaction)

Commits an existing transaction for EliasDB.

Parameter | Description -|- transaction | Transaction to execute

Example:

db.commit(trans)

db.query(partition, query)

Run an EQL query.

Parameter | Description -|- partition | Partition to query query | Query to execute

Example:

db.commit("main", "get bar")

db.graphQL(partition, query, [variables], [operationName])

Run a GraphQL query.

Parameter | Description -|- partition | Partition to query query | Query to execute variables | Map of variables for the query operationName | Operation to execute (useful if the query defines more than a single operation)

Example:

db.graphQL("main", "query myquery($x: string) { bar(key:$x) { data }}", {
  "x": "foo",  
}, "myquery")

db.raiseGraphEventHandled()

When handling a graph event, notify the GraphManager of EliasDB that no further action is necessary.

Example:

sink mysink
  kindmatch [ "db.*.*" ],
{
  db.raiseGraphEventHandled()
}