Behavioural signal functions
Spot behaviour that changes in a way an honest customer's does not: a refund pattern that shifts, orders from somewhere new, addresses shared by many accounts, an order surge.
Syntax
Write the function's name and its arguments. The period is written one of three ways: a date window name such as ROLLING_90_DAYS (the date window functions), a start date and an end date such as "2026-01-01", "2026-03-31", or an accounting period id. An optional location at the end limits the answer to one location.
SUDDEN_REFUND_PATTERN_SHIFT(accountId, period, [periodEnd], [locationId])
VELOCITY_SPIKE_ANOMALY(accountId, period, [periodEnd], [locationId])
DEVICE_CHANGE_HIGH_VALUE_ORDER(accountId, period, [periodEnd], [locationId])
ADDRESS_CHANGE_PRE_REFUND(accountId, period, [periodEnd], [locationId])
MULTI_ACCOUNT_ADDRESS_CLUSTER(accountId, period, [periodEnd], [locationId])
GEO_MISMATCH_PATTERN(accountId, period, [periodEnd], [locationId])Parameters and arguments
Arguments are written in brackets, separated by commas. An argument in square brackets is optional.
SUDDEN_REFUND_PATTERN_SHIFT
Required: YesaccountId
Required: Yesperiod
Required: NoperiodEnd
Required: NolocationIdVELOCITY_SPIKE_ANOMALY
Required: YesaccountId
Required: Yesperiod
Required: NoperiodEnd
Required: NolocationIdDEVICE_CHANGE_HIGH_VALUE_ORDER
Required: YesaccountId
Required: Yesperiod
Required: NoperiodEnd
Required: NolocationIdADDRESS_CHANGE_PRE_REFUND
Required: YesaccountId
Required: Yesperiod
Required: NoperiodEnd
Required: NolocationIdMULTI_ACCOUNT_ADDRESS_CLUSTER
Required: YesaccountId
Required: Yesperiod
Required: NoperiodEnd
Required: NolocationIdGEO_MISMATCH_PATTERN
Required: YesaccountId
Required: Yesperiod
Required: NoperiodEnd
Required: NolocationId
Examples
Customers whose refund rate in the second half of the window is well above their rate in the first half.
Return type and behaviour
Each function returns one value. The table shows its type, what it does and one way to write it; the examples use the functions in realistic statements.
| Function | Returns | Behaviour | Form |
|---|---|---|---|
SUDDEN_REFUND_PATTERN_SHIFT | list of signals | Customers whose refund rate rose sharply between the first and second half of the window | SUDDEN_REFUND_PATTERN_SHIFT("ACCOUNT_ID", "ROLLING_90_DAYS") |
VELOCITY_SPIKE_ANOMALY | list of signals | Days when order volume ran far above the window's average | VELOCITY_SPIKE_ANOMALY("ACCOUNT_ID", "ROLLING_30_DAYS") |
DEVICE_CHANGE_HIGH_VALUE_ORDER | list of signals | Large orders placed from a country other than the customer's usual one | DEVICE_CHANGE_HIGH_VALUE_ORDER("ACCOUNT_ID", "ROLLING_30_DAYS") |
ADDRESS_CHANGE_PRE_REFUND | list of signals | Refunds that go to a different country or postcode than the order came from | ADDRESS_CHANGE_PRE_REFUND("ACCOUNT_ID", "ROLLING_90_DAYS") |
MULTI_ACCOUNT_ADDRESS_CLUSTER | list of signals | Places where several customer accounts share an address and many of them are refunding | MULTI_ACCOUNT_ADDRESS_CLUSTER("ACCOUNT_ID", "ROLLING_90_DAYS") |
GEO_MISMATCH_PATTERN | list of signals | Customers whose orders keep coming from somewhere other than their registered address | GEO_MISMATCH_PATTERN("ACCOUNT_ID", "ROLLING_90_DAYS") |
Every signal function answers a list of signal rows, strongest first
| Field | Type | Meaning |
|---|---|---|
entityId | text | The customer, staff member, geographic cluster, period or account the signal is about |
entityType | text | CUSTOMER, STAFF, GEO_CLUSTER, PERIOD or TENANT |
signalType | text | The signal's name in words, such as HighRefundVelocity |
severity | text | LOW, MEDIUM, HIGH or CRITICAL, graded from the size of the exposure |
confidenceScore | text | A decimal between 0 and 1 written as text. It grows with the amount of evidence behind the signal |
impactAmount | money | The money exposed by the signal, with its currency |
detectedAt | text | When the signal was found |
evidence | record | The facts the signal rests on. The fields differ for each function and are listed below |
What each function detects and its evidence
| Function | Entity | Evidence fields |
|---|---|---|
SUDDEN_REFUND_PATTERN_SHIFT | CUSTOMER | recentOrderCount, recentRefundCount, historicOrderCount, historicRefundCount, rateShift and recentRefundAmount |
VELOCITY_SPIKE_ANOMALY | TENANT | spikeDate, dailyOrderCount, dailyOrderValue, avgDailyOrderCount and burstMultiple |
DEVICE_CHANGE_HIGH_VALUE_ORDER | CUSTOMER | orderId, orderTotal, orderCountry and historicHomeCountry |
ADDRESS_CHANGE_PRE_REFUND | CUSTOMER | orderId, refundId, orderCountry, orderZip, refundCountry, refundZip and refundAmount |
MULTI_ACCOUNT_ADDRESS_CLUSTER | GEO_CLUSTER | clusterKey, country, state, zipCode, clusterCustomerCount, refundingCustomerCount, totalRefundAmount and refundRate |
GEO_MISMATCH_PATTERN | CUSTOMER | customerCountry, customerZip, mismatchedOrderCount, countryMismatchCount, zipMismatchCount and totalOrderValue |
The limits that decide when a signal fires are tuned by the platform and are not part of the contract. An empty list means nothing in the window met the signal's test.
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-5001 | The function was given the wrong number of arguments. The message names the function and the counts | Give it the arguments listed under Parameters |
HTQL-1004 Unsupported function | The name is not a function this engine runs | Check the name and its spelling against this entry |
Limitations
GEO_MISMATCH_PATTERNneeds a pattern, several mismatched orders, not a single shipping exception.- The address signals compare countries and postcodes on records. They do not read device identifiers or network addresses.
MULTI_ACCOUNT_ADDRESS_CLUSTERand the day signals read monthly or daily summaries, so a window is widened to whole months where the summary is monthly.
Permissions and security
These functions read customer, refund, order and daily order summaries. The caller needs read access to the records named, and nothing is written.
They are governed by the same read access as the tables they read, so no separate grant is needed beyond it.
Best practices
- Combine signals: a refund shift with an address change for the same customer is stronger than either alone.
- Review
HIGHandCRITICALrows first, then sort the rest byimpactAmount. - Do not block a customer on a signal alone. A signal says where to look.