Time Functions - FinWatch

All aggregate functions accept a time window in ISO 8601 duration format:

Format	Meaning	Example Use Case
`"PT30S"`	30 seconds	Rapid-fire card testing detection
`"PT15M"`	15 minutes	BIN attack detection
`"PT1H"`	1 hour	Short-burst velocity checks
`"PT24H"`	24 hours	Daily velocity and volume limits
`"P1D"`	1 day	Same as PT24H
`"P7D"`	7 days	Weekly pattern analysis
`"P30D"`	30 days	Monthly behavioral baselines

Performance Note: Smaller time windows are significantly faster to query. A "PT1H" query scans far less data than a "P30D" query. Use the smallest window that effectively catches the pattern you’re looking for. Time functions extract temporal components from the transaction’s timestamp field. They enable rules based on the time of day, day of the week, or other calendar-based patterns.

`hour_of_day()`

Signature: hour_of_day(<timestamp_field>) Return Value: An integer from 0 to 23 representing the hour in UTC. Description: Extracts the hour component from a timestamp. The primary use case is detecting transactions outside of normal business hours. Example:

rule UnusualTransactionTime {
    description "Large transactions during unusual hours receive extra scrutiny."

    when hour_of_day(timestamp) >= 1
     and hour_of_day(timestamp) < 5
     and amount > 1000

    then review
         score   0.6
         reason  "Large transaction during unusual hours (1 AM - 5 AM)"
}

`day_of_week()`

Signature: day_of_week(<timestamp_field>) Return Value: An integer from 0 (Sunday) to 6 (Saturday). Description: Extracts the day of the week. Useful for detecting weekend activity on business accounts, or activity on holidays. Special Feature: Also supports in with string day names: ("Sunday", "Saturday"). Example:

rule WeekendTransactionCheck {
    description "Flags high-value transactions on weekends for business accounts."

    when day_of_week(timestamp) == 0
      or day_of_week(timestamp) == 6
     and amount > 5000

    then review
         score   0.4
         reason  "High-value transaction on a weekend"
}

Complete Time Function Reference

Function	Return Value	Description
`hour_of_day(timestamp)`	`0` - `23`	Hour of the day (UTC)
`day_of_week(timestamp)`	`0` (Sun) - `6` (Sat)	Day of the week
`day_of_month(timestamp)`	`1` - `31`	Day of the month
`day_of_year(timestamp)`	`1` - `366`	Day of the year
`month_of_year(timestamp)`	`1` - `12`	Month number
`week_of_year(timestamp)`	`1` - `53`	ISO week number
`year(timestamp)`	e.g., `2026`	Full year

The `previous_transaction()` Function

This is a powerful function for checking whether specific patterns exist in a user’s recent transaction history. Signature:

previous_transaction(
    within: "<time_window>",
    match: {
        <field>: <value>,
        <field>: "$current.<field>"
    }
)

Parameters:

Parameter	Type	Description
`within`	Named argument, string	ISO 8601 duration for the lookback window.
`match`	Named argument, object	Key-value pairs that previous transactions must match.

Return Value: Boolean — true if at least one matching previous transaction exists within the time window, false otherwise. Description: Queries the transaction database for historical records that satisfy ALL of the match conditions within the specified within time window. This enables powerful sequential pattern detection: “block this transaction IF a previous transaction from the same source failed within the last hour.” How $current.<field> works inside match: The string "$current.source" is resolved at runtime to the source field of the current transaction being evaluated. This allows you to find previous transactions from the same user, account, or device. Example: Block After Previous Failure

rule BlockWhenPreviousTransactionFailed {
    description "Block when previous transaction failed for same source"

    when previous_transaction(
        within: "PT1H",
        match: {
            status: "failed",
            source: "$current.source"
        }
    )
    and amount > 700000

    then block
         score   1.0
}

How it works internally: The engine builds a SQL query:

SELECT COUNT(*) FROM transactions
WHERE status = 'failed'
  AND source = '<current transaction source>'
  AND timestamp >= '<now - 1 hour>'
LIMIT 1

If the count is greater than 0, the condition evaluates to true.

​hour_of_day()

​day_of_week()

​Complete Time Function Reference

​The previous_transaction() Function

`hour_of_day()`

`day_of_week()`

Complete Time Function Reference

The `previous_transaction()` Function