Drasi Custom Functions

Drasi is not simply running graph queries across data, it is using the Cypher Query Language as a convenient way to express the data you want to observe for changes. Drasi provides the following functions that extend the base Cypher Query Language in order to meet its needs for detecting and reacting to change (or an absence of change).

Drasi METADATA Functions

drasi.changeDateTime()

The drasi.changeDateTime function returns the ZONED DATETIME of when the provided element was last changed.

Syntax

drasi.changeDateTime(element)

Arguments

The drasi.changeDateTime function accepts one argument:

Returns

The drasi.changeDateTime function returns a ZONED DATETIME.

Drasi DELTA Functions

drasi.previousValue()

The drasi.previousValue function returns the value of an expression within a query as it was before the current change.

Syntax

drasi.previousValue(expression, default)

Arguments

Returns

The drasi.previousValue function returns the value of the given expression as it was before the current change.

Example

For example, if we wanted to know when any Task changes from the pending state to the active state. This could be achieved with the following clause:

WHERE t.state = 'active' AND drasi.previousValue(t.state) = 'pending'

In this case:

• When the Task transitions from pending to active, this clause will evaluate to true
• When the Task transitions from cancelled to active, this clause will evaluate to false
• When the Task had already transitioned from pending to active but subsequently the tag field was changed but the state field remained as active, this clause will evaluate to false because the value of t.state was also active prior to the final change

drasi.previousDistinctValue()

The drasi.previousDistinctValue function returns the previous value of an expression within a query that was different from the current value of that expression.

Syntax

drasi.previousDistinctValue(expression, default)

Arguments

Returns

The drasi.previousDistinctValue function returns the previous value of an expression within a query that was different from the current value of that expression.

Example

For example, if we wanted to keep a result set of all the Tasks that are currently in the active state but which the immediately previous state was pending. This could be achieved with the following clause:

WHERE t.state = 'active' AND drasi.previousDistinctValue(t.state) = 'pending'

In this case:

• When the Task transitions from pending to active, this clause will evaluate to true
• When the Task transitions from cancelled to active, this clause will evaluate to false
• When the Task had already transitioned from pending to active but subsequently the tag field was changed but the state field remained as active, this clause will evaluate to true because the previously distinct value of t.state was pending even though it was not altered by the final change

Drasi LIST Functions

Drasi LIST functions simplify some LIST handling operations that are common in Drasi Continuous Queries.

drasi.listMin()

The drasi.listMin function returns the minimum value contained in a LIST. Null values are ignored.

Syntax

drasi.listMin(list)

Arguments

The drasi.listMin function accepts one argument:

Returns

The drasi.listMin function returns a single value, which is the minimum value from the provided list. Determination of which value is minimum depends on the types of values in the list. For example:

• drasi.listMin([45, 33, 66]) returns 33
• drasi.listMin([“banana”, “apple”, “peach”]) returns “apple”
• drasi.listMin(null) returns null

drasi.listMax()

The drasi.listMax function returns the maximum value contained in a LIST. Null values are ignored.

Syntax

drasi.listMax(list)

Arguments

The drasi.listMax function accepts one argument:

Returns

The drasi.listMax function returns a single value, which is the maximum value from the provided list. Determination of which value is maximum depends on the types of values in the list. For example:

• drasi.listMax([45, 33, 66]) returns 66
• drasi.listMax([“banana”, “apple”, “peach”]) returns “peach”
• drasi.listMax(null) returns null

Drasi TEMPORAL Functions

Drasi TEMPORAL functions make it possible to write Continuous Queries that use previous values of Nodes and Relations in the logic of the query.

A Continuous Query containing TEMPORAL functions must have a temporal Element Index enabled.

drasi.getVersionByTimestamp()

The drasi.getVersionByTimestamp function returns the version of a specified Element as it was at the specified time.

The Continuous Query containing the drasi.getVersionByTimestamp function must have a temporal Element Index enabled.

Syntax

drasi.getVersionByTimestamp(element, timestamp)

Arguments

The drasi.getVersionByTimestamp function accepts two arguments:

Returns

The drasi.getVersionByTimestamp function returns an Element (Node or Relation).

drasi.getVersionsByTimeRange()

The drasi.getVersionsByTimeRange function returns a LIST containing all the versions of a specified Element that exist between two points in time.

The Continuous Query containing the drasi.getVersionsByTimeRange function must have a temporal Element Index enabled.

Syntax

drasi.getVersionsByTimeRange(element, from_timestamp, to_timestamp, include_initial_version)

Arguments

The drasi.getVersionsByTimeRange function accepts four arguments:

Returns

The drasi.getVersionsByTimeRange function returns a LIST of Elements (Node or Relation).

Drasi FUTURE Functions

Drasi FUTURE functions makes it possible to use Continuous Queries in situations where it is important to react to the absence of change. For example, if it is important to know when Invoices become 10 days overdue, or which customers haven’t logged in to their account for over 2 weeks. Both of these situations (depending on the database schema) might only occur as a result of no change being made to the Invoice or Customer record.

drasi.trueLater()

The drasi.trueLater function makes it possible to write Continuous Queries that evaluate a BOOLEAN expression at a specific point in time, instead of at the point in time when the change being processed occurred.

Syntax

drasi.trueLater(expression, timestamp)

Arguments

The drasi.trueLater function accepts two arguments:

Returns

If the timestamp is less than or equal to the time associated with the change being processed (i.e. the desired time has already occurred), drasi.trueLater will evaluate and return the value of expression. Otherwise, drasi.trueLater will return the special value drasi.awaiting indicating the Drasi cannot yet evaluate the expression, and schedules the solution currently being evaluated to be re-evaluated at the time specified by timestamp.

More formally:

drasi.trueUntil()

The drasi.trueUntil function makes it possible to write Continuous Queries that evaluate whether a BOOLEAN expression remains TRUE at least until a specific point in time.

Syntax

drasi.trueUntil(expression, timestamp)

Arguments

The drasi.trueUntil function accepts two arguments:

Returns

• If the timestamp is less than or equal to the time associated with the change being processed (i.e. the desired time has already occurred), drasi.trueUntil will evaluate and return the value of expression.
• Otherwise, if expression evaluates to TRUE, drasi.trueUntil will return the special value drasi.awaiting indicating that Drasi has scheduled the solution currently being evaluated to be re-evaluated (for remaining TRUE) at the time specified by timestamp.
• If, at any time before timestamp, expression is found to be FALSE, drasi.trueUntil returns FALSE and cancels any currently scheduled reprocessing for the current solution.

More formally:

drasi.trueFor()

The drasi.trueFor function makes it possible to write Continuous Queries that evaluate whether a BOOLEAN expression remains TRUE for at least a period of time from the time at which the change being evaluated occurred.

Syntax

drasi.trueFor(expression, duration)

Arguments

The drasi.trueFor function accepts two arguments:

Returns

• If the time when expression became TRUE with duration added to it is less than or equal to the time associated with the change being processed (i.e. the desired time has already occurred), drasi.trueUntil will evaluate and return the value of expression.
• Otherwise, if expression evaluates to TRUE, drasi.trueUntil will return the special value drasi.awaiting indicating that Drasi has scheduled the solution currently being evaluated to be re-evaluated (for remaining TRUE) at the time specified by the current change time plus the duration.
• If, at any time before duration passes, expression is found to be FALSE, drasi.trueUntil returns FALSE and cancels any currently scheduled reprocessing for the current solution.

More formally:

Drasi WINDOWING Functions

Drasi WINDOWING functions enable time-based windowing operations over data streams, allowing you to perform calculations over sliding time windows.

drasi.slidingWindow()

The drasi.slidingWindow function makes it possible to write Continuous Queries that apply aggregation functions over a sliding time window. This enables calculations like moving averages, rolling maximums, or other time-based aggregations that update as data changes over time.

Syntax

drasi.slidingWindow(duration, aggregation_expression)

Arguments

The drasi.slidingWindow function accepts two arguments:

Returns

The drasi.slidingWindow function returns the result of the aggregation expression computed over all values within the specified time window from the current time.

Example

The following example calculates a 10-second sliding maximum, a 20-second sliding maximum, and a 10-second sliding average of price values:

MATCH 
  (p:Price)
RETURN
  p.Group AS group,
  drasi.slidingWindow(duration({ seconds: 10 }), max(p.Value)) AS slidingMax10,
  drasi.slidingWindow(duration({ seconds: 20 }), max(p.Value)) AS slidingMax20,
  drasi.slidingWindow(duration({ seconds: 10 }), avg(p.Value)) AS slidingAvg10

In this example:

• slidingMax10 returns the maximum price value within the last 10 seconds
• slidingMax20 returns the maximum price value within the last 20 seconds
• slidingAvg10 returns the average price value within the last 10 seconds

As new price values arrive or old values age out of the time window, the sliding window calculations automatically update to reflect the current window of data.

Behavior with Insert, Update, and Delete Operations

Unlike traditional event streams, Drasi’s sliding window function operates on uniquely identified graph elements, which means it handles insert, update, and delete operations in a specific way. The window tracks the identity of anchor graph elements rather than treating each change as an independent event.

Key Behavior: When an element in the window is updated, its value is modified in place rather than creating a duplicate entry. This means the element moves to the front of the window with its new value, maintaining a count of 1 for that element.

Example

Consider the following query that projects four different windows over the same data:

MATCH  
  (p:Price) 
RETURN 
  drasi.slidingWindow(duration({ seconds: 10 }), avg(p.Value)) AS avg10, 
  drasi.slidingWindow(duration({ seconds: 10 }), count(p)) AS count10, 
  drasi.slidingWindow(duration({ seconds: 10 }), max(p.Value)) AS max10, 
  drasi.slidingWindow(duration({ seconds: 20 }), max(p.Value)) AS max20

The following table illustrates the results of inserting elements A, B, C, and D, followed by updating D:

Important Note: When element D is updated at t=30 from value 100 to 80, the average and max values drop to 80 even though the previous value of 100 is still within the time window. This occurs because Drasi tracks the identity of the anchor graph element tied to the original change. When the element’s value is updated, it is not duplicated in the window but rather moved to the front with the new value.

This behavior is particularly intuitive for sum() and count() aggregations, where you would expect the count to remain at 1 through an update rather than becoming 2. It ensures that each unique graph element contributes only once to the window calculation, regardless of how many times it has been updated.

Drasi STATISTICAL Functions

drasi.linearGradient()

The drasi.linearGradient function is an aggregating function that fits a straight line to a set of X and Y coordinates, and returns the slope of that line. As values are added, removed or updated, the line will be adjusted to reflect the relationship between the X and Y values. The slope of the line can be used to predict a value for Y given a known value of X, by multiplying the slope by the X value.

Syntax

drasi.linearGradient(x, y)

Arguments

The drasi.linearGradient function accepts two arguments:

Returns

The slope or gradient of the line that best fits the current data set. This can be used to predict the value of Y for a given value of X by multiplying it by the known X value.

Example

The following example will return the gradient of each line, given the known points associated with that line.

MATCH
  (l:Line)-[:HAS]->(p:Point)
RETURN
  l.id as LineId,
  drasi.linearGradient(p.x, p.y) as Gradient