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

    accountId

    Required: Yes
  • period

    Required: Yes
  • periodEnd

    Required: No
  • locationId

    Required: No
  • VELOCITY_SPIKE_ANOMALY

    accountId

    Required: Yes
  • period

    Required: Yes
  • periodEnd

    Required: No
  • locationId

    Required: No
  • DEVICE_CHANGE_HIGH_VALUE_ORDER

    accountId

    Required: Yes
  • period

    Required: Yes
  • periodEnd

    Required: No
  • locationId

    Required: No
  • ADDRESS_CHANGE_PRE_REFUND

    accountId

    Required: Yes
  • period

    Required: Yes
  • periodEnd

    Required: No
  • locationId

    Required: No
  • MULTI_ACCOUNT_ADDRESS_CLUSTER

    accountId

    Required: Yes
  • period

    Required: Yes
  • periodEnd

    Required: No
  • locationId

    Required: No
  • GEO_MISMATCH_PATTERN

    accountId

    Required: Yes
  • period

    Required: Yes
  • periodEnd

    Required: No
  • locationId

    Required: No

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.

FunctionReturnsBehaviourForm
SUDDEN_REFUND_PATTERN_SHIFTlist of signalsCustomers whose refund rate rose sharply between the first and second half of the windowSUDDEN_REFUND_PATTERN_SHIFT("ACCOUNT_ID", "ROLLING_90_DAYS")
VELOCITY_SPIKE_ANOMALYlist of signalsDays when order volume ran far above the window's averageVELOCITY_SPIKE_ANOMALY("ACCOUNT_ID", "ROLLING_30_DAYS")
DEVICE_CHANGE_HIGH_VALUE_ORDERlist of signalsLarge orders placed from a country other than the customer's usual oneDEVICE_CHANGE_HIGH_VALUE_ORDER("ACCOUNT_ID", "ROLLING_30_DAYS")
ADDRESS_CHANGE_PRE_REFUNDlist of signalsRefunds that go to a different country or postcode than the order came fromADDRESS_CHANGE_PRE_REFUND("ACCOUNT_ID", "ROLLING_90_DAYS")
MULTI_ACCOUNT_ADDRESS_CLUSTERlist of signalsPlaces where several customer accounts share an address and many of them are refundingMULTI_ACCOUNT_ADDRESS_CLUSTER("ACCOUNT_ID", "ROLLING_90_DAYS")
GEO_MISMATCH_PATTERNlist of signalsCustomers whose orders keep coming from somewhere other than their registered addressGEO_MISMATCH_PATTERN("ACCOUNT_ID", "ROLLING_90_DAYS")

Every signal function answers a list of signal rows, strongest first

FieldTypeMeaning
entityIdtextThe customer, staff member, geographic cluster, period or account the signal is about
entityTypetextCUSTOMER, STAFF, GEO_CLUSTER, PERIOD or TENANT
signalTypetextThe signal's name in words, such as HighRefundVelocity
severitytextLOW, MEDIUM, HIGH or CRITICAL, graded from the size of the exposure
confidenceScoretextA decimal between 0 and 1 written as text. It grows with the amount of evidence behind the signal
impactAmountmoneyThe money exposed by the signal, with its currency
detectedAttextWhen the signal was found
evidencerecordThe facts the signal rests on. The fields differ for each function and are listed below

What each function detects and its evidence

FunctionEntityEvidence fields
SUDDEN_REFUND_PATTERN_SHIFTCUSTOMERrecentOrderCount, recentRefundCount, historicOrderCount, historicRefundCount, rateShift and recentRefundAmount
VELOCITY_SPIKE_ANOMALYTENANTspikeDate, dailyOrderCount, dailyOrderValue, avgDailyOrderCount and burstMultiple
DEVICE_CHANGE_HIGH_VALUE_ORDERCUSTOMERorderId, orderTotal, orderCountry and historicHomeCountry
ADDRESS_CHANGE_PRE_REFUNDCUSTOMERorderId, refundId, orderCountry, orderZip, refundCountry, refundZip and refundAmount
MULTI_ACCOUNT_ADDRESS_CLUSTERGEO_CLUSTERclusterKey, country, state, zipCode, clusterCustomerCount, refundingCustomerCount, totalRefundAmount and refundRate
GEO_MISMATCH_PATTERNCUSTOMERcustomerCountry, 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
ErrorWhat happenedHow to recover
HTQL-5001The function was given the wrong number of arguments. The message names the function and the countsGive it the arguments listed under Parameters
HTQL-1004 Unsupported functionThe name is not a function this engine runsCheck the name and its spelling against this entry
Limitations
  • GEO_MISMATCH_PATTERN needs 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_CLUSTER and 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 HIGH and CRITICAL rows first, then sort the rest by impactAmount.
  • Do not block a customer on a signal alone. A signal says where to look.