> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finwatch.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Time Functions

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:**

```go lines theme={null}
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:**

```go lines theme={null}
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:**

```go theme={null}
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**

```go lines theme={null}
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:

```sql theme={null}
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`.