Skip to main content

Line Crossing Events Reader

The Line Crossing Events Reader action retrieves stored visitor entry and exit records from the local database for processing, reporting, or uploading to external systems.

Overview​

When the Visitor Entry Counting action runs, it stores detailed records in the local database. The Line Crossing Events Reader allows you to:

  • Query those records with custom filters
  • Retrieve specific data for processing
  • Feed data into subsequent workflow actions

This action is a "data source" that pulls information from storage rather than analyzing video.

What It Does​

1. Executes Database Query​

The action runs a SQL SELECT query against the visitor_entries table. This table contains records created by the Visitor Entry Counting action.

2. Returns Records​

The matched records are returned and made available to subsequent actions in the workflow. This enables workflows like:

  • Read recent entries → Generate report
  • Read entries from last hour → Upload to cloud
  • Read entries matching criteria → Trigger alerts

Configuration​

ParameterTypeRequiredDescription
Select QueryTextYesSQL SELECT query to execute

Query Requirements​

  • The query must start with SELECT
  • Only SELECT statements are allowed (no INSERT, UPDATE, DELETE)
  • The query runs against the local database

Available Table: visitor_entries​

ColumnTypeDescription
idIntegerUnique record identifier
timestampDateTimeWhen the event occurred
entry_countIntegerNumber of entries (usually 1)
exit_countIntegerNumber of exits (usually 1)
stream_idIntegerWhich camera recorded this
branch_idIntegerWhich branch this belongs to
age_groupTextEstimated age category (if demographics enabled)
genderTextEstimated gender (if demographics enabled)
processedBooleanWhether this record has been uploaded

Example Queries​

Get the 10 most recent entries:

SELECT * FROM visitor_entries WHERE entry_count = 1 ORDER BY timestamp DESC LIMIT 10

Get unprocessed entries from today:

SELECT * FROM visitor_entries WHERE processed = false AND timestamp >= date('now', 'start of day')

Get all entries for a specific camera:

SELECT * FROM visitor_entries WHERE stream_id = 42 ORDER BY timestamp DESC

Get demographic summary:

SELECT age_group, gender, COUNT(*) as count FROM visitor_entries WHERE entry_count = 1 GROUP BY age_group, gender

Understanding Results​

ResultMeaningData Available
records_foundQuery returned dataRecords in action result extras
no_recordsQuery returned emptyNo matching data in database
query_errorQuery failedCheck query syntax

Common Use Cases​

Hourly Data Export​

  • Schedule: Run every hour
  • Query: Select unprocessed entries from the last hour
  • Next Action: Visitor Summary Uploader to send to cloud

Real-Time Dashboard​

  • Schedule: Run every few minutes
  • Query: Select entries from the last 15 minutes
  • Use: Display current traffic in external dashboard

End-of-Day Reporting​

  • Schedule: Run once at closing time
  • Query: Select all entries from today
  • Use: Generate daily traffic report

Demographic Analysis​

  • Schedule: Weekly or monthly
  • Query: Group by age and gender
  • Use: Marketing and merchandising insights

Troubleshooting​

Invalid Query Error​

  1. Check Query Start: Query must begin with SELECT (case-insensitive).

  2. Verify Syntax: Ensure SQL syntax is correct:

    • Check for missing commas
    • Verify column names are spelled correctly
    • Ensure table name is correct (visitor_entries)

  3. Test Query: If possible, test the query directly against the database to verify it works.

No Records Returned​

  1. Check Filters: Your WHERE clause may be too restrictive. Try removing conditions to see if any data exists.

  2. Verify Time Range: Timestamps are stored in UTC. Ensure your date/time comparisons account for time zones.

  3. Check Data Exists: Confirm that Visitor Entry Counting has been running and storing data.

  4. Processed Flag: If querying for processed = false, previous uploads may have marked records as processed.

Slow Query Performance​

  1. Add Limits: Always use LIMIT to restrict result size.

  2. Index Usage: Queries filtering on indexed columns (id, timestamp, stream_id) are faster.

  3. Simplify: Complex JOINs or subqueries may be slow on large datasets.

Security Errors​

  1. No Modifications: Only SELECT is allowed. Any attempt to INSERT, UPDATE, DELETE, or DROP will be rejected.

  2. Single Statement: Only one SQL statement can be executed per query.

Best Practices​

  1. Always Use Limits: Prevent accidentally loading millions of records by always including LIMIT in your queries.

  2. Filter by Time: Most use cases only need recent data. Filter by timestamp to reduce data volume.

  3. Mark Processed: When building upload workflows, update records as processed to avoid duplicate uploads.

  4. Specific Columns: Select only the columns you need rather than using SELECT * to improve performance.

  5. Test Queries: Before deploying workflows, test your queries to ensure they return expected results.

  • Visitor Entry Counting: The action that creates the records this reader queries
  • Visitor Summary Uploader: Often used after this reader to upload data to cloud
  • Zone Dwell Reader: Similar reader for zone dwell events