Skip to main content
The zone_dwell_reader data action reads zone dwell events from the local RESDB SQLite database. It executes custom SELECT queries and returns matching records for downstream actions to process.

​
What it does

The zone dwell reader:
  1. Accepts custom SELECT queries via feature_variables.select_query
  2. Validates query safety to prevent write operations (INSERT, UPDATE, DELETE)
  3. Executes the query against the zone_dwell_events table
  4. Parses JSON columns like attachments, detection_result, and extra_info
  5. Calculates ongoing duration for records without exit times
  6. Returns all matching records in a single response

​
Requirements

RequirementDescription
select_queryA valid SELECT query in feature_variables. Required.
RESDB databaseThe local SQLite database must be initialized

​
Configuration

Configure the action through feature_variables on the action detail:
VariableTypeRequiredDescription
select_querystringYesFull SELECT query to execute
The query must start with SELECT. Any write operations (INSERT, UPDATE, DELETE, DROP, etc.) are blocked for security.

​
Available columns

The zone_dwell_events table contains these columns:
ColumnTypeDescription
idintegerAuto-incrementing primary key
timestampdatetimeWhen the event was recorded
camera_nametextName of the camera/stream
tracked_object_idtextStable ID for the tracked object
zone_nametextName of the detection zone
entry_timedatetimeWhen the object entered the zone
exit_timedatetimeWhen the object exited (NULL if ongoing)
duration_secondsrealTime spent in zone (NULL if ongoing)
is_readbooleanWhether the record has been processed
model_label_idintegerDetection model label ID
created_atdatetimeDatabase insertion timestamp
branch_idintegerAssociated branch ID
stream_idintegerAssociated stream ID
stream_zone_idintegerAssociated stream zone ID
is_violatedbooleanWhether a violation was created
attachmentstext (JSON)Array of ResultAttachment objects
detection_resulttext (JSON)Detection metadata
extra_infotext (JSON)Additional data (including violated_branch_rules)

​
Example queries

​
Query ongoing dwell events

Find people who have been in a zone for more than 60 seconds and haven’t left yet: Query: 
SELECT * FROM zone_dwell_events 
WHERE exit_time IS NULL 
AND (strftime('%s', 'now') - strftime('%s', entry_time)) > 60 
ORDER BY entry_time ASC 
LIMIT 50
Use case: Loitering detection - find people dwelling too long in restricted areas.

​
Query completed dwell events by duration

Find completed visits that lasted between 5 and 30 minutes: Query: 
SELECT * FROM zone_dwell_events 
WHERE exit_time IS NOT NULL 
AND duration_seconds BETWEEN 300 AND 1800 
ORDER BY duration_seconds DESC 
LIMIT 100
Use case: Customer engagement analysis - identify visitors who spent meaningful time in a zone.

​
Query events with attachments

Find recent events that have captured frames attached: Query: 
SELECT * FROM zone_dwell_events 
WHERE attachments IS NOT NULL 
AND timestamp > datetime('now', '-1 hour') 
ORDER BY timestamp DESC 
LIMIT 20
Use case: Review recent detections with visual evidence.

​
Query by zone and stream

Find events in a specific zone from a specific camera: Query: 
SELECT * FROM zone_dwell_events 
WHERE zone_name = 'Entry Area' 
AND stream_id = 42 
AND timestamp > datetime('now', '-24 hours') 
ORDER BY timestamp DESC
Use case: Zone-specific reporting for a particular camera.

​
Query unprocessed events

Find events that haven’t been used for violations yet: Query: 
SELECT * FROM zone_dwell_events 
WHERE is_violated = 0 
AND exit_time IS NOT NULL 
AND duration_seconds > 120 
ORDER BY timestamp ASC 
LIMIT 50
Use case: Batch processing of completed dwell events for violation creation.

​
Query events not violated by specific rule

Find events that haven’t been processed by a specific branch rule: Query: 
SELECT * FROM zone_dwell_events 
WHERE (extra_info IS NULL 
   OR extra_info NOT LIKE '%"branch-rule-uuid"%') 
AND duration_seconds > 60 
ORDER BY timestamp DESC 
LIMIT 100
Use case: Rule-specific violation processing to prevent duplicate violations.

​
Result format

​
Success with records

FieldValue
is_successtrue
feature_resultrecords_found
note”Found X zone dwell records”
extras.recordsArray of record objects
extras.total_recordsNumber of records returned
extras.query_usedThe executed query (truncated if long)
extras.columnsArray of column names

​
No records found

FieldValue
is_successtrue
feature_resultno_records_found
note”No zone dwell records found matching criteria”
extras.recordsEmpty array
extras.total_records0

​
Record structure

Each record in extras.records contains:
FieldDescription
All database columnsOriginal column values
record_idCopy of id for convenience
is_ongoingtrue if exit_time is NULL
duration_secondsCalculated from entry_time to now if ongoing
attachmentsParsed JSON array (if present)
detection_resultParsed JSON object (if present)
extra_infoParsed JSON object (if present)

​
Possible errors

Error: no_query_providedWhat happened: The select_query feature variable was not set.How to fix: Add a select_query to the action’s feature_variables configuration.
Error: invalid_queryWhat happened: The query doesn’t start with SELECT or contains forbidden keywords.How to fix:
  • Ensure query starts with SELECT
  • Remove any INSERT, UPDATE, DELETE, DROP, or other write statements
  • Use only single statements (no semicolons for multiple statements)
Error: errorWhat happened: SQL execution failed due to syntax error or database issue.How to fix:
  • Verify SQL syntax is valid SQLite
  • Check column names exist in the table
  • Ensure database file is accessible

​
Workflow integration

The zone dwell reader is typically used as the first step in a violation workflow:
  1. zone_dwell_reader queries for events matching violation criteria
  2. zone_dwell_violation_snapshot annotates frames from the records
  3. create_violation creates violation records from the prepared attachments
The zone dwell reader returns all matching records in a single response. Downstream actions should iterate through extras.records to process each record.