Observable Alerts
Summary
- Observable Alerts fire when a live Observable Expression Rule becomes true
- They are ideal for Alerts that are based on history or time conditions
- Examples include change counts, highs and lows, silence, grid-wide activity, and row-event counts
- The Rule is a boolean Expression built from Observable Functions (that use curly braces)
Observable Alerts watch how data has changed (or, indeed not changed) in AG Grid over time.
They leverage AdapTable's recorded cell / row history.
Typical use cases for Observable Alerts include:
- a cell has changed 3 times in the last 2 minutes
- a value is at its highest in the last hour
- there have been no ticks for 5 seconds
- a column changed grid-wide N times within a window
- at least N rows were added or removed in a timeframe
Find Out More
See Observable Expressions for full details of the many observable-related functions available
Observable Functions
There are many Observable Functions available.
The ones which are most commonly used in Alerts are:
| Function | Example Alert Rule |
|---|---|
CHANGE_COUNT | CHANGE_COUNT{[price], WITHIN(5m)} >= 3 — choppy |
NO_CHANGES | NO_CHANGES{[price], WITHIN(20s)} — this row has gone quiet |
NET_CHANGE | NET_CHANGE{[price], WITHIN(1h)} > 10 — large absolute move |
PERCENT_CHANGE | PERCENT_CHANGE{[price], WITHIN(1h)} > 5 — up more than 5% in the hour |
HIGHEST / LOWEST | [price] = HIGHEST{[price], WITHIN(1d)} — at the daily high |
PREVIOUS | [price] > PREVIOUS{[price]} — higher than the last tick |
ROW_AGE | ROW_AGE{} < 30s — row added in the last 30 seconds |
ROWS_ADDED / ROWS_REMOVED | ROWS_ADDED{WITHIN(1m)} >= 3 — burst of adds in a minute |
Find Out More
See Observable Expressions for the full catalogue and timeframes (e.g. WITHIN, LAST_N, ALL_ROWS())
Creating Alert Expressions
Observable Functions always return a value.
Note
The return value can be of any kind, though it is most commonly a number
However Alert Expressions need to return a boolean - so they trigger if they evaluate as true.
Accordingly, in order to create an Alert Rule, you need 2 steps:
- create a normal Observable Expression:
CHANGE_COUNT{[price], WITHIN(5m)}- Wrap that Observable Expression inside a comparison operation:
CHANGE_COUNT{[price], WITHIN(5m)} >Developer Guide
Providing Observable Alerts in Initial State
const initialState: InitialState = {
Alert: {
AlertDefinitions: [
{
Name: 'alert-stars-choppy',
Type: 'Observable',
MessageType: 'Info',
MessageHeader: 'Choppy stars',
Scope: {All: true},
Rule: 'CHANGE_COUNT{[github_stars], WITHIN(2m)} >= 3',
AlertProperties: {
DisplayNotification: true,
},
},
{
Name: 'alert-issues-at-high',
Type: 'Observable',
MessageType: 'Success',
Scope: {All: true},
Rule: "[open_issues_count] = HIGHEST{[open_issues_count], WITHIN(1h)} AND [language] = 'JavaScript'",
AlertProperties: {
DisplayNotification: true,
HighlightCell: true,
},
},
],
},
};Set Type: 'Observable' for live rules. Use Scope: { All: true } unless the rule is grid-level only.
Wrap observable functions (curly braces) in a comparison so the rule evaluates to true / false.
Observable alerts default to firing when the rule becomes true (TriggerPolicy.FireOn: 'BecomeTrue'). See Alerts Technical Reference.
Per Row Changes
The most common Observable Alert use case is watching each row's own change history.
- This demo showcases 2 Observable Alerts which focus on per-row changes:
- Tell me if Github Stars has changed 3 times in this row within 2 minutes:
CHANGE_COUNT{[github_stars], WITHIN(2m)} >= 3 - Tell me if Open Issues is at its 1-hour high on JavaScript rows:
[open_issues_count] = HIGHEST{[open_issues_count], WITHIN(1h)} AND [language] = 'JavaScript'
- Tell me if Github Stars has changed 3 times in this row within 2 minutes:
- Click the Add Star Action Column button next to
Github Stars; once it is clicked 3 times in a row, the Info Alert will be triggered - Click the Open an Issue button next to
Open Issueson a JavaScript row to push it to a new high
Grid-wide Changes
Observable Alerts can also fire based on activitiy across the whole Grid.
This is by done by using the ALL_ROWS() keyword.
Hint
This is useful when you care about overall activity rather than a single row
- This example contains 2 Observable Alerts which operate over the whole Grid:
- Tell me if Language changed 3 times anywhere in the Grid within 5 minutes -
CHANGE_COUNT{[language], WITHIN(5m), ALL_ROWS()} >= 3 - Tell me if Github Stars changed twice within a minute, counting only MIT License rows -
CHANGE_COUNT{[github_stars] WHERE [license] = 'MIT License', WITHIN(1m), ALL_ROWS()} >= 2
- Tell me if Language changed 3 times anywhere in the Grid within 5 minutes -
No Changes
Observable Alerts are also ideal for detecting silence — when expected ticks stop.
Note
- This is particularly useful if you have ticking data or you expect some changes at some point
NO_CHANGESis the Function for this: it returns a boolean, so it can be the Alert Rule on its own
No Changes Per Row
Watch one column on each row:
// Fires per row when that row's price has been quiet for 20 seconds
NO_CHANGES{[price], WITHIN(20s)}Or watch every column on the row with ANY_COL():
NO_CHANGES{ANY_COL(), WITHIN(20s)}No Changes Per Grid
Add ALL_ROWS() for one shared reading across the whole Grid.
// Fires once when no row has changed price in 5 seconds
NO_CHANGES{[price], WITHIN(5s), ALL_ROWS()}Hint
ANY_COL()withALL_ROWS()is the usual “feed stalled” pattern — silence anywhere, on any columnDisplaySystemStatusMessageon the Alert writes the same message into the System Status bar
NO_CHANGES{ANY_COL(), WITHIN(10s), ALL_ROWS()}- A live price feed updates
Lastseveral times a second, and the Column flashes on each tick - The Alert Rule is
NO_CHANGES{ANY_COL(), WITHIN(2s), ALL_ROWS(), TRIGGER('tick')} DisplaySystemStatusMessageis on, so when the Rule fires the System Status bar shows an Error
- Watch prices tick and flash
- Click Simulate system down in 10 secs — ticking continues
- After 10 seconds the feed stops; 2 seconds of silence later the Error System Status appears
- Click Resume Feed to restore the ticks
Row Change Counts
AdapTable provides a Row Change Alert which is a specialist Alert Type.
This common use case occurs when Rows are added or removed from the Grid.
However it is possible to extend these with fully-powered Observable Expressions — e.g. alert only when a specific number of rows have been added within a timeframe:
// Tell me if more than 10 rows were added in the last minute
ROWS_ADDED{WITHIN(1m)} > 10- Alert Type is
Observable(not Row Change) - Rule:
ROWS_ADDED{WITHIN(30s)} >= 3— fires when at least 3 rows are added within 30 seconds - Unlike a Row Change Alert, this does not fire on every single add — only when the count in the window crosses the threshold
- Click the Add Row Dashboard button three times (within 30 seconds) and note the Warning Alert
Suspending Observable Alerts
When an Observable Alert is suspended, the subscription is removed.
It will then be re-created when unsuspended.
Caution
- This means that any changes in the data during the Alert's suspension are not observed
- The count / watch starts again from scratch (rather than continues) when the Alert is unsuspended