EliasDB Event Condition Action Language

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

ECAL was added for the following use-cases:

Providing a way to manipulate data in response to events
Enforce certain aspects of a database schema
Providing back-end logic for web applications using EliasDB

The source of EliasDB comes with a chat example containing a simple ECAL script which adds a timestamp to nodes and a game example which demonstrates a more complex application of ECAL.

ECAL related config values:

These ECAL related config options are available in eliasdb.config.json:

Configuration Option	Description
EnableECALScripts	Enable ECAL scripting.
ECALScriptFolder	Scripting folder for ECAL scripts.
ECALEntryScript	Entry script in the script folder.
ECALLogFile	File in which the logs should be written (use an empty string for stdout).
ECALLogLevel	Log level for the printed logs.
EnableECALDebugServer	Enable debugging and start the ECAL debug server. Note: Activating debugging will slow down the interpreter speed significantly!
ECALDebugServerHost	Host for the debug server.
ECALDebugServerPort	Port for the debug server.
ECALWorkerCount	Number of worker threads in the ECA engine's thread pool.

ECAL Debugging

If the debug server is enabled in the config file then it is possible to debug ECAL scripts with VSCode. The debugger supports break points and thread state inspection. It is also possible to restart and reload the scripts.

Using the -ecal-console parameter it is possible to open an interactive console into the server process. If used together with the debug server additional debug commands are available also there. Enter ? to see the build-in documentation.

EliasDB specific events which can be handled:

The ECAL interpreter in EliasDB receives the following events:

Web Request	ECAL event kind	Event state contents	Description
/db/api/	`db.web.api`	bodyJSON, bodyString, header, method, path, pathList, query	Any web request to /db/api/... These endpoints are public and never require authentication.
/db/ecal/	`db.web.ecal`	bodyJSON, bodyString, header, method, path, pathList, query	Any web request to /db/ecal/... These endpoints are considered internal and require authentication if access control is enabled.
/db/sock/	`db.web.sock`	bodyJSON, bodyString, commID, header, method, path, pathList, query	Any web request to /db/sock/... These endpoints are used to initiate websocket connections.
-	`db.web.sock.data`	commID, data, header, method, path, pathList, query	An existing websocket connection received some JSON object data. If the close attribute of the object is set to true then the websocket connection is closed.

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.
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.

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 parallel event cascade can be started using addEvent with a scope:

EliasDB can receive the following events from the ECAL interpreter:

ECAL event kind	Event state contents	Description
db.web.sock.msg	commID, payload, close	The payload is send to a client with an open websocket identified by the commID.

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.

Example:

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

`db.updateNode(partition, nodeMap, [transaction])`

Updates a node in EliasDB (only update the given values of the node).

Example:

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

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

Removes a node in EliasDB.

Example:

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

`db.fetchNode(partition, nodeKey, nodeKind)`

Fetches a node in EliasDB.

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.

Example:

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

`db.fetchEdge(partition, edgeKey, edgeKind)`

Fetches an edge in EliasDB.

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.

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.

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. This creates a special error object and should not be used inside a try block. When using a try block this can be used inside an except or otherwise block.

Example:

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

`db.raiseWebEventHandled()`

When handling a web event, notify the web API of EliasDB that the web request was handled. This creates a special error object and should not be used inside a try block. When using a try block this can be used inside an except or otherwise block.

Example:

sink mysink
  kindmatch [ "web.*.*" ],
{
  db.raiseWebEventHandled({
    "status" : 200,
    "headers" : {
      "Date": "today"
    },
    "body" : {
      "mydata" : [1,2,3]
    }
  })
}

ecal.md 10 KB История Исходник

EliasDB Event Condition Action Language

ECAL related config values:

ECAL Debugging

EliasDB specific events which can be handled:

EliasDB specific functions:

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

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

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

db.fetchNode(partition, nodeKey, nodeKind)

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

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

db.fetchEdge(partition, edgeKey, edgeKind)

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

db.newTrans()

db.newRollingTrans(n)

db.commit(transaction)

db.query(partition, query)

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

db.raiseGraphEventHandled()

db.raiseWebEventHandled()

ecal.md 10 KB

История Исходник

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

`db.updateNode(partition, nodeMap, [transaction])`

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

`db.fetchNode(partition, nodeKey, nodeKind)`

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

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

`db.fetchEdge(partition, edgeKey, edgeKind)`

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

`db.newTrans()`

`db.newRollingTrans(n)`

`db.commit(transaction)`

`db.query(partition, query)`

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

`db.raiseGraphEventHandled()`

`db.raiseWebEventHandled()`