Rule Expressions

Rule expressions are written in a small expression language with familiar comparison and logical operators. Each expression is a condition. When it evaluates to true on a record, that record is flagged with an alert.

{{data-point.carbon_content}} not between 0.50 and 0.90

This page is the reference for the full set of operators and patterns. For a walkthrough of writing your first rule, see Create a Data Rule.

Variables

Variables reference the data Mangrove evaluates the expression against. They are wrapped in double curly braces and always carry a prefix naming what kind of thing they point at.

Form	Used in	Points at
`{{data-point.<slug>}}`	Data Points rules	A data point on the event being evaluated.
`{{node.<name>}}`	Batch Calculation rules	A node in the selected model.
`{{node.<name>.<slug>}}`	Batch Calculation rules	A specific data point type on that node, when the node name alone is ambiguous.

{{data-point.carbon_content}}
{{node.total_emissions}}
{{node."Biochar Produced".carbon_content}}

Use double quotes around a node name that contains spaces or other special characters, as in the third example. The prefix has to match what the rule runs on. A Data Points rule cannot reference {{node.*}}, and a Batch Calculation rule cannot reference {{data-point.*}}. Mismatches are rejected when you save. What the editor offers follows from that:

Data Points rules use data point slugs. These rules apply across the whole project, so autocomplete offers every non-static data point type in it, and the rule evaluates against any event whose data points satisfy the condition. One rule reads a single event type: a condition referencing types from two of them is rejected when you save, and autocomplete does not narrow the list to stop you writing one.
Batch Calculation rules use nodes in the selected model.

Type {{ in the rule editor to open autocomplete. Each suggestion shows the variable name and its description, value type, or unit when available, and inserts the full prefixed form for you.

Comparison operators

Operator	Meaning
`=`	Equal to
`!=`	Not equal to
`<`	Less than
`<=`	Less than or equal to
`>`	Greater than
`>=`	Greater than or equal to

{{data-point.ash_content}} > 0.05
{{data-point.batch_status}} != 'verified'

Logical operators

Combine conditions with AND, OR, and NOT. Use parentheses to group. NOT binds tightest, then AND, then OR.

{{data-point.ash_content}} > 0.05 AND {{data-point.moisture}} < 0.10
NOT ({{data-point.feedstock_type}} = 'manure' OR {{data-point.feedstock_type}} = 'crop_residue')

Range and set operators

Operator	Example	Triggers when…
`BETWEEN ... AND ...`	`{{data-point.ph}} between 6.0 and 8.0`	The value is within the range (inclusive).
`NOT BETWEEN ... AND ...`	`{{data-point.ph}} not between 6.0 and 8.0`	The value is outside the range.
`IN (...)`	`{{data-point.country}} in ('US', 'CA', 'MX')`	The value matches any item in the list.
`NOT IN (...)`	`{{data-point.country}} not in ('US', 'CA')`	The value matches none of the items in the list.

Text operators

Operator	Example	Triggers when…
`CONTAINS`	`{{data-point.notes}} contains 'override'`	The text contains the substring.
`STARTS WITH`	`{{data-point.tracking_id}} starts with 'TMP-'`	The text starts with the prefix.
`ENDS WITH`	`{{data-point.filename}} ends with '.csv'`	The text ends with the suffix.
`MATCHES`	`{{data-point.lot_code}} matches '[A-Z]{2}-[0-9]+'`	The text matches the regular expression.

String literals use single quotes. MATCHES patterns use Ruby regular expression syntax, and each match attempt is bounded by a one-second timeout, so keep patterns anchored and avoid ones that backtrack heavily. There is no NOT MATCHES operator, and the same goes for the other text operators. Negate them with the NOT prefix instead: NOT {{data-point.lot_code}} matches '[A-Z]{2}-[0-9]+'.

Presence operators

Use these to check whether a value was recorded.

Operator	Triggers when…
`IS MISSING`	The data point holds no value at all.
`IS PRESENT`	The data point holds a value that is not empty text and not `false`.

{{data-point.lab_sample_id}} is missing
{{data-point.adjustment_note}} is present AND {{data-point.adjustment_note}} = 'manual'

Two cases fall between the two operators, and neither one catches them. A text data point holding an empty string is not missing, because a value was stored, and it is not present either. A boolean holding false behaves the same way. Test for those with = '' and = false instead. A reading that was never submitted has no data point for the rule to evaluate, so IS MISSING stays out of its reach.

Aggregates

Aggregate functions roll a set of values into a single number. Use one as the left side of a comparison.

Function	Returns
`COUNT`	Number of values
`SUM`	Sum of values
`AVG`	Average of values
`MIN`	Smallest value
`MAX`	Largest value

SUM({{data-point.batch_input_mass}}) > 1000
AVG({{data-point.moisture}}) not between 0.05 and 0.15
COUNT({{data-point.lab_sample_id}}) < 3

SUM, AVG, MIN and MAX need a numeric data point type and are rejected when you save otherwise. COUNT works on any type. By default an aggregate covers only the data points on the event being evaluated. To ask a question that spans events, add a window.

Windowed aggregates

Add a WITHIN clause inside the aggregate’s parentheses to widen the set from one event to many. Use it for rules about how often something happens, or about a total across a period.

COUNT({{data-point.readings}} WITHIN ROLLING 1.week) > 3
SUM({{data-point.emissions}} WITHIN CALENDAR YEAR) > 1000

Pick the mode that matches the question you are asking.

ROLLING

A sliding window centred on the data point being evaluated, reaching the full duration in both directions. For a value captured at a single point in time, ROLLING 7.days therefore spans 14 days: the seven days before it and the seven after. Where the event carries a start and an end, the window reaches out from both, so the span is the event’s own duration plus the window twice. Use it for proximity and anomaly questions, such as flagging a cluster of readings around one point in time.

COUNT({{data-point.readings}} WITHIN ROLLING 7.days) > 3
AVG({{data-point.temperature}} WITHIN ROLLING 24h) > 100
SUM({{data-point.volume}} WITHIN ROLLING 30.days) > 1000

Durations take two forms:

Form	Units	Example
`<N>.<unit>`	`second`, `minute`, `hour`, `day`, `week`, `month`, `year` (singular or plural)	`1.week`, `30.days`
`<N><unit>`	`s` seconds, `m` minutes, `h` hours	`24h`, `90m`

A ROLLING duration has to be greater than zero. ROLLING 0.days is rejected when you save.

CALENDAR

The calendar bucket the evaluated data point falls in, in your account’s timezone. Use it for cohort and reporting-period questions, such as “no more than one of these per calendar month”.

COUNT({{data-point.biochar}} WITHIN CALENDAR MONTH) > 1
SUM({{data-point.emissions}} WITHIN CALENDAR YEAR) > 1000
COUNT({{data-point.batches}} WITHIN CALENDAR WEEK) > 5

Units are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, and YEAR. Weeks start on Monday. The sub-hour units suit duplicate detection at a known cadence, such as one meter reading per clock minute. Calendar buckets are absolute. February 27 and March 2 sit in different MONTH buckets and never pair, however close together they are. Two readings two seconds apart at 12:00:59 and 12:01:01 fall in different MINUTE buckets for the same reason. Use ROLLING when you care about elapsed time, and CALENDAR when you care about the clock bucket.

What to know before you use one

The evaluated data point is in the set when the window names its own type. COUNT(...) = 1 is therefore true for a data point with no neighbours, so write COUNT(...) > 1 to mean “more than just this one”. In a rule that references several types, a value is not a member of a window over a different type.
The preview cannot evaluate a windowed aggregate. It reads them against an empty set, so COUNT previews as 0 and the others as no value. Preview the rest of the condition there, and expect the window itself to be exercised only once the rule is saved.
Windows only work on {{data-point.*}} variables. A WITHIN clause on a {{node.*}} reference is rejected when you save, so Batch Calculation rules cannot use one.
The rule’s effective dates clamp the window. A CALENDAR MONTH bucket is cut short if the rule only became effective partway through that month.
You can use more than one windowed aggregate in a rule. Each resolves its own set independently.

Booleans and numbers

Booleans are written true and false (case-insensitive).
Numbers are written without quotes. Both integers and decimals work: 0, 42, 3.14, 0.005. Negative numbers are allowed.

Common patterns

These examples assume your project has data points with the slugs shown. Substitute slugs that exist in your project.

# Out-of-range alert
{{data-point.carbon_content}} not between 0.50 and 0.90

# Required value missing or blank
{{data-point.lab_sample_id}} IS MISSING OR {{data-point.lab_sample_id}} = ''

# Tracking ID format check
NOT {{data-point.tracking_id}} matches '[A-Z]{2}-[0-9]{6}'

# Batch CI sanity check
{{data-point.ci_score}} > 30 OR {{data-point.ci_score}} < -50

# Fewer than three lab samples recorded on one event
COUNT({{data-point.lab_sample_id}}) < 3

# More than one delivery logged in the same calendar month
COUNT({{data-point.delivery_mass}} WITHIN CALENDAR MONTH) > 1

# Repeated readings clustered within a week either side
COUNT({{data-point.meter_reading}} WITHIN ROLLING 7.days) > 3

Tips for writing good rules

Phrase the rule as the failure case. A rule with the expression {{data-point.ph}} not between 6.0 and 8.0 triggers when pH is out of range, which is the alert you want.
Validate before saving. Validating previews the matches from the last 90 days. Use it to catch over-eager rules before they generate noise. When nothing matches, a range filter appears with the result so you can look further back.
Cover every shape of an empty value. IS MISSING catches a data point with no value stored. It misses a text data point holding an empty string and a boolean holding false, so a rule that has to catch those needs each test spelled out with its own variable: {{data-point.lab_sample_id}} IS MISSING OR {{data-point.lab_sample_id}} = ''.
Say why in the rule name. Expressions are terse and a rule carries no separate description field, so the name and the alert message are where you explain what the rule is for.

Overview

Production Accounting

Data Collection

Data Rules

Reporting

Inventory

Account Admin

Portfolio

Variables

Comparison operators

Logical operators

Range and set operators

Text operators

Presence operators

Aggregates

Windowed aggregates

ROLLING

CALENDAR

What to know before you use one

Booleans and numbers

Common patterns

Tips for writing good rules

​Variables

​Comparison operators

​Logical operators

​Range and set operators

​Text operators

​Presence operators

​Aggregates

​Windowed aggregates

​ROLLING

​CALENDAR

​What to know before you use one

​Booleans and numbers

​Common patterns

​Tips for writing good rules

Variables

Comparison operators

Logical operators

Range and set operators

Text operators

Presence operators

Aggregates

Windowed aggregates

ROLLING

CALENDAR

What to know before you use one

Booleans and numbers

Common patterns

Tips for writing good rules