For the complete documentation index, see llms.txt. This page is also available as Markdown.

Rule-based driver events

How the Rule-based driver events table turns your alert rules into driving violation records, and how to query it.

The Rule-based driver events transformation records driving violations as individual event records, evaluated against the alert rules configured on your account. Each row in processed_common_data.rule_based_driver_events represents one violation: which rule detected it, what type it was, when and where it occurred, and how fast the vehicle was moving at the time.

Unlike the trigger-based transformation it replaces, this one runs on a fixed schedule. A refresh function re-evaluates a window of recent data every 15 minutes, so a new row can lag up to 15 minutes behind the event on the device.

  • Thresholds for speeding and idling come from your own alert rules, not from platform-wide defaults. Two devices can produce different events from identical driving if different rules apply to them.

  • Repeated hardware events of the same type from the same device within 10 seconds are combined into a single row, since a device can send multiple signals for one incident.

  • Accelerometer-based events are ignored while the vehicle is moving below 3 km/h. This avoids flagging vibration from loading or parking as a violation.

  • All timestamps are stored in UTC.

Output table: processed_common_data.rule_based_driver_events

Each row represents one detected violation. The table is keyed on device_id, device_time, rule_id, and hw_event_id.

Several columns are denormalized copies of values held elsewhere, so the most common dashboard queries need no joins at all: object_label comes from the object record, and speed_limit, event_comment1, and event_comment2 come from the rule that produced the event.

Field
Type
Description

device_id

integer

Device identifier.

object_id

integer

Object (vehicle or asset) identifier associated with the device at the time of the event.

object_label

text

Human-readable object name. Already denormalized into this table, so no join to raw_business_data.objects is needed.

device_time

timestamp

Event timestamp, in UTC.

rule_id

integer

The alert rule that produced the event. References raw_business_data.rules. Set to 0 for rpm_exceeded events, which are not rule-driven. See How rules shape the output.

event_type

text

Violation category. One of four values. See Violation types below.

hw_event_id

integer

Hardware event code for accelerometer and sensor-detected violations. 0 for speedup and idling_soft, which are derived rather than reported by the device.

event_comment1

text

Free-text label copied from the rule. Set when the rule was configured, and useful for grouping events by your own categories. Null for rpm_exceeded.

event_comment2

text

Second free-text label copied from the rule. Null for rpm_exceeded.

speed_limit

integer

The threshold configured on the rule, denormalized from raw_business_data.rules. For speedup rules this is the speed limit in km/h; for idling_soft rules it is the idle tolerance in minutes.

speed_kmh

numeric

Vehicle speed at the moment of the event, in km/h.

duration_sec

integer

Length of the violation in seconds, for event types that span a period of time rather than occurring instantaneously.

zone_id

integer

Geofence in which the event occurred, when the rule is scoped to specific zones. Null when the rule has no zones attached, and also when the rule is configured to fire outside its zones. See Zone scoping.

zone_label

text

Human-readable geofence name, denormalized alongside zone_id.

latitude

double precision

Latitude in degrees.

longitude

double precision

Longitude in degrees.

extra_value

numeric

Context-dependent measurement, set for event types that record a reading other than speed. For rpm_exceeded events, the RPM reading that triggered the event.

created_at

timestamp

When the row was written by the refresh function. Later than device_time by up to the length of one refresh cycle.

Violation types

The table below lists every violation type the transformation records, the exact event_type value stored for it, and where its threshold comes from. Use the event_type column value directly when filtering or grouping queries.

event_type value
What it means
hw_event_id
Threshold

speedup

Vehicle exceeded the speed limit set on the rule

0

Per rule, in km/h

harsh_driving

Accelerometer or hardware event reported by the device: harsh acceleration, braking, turns, lane changes, and seatbelt violations

900, 931, 987–991, 996

Detected by the device. Ignored below 3 km/h

idling_soft

Vehicle stationary with ignition on for longer than the rule allows

0

Per rule, in minutes

rpm_exceeded

Engine RPM above the platform threshold

9002

Fixed at 5,000 RPM

The examples below show common query patterns. The basic query returns recent violations ordered by device and time. The second adds the rule definition behind each event. The third filters to hardware-detected harsh driving only.

Use a LEFT JOIN rather than an inner join. rpm_exceeded events carry rule_id = 0 and have no matching row in raw_business_data.rules, so an inner join silently drops them.

Filtering on a single event_type value replaces the long IN list the previous table required, since all accelerometer and hardware violations now share one category. Split them apart with hw_event_id when you need the individual manoeuvre.

How rules shape the output

Rows in this table are not produced by platform-wide detection logic. With the exception of rpm_exceeded, every event is the result of an alert rule configured on your account, and the rule determines both the threshold and the scope.

1

The rule sets the threshold

Each rule stores its threshold in raw_business_data.rules.maximum: a speed in km/h for speedup rules, a duration in minutes for idling_soft rules. The transformation copies that value into speed_limit on every row it writes, so you can see what the vehicle was measured against without joining back to the rule.

2

The rule sets the scope

A rule applies to the objects linked to it through rules2objects, and optionally to the geofences linked through rules2zones. A device outside a rule's object list produces no events for that rule, however it is driven.

3

The rule supplies its own labels

event_comment1 and event_comment2 are free-text fields filled in when the rule is configured. They are copied onto each event so dashboards can display your own terminology without a join.

4

The refresh function evaluates the window

Every 15 minutes, refresh_rule_based_driver_events re-examines a 40-minute window of recent data and writes any qualifying events. The window is deliberately longer than the interval, so records that reach the platform late are still picked up on a later pass.

5

RPM is the exception

rpm_exceeded events are not rule-driven. They use a fixed 5,000 RPM platform threshold, carry rule_id = 0, and have no event_comment1 or event_comment2 values.

Zone scoping

When a rule has geofences attached through rules2zones, those zones decide both whether an event is recorded and whether zone_id is populated. Zone geometry is read from processed_common_data.zones_geom, materialized from raw_business_data.zones.

Rule configuration
Events recorded
zone_id value

No zones attached

Everywhere

Null

Zones attached, zone_inverted = false

Only inside the zones

The zone the event occurred in

Zones attached, zone_inverted = true

Only outside the zones

Null

Fixed platform constants

These values are the same for every account and are not configurable through a rule. Rule-driven thresholds are covered in How rules shape the output.

Constant
Value
Description

Minimum speed for accelerometer events

3 km/h

Accelerometer-based violations below this speed are ignored, to avoid flagging vibration while parked or loading.

RPM threshold

5,000 RPM

Engine RPM must exceed this value for an rpm_exceeded event to be recorded.

Hardware deduplication window

10 seconds

Repeated hardware events of the same type from the same device within this window are merged into one.

Refresh interval

15 minutes

How often the refresh function runs.

Refresh lookback

40 minutes

How far back each run re-examines data, so late-arriving records are not missed.

Customizing the transformation

For speedup and idling_soft, customization does not require a workflow at all. Both thresholds are read from the alert rule, so changing the rule changes what the transformation records from the next refresh onward. The same applies to scope: adjust the objects or geofences attached to the rule to change which vehicles and areas produce events.

If your operational scenario needs different fixed thresholds, contact [email protected] to request the corresponding workflow template. Once you have it, load it into Transformation Builder, adjust the relevant values, and schedule the modified workflow as a custom transformation.

Next steps

Last updated

Was this helpful?