Wait Row

Waits until a new row is inserted into a specified table in Microsoft SQL Server.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

• Connection Id - The unique identifier of the database connection to use (optional if credentials provided directly).
• Table Name - Name of the table to monitor for new rows.
• Sort By - Column name to sort by for detecting new rows. Should be an auto-increment ID, timestamp, or sequential column.

Options

• Poll Time (s) - Time interval in seconds between checks for new rows (default: 1.0 second).
• Credentials - SQL Server database credentials (optional). Use this if you want to monitor without a Connect node.

Output

• None - The node completes when a new row is detected in the specified table.

How It Works

The Wait Row node monitors a table for new rows being inserted. When executed, the node:

1. Retrieves the database connection (either from connection ID or creates new connection from credentials)
2. Validates the table name and sort column are provided
3. Queries the table for the highest value in the sort column (TOP 1 ORDER BY sort column DESC)
4. On first execution, records the initial maximum value
5. Continuously polls the database at the specified interval
6. Compares the current maximum value with the last recorded value
7. When a new row is detected (value increased), the node completes
8. Handles tables with no rows initially

Requirements

• Either: A valid connection ID from Connect node OR valid database credentials
• Valid table name (table must exist)
• Valid sort column that increases with new rows (ID, timestamp, sequence, etc.)
• Appropriate SELECT permission on the table
• Connection must remain open during monitoring

Error Handling

The node will return specific errors in the following cases:

• ErrInvalidArg - Table name or sort column is empty
• ErrNotFound - Connection ID not found
• ErrConnection - Cannot connect to SQL Server (when using credentials mode)
• ErrRuntime - Query execution failed, table doesn't exist, or connection closed during monitoring

Sort Column Selection

Auto-Increment ID (Best)

Table Name: dbo.Orders
Sort By: OrderID

Perfect for detecting new rows because:

• Always increases
• Never null
• Never duplicates
• Reflects insertion order

Timestamp/DateTime Column (Good)

Table Name: dbo.Logs
Sort By: CreatedDate

Good for detecting new rows:

• Usually increases
• Reflects creation time
• May have duplicates (if multiple inserts at same time)

Sequential Number (Good)

Table Name: dbo.Transactions
Sort By: SequenceNumber

Works well if:

• Numbers always increase
• No gaps allowed
• Single source of inserts

Avoid These Columns

• User-provided values (may not increase)
• Nullable columns
• Non-unique columns (without timestamp)
• Columns that can be updated

Usage Examples

Monitor Order Table

Connect
  ↓
Wait Row
  - Table Name: dbo.Orders
  - Sort By: OrderID
  - Poll Time: 2.0
  ↓
(triggered when new order inserted)
  ↓
Query (SELECT TOP 1 * FROM dbo.Orders ORDER BY OrderID DESC)
  ↓
Process New Order
  ↓
Disconnect

Monitor Log Table

Wait Row
  - Table Name: dbo.ApplicationLog
  - Sort By: LogTimestamp
  - Poll Time: 1.0
  ↓
(triggered when new log entry)
  ↓
Query (get latest log)
  ↓
Send Alert if Error

Continuous Processing Loop

Connect
  ↓
Loop (continuous):
  Wait Row
    - Table Name: dbo.Queue
    - Sort By: QueueID
    ↓
  Query (get latest queued item)
    ↓
  Process Item
    ↓
  Non Query (mark as processed)
    ↓
  (loop continues)
  ↓
Disconnect (on stop)

Common Use Cases

1. Queue Processing - Monitor queue tables for new tasks to process
2. Event Triggering - Trigger automation when new events are logged
3. Order Processing - Process new orders as they arrive
4. Data Integration - Detect when external systems add data
5. Log Monitoring - Monitor application or system logs for new entries
6. Real-Time Processing - Process data as soon as it's inserted
7. Change Data Capture - Detect and react to data changes
8. Message Queue - Implement database-based message queuing

Tips for Effective Use

• Choose Right Sort Column - Use auto-increment ID or timestamp columns
• Table Must Exist - Table should exist and have at least one column before monitoring
• Handle Empty Tables - The node handles tables with no initial rows
• Poll Interval - Adjust based on expected insert frequency
• Connection Stability - Use credentials mode for long-running monitors
• Process Latest Row - Query for the newest row after trigger
• Continuous Monitoring - Combine with loop for continuous processing
• Mark Processed - Update rows after processing to avoid reprocessing

Polling Behavior

How Polling Works

1. Initial Check - Gets maximum value from sort column
2. Wait Period - Sleeps for Poll Time seconds
3. Subsequent Check - Gets maximum value again
4. Compare - If value increased (new row), triggers; otherwise continues
5. Repeat - Steps 2-4 repeat until new row detected

SQL Query Executed

SELECT TOP 1 {{sortColumn}}
FROM {{tableName}}
ORDER BY {{sortColumn}} DESC

This query retrieves the highest value in the sort column, which indicates the most recent row.

Poll Time Recommendations

Fast Polling (0.5 - 1 second):

• Near real-time processing
• More database queries
• Higher resource usage
• Good for time-critical applications

Medium Polling (2 - 5 seconds):

• Balanced performance
• Acceptable latency
• Good for most applications

Slow Polling (10+ seconds):

• Lower resource usage
• Higher latency
• Good for background monitoring

Handling Empty Tables

If the table has no rows initially:

1. First poll returns no rows
2. Node marks as initialized
3. Continues polling
4. Triggers when first row is inserted

Getting the New Row Data

After Wait Row triggers, retrieve the new row:

-- Get the latest row
SELECT TOP 1 *
FROM {{tableName}}
ORDER BY {{sortColumn}} DESC

Or store the last value and query for rows greater than it:

// After trigger, store the value for next iteration
const lastValue = $item.lastSortValue;

// Query for new rows
// SELECT * FROM TableName WHERE SortColumn > {{lastValue}}

Advanced Examples

Queue Processing Pattern

Connect
  ↓
Loop (infinite):
  Wait Row
    - Table Name: dbo.TaskQueue
    - Sort By: TaskID
    ↓
  Query: SELECT TOP 1 * FROM dbo.TaskQueue
         WHERE Status = 'Pending'
         ORDER BY TaskID DESC
    ↓
  JavaScript (process task)
    ↓
  Non Query: UPDATE dbo.TaskQueue
             SET Status = 'Completed',
                 ProcessedDate = GETDATE()
             WHERE TaskID = {{taskId}}
    ↓
  (loop continues)
  ↓
Disconnect

Event-Driven Automation

Wait Row
  - Table Name: dbo.Events
  - Sort By: EventTimestamp
  ↓
Query (get latest event)
  ↓
JavaScript (check event type)
  ↓
Switch (based on event type):
  Case 'OrderCreated': Process Order
  Case 'PaymentReceived': Process Payment
  Case 'ErrorOccurred': Send Alert

Multi-Table Monitoring

Parallel:
  Branch 1: Wait Row (Orders table)
  Branch 2: Wait Row (Customers table)
  Branch 3: Wait Row (Products table)
  ↓
(First to trigger continues)
  ↓
Process the table that triggered

Batch Processing with Wait

Connect
  ↓
Loop:
  Wait Row (wait for new data)
    ↓
  JavaScript (start collecting batch)
    ↓
  Wait (5 seconds - collect more rows)
    ↓
  Query (get all new rows)
    ↓
  Process Batch
    ↓
  Non Query (mark batch as processed)
  ↓
Disconnect

Real-Time Analytics

Wait Row
  - Table Name: dbo.SalesTransactions
  - Sort By: TransactionID
  ↓
Query (get latest transaction)
  ↓
JavaScript (update running totals)
  ↓
Non Query (INSERT INTO DailySummary)
  ↓
Send Dashboard Update

Change Data Capture

Wait Row
  - Table Name: dbo.Customers
  - Sort By: LastModified
  ↓
Query: SELECT * FROM dbo.Customers
       WHERE LastModified = (SELECT MAX(LastModified) FROM dbo.Customers)
  ↓
JavaScript (compare with previous version)
  ↓
Non Query (INSERT INTO ChangeHistory)
  ↓
Trigger Downstream Processes

Message Queue Implementation

-- Producer (external system) inserts messages
INSERT INTO MessageQueue (MessageType, Payload, CreatedDate)
VALUES ('OrderNotification', '{{jsonData}}', GETDATE())

-- Consumer (automation)
Wait Row
  - Table Name: MessageQueue
  - Sort By: MessageID
  ↓
Query (get unprocessed messages)
  ↓
Loop (process each message):
  JavaScript (parse payload)
  Process Message
  Non Query (DELETE from MessageQueue WHERE MessageID = {{id}})

Common Errors and Solutions

Table Name Cannot Be Empty

Error: ErrInvalidArg: Table name cannot be empty

Solutions:

• Provide table name in the Table Name field
• Ensure variable containing table name has value

Sort By Column Cannot Be Empty

Error: ErrInvalidArg: Sort By column cannot be empty

Solutions:

• Provide column name in the Sort By field
• Choose appropriate column (ID, timestamp, etc.)
• Verify column exists in table

Invalid Column Name

Error: Invalid column name in ORDER BY clause

Solutions:

• Verify sort column exists in table
• Check column name spelling
• Use sp_help 'TableName' to see column names

Table Does Not Exist

Error: Invalid object name 'TableName'

Solutions:

• Verify table exists before monitoring
• Check table name spelling
• Include schema: dbo.TableName

Connection Closed During Monitoring

Error: Connection closed or lost during monitoring

Solutions:

• Use credentials mode for dedicated connection
• Ensure connection timeout is sufficient
• Check network stability
• Implement reconnection logic

False Triggers

Problem: Triggers when rows are updated, not inserted

Solutions:

• Use auto-increment ID column instead of timestamp
• Ensure sort column only increases on INSERT
• Don't use columns that can be updated

Never Triggers

Problem: Node waits indefinitely even when rows inserted

Solutions:

• Verify sort column increases with new rows
• Check that new rows have higher values in sort column
• Test query manually: SELECT TOP 1 {{sortBy}} FROM {{table}} ORDER BY {{sortBy}} DESC
• Verify permissions on table
• Implement timeout logic

Performance Considerations

Database Load

• Each poll executes a TOP 1 query with ORDER BY
• Faster polling = more queries
• Ensure index exists on sort column
• Monitor database performance

Indexing

Create an index on the sort column for better performance:

CREATE INDEX IX_TableName_SortColumn
ON TableName (SortColumn DESC)

This dramatically improves the performance of SELECT TOP 1 ... ORDER BY SortColumn DESC queries.

Large Tables

For tables with millions of rows:

• Index on sort column is critical
• Consider slower poll times
• Monitor query execution time
• Use execution plan to verify index usage

Multiple Monitors

• Multiple Wait Row nodes increase database load
• Each executes queries independently
• Use appropriate poll intervals
• Consider consolidating into single monitor with branches

Integration Patterns

Trigger-Based Workflow

External System → INSERT into Table
  ↓
Wait Row (detects insert)
  ↓
Query (get new data)
  ↓
Transform Data
  ↓
Send to API / Export / Process
  ↓
Mark as Processed

Real-Time Sync

Source Database: INSERT into Orders
  ↓
Wait Row (Orders)
  ↓
Query (get new order)
  ↓
HTTP Request (send to external system)
  ↓
Non Query (update sync status)

Audit Trail Monitoring

Wait Row (AuditLog, by LogID)
  ↓
Query (get latest audit entry)
  ↓
JavaScript (check for security events)
  ↓
If security event: Send Alert

Troubleshooting

Test Sort Column

-- Verify sort column increases with new rows
SELECT TOP 10
  {{sortColumn}},
  *
FROM {{tableName}}
ORDER BY {{sortColumn}} DESC

Monitor Insertion Activity

-- Check recent insertions
SELECT
  {{sortColumn}},
  COUNT(*) as InsertCount,
  DATEADD(minute, -5, GETDATE()) as Since
FROM {{tableName}}
WHERE {{sortColumn}} > (
  SELECT MAX({{sortColumn}})
  FROM {{tableName}}
  WHERE CreatedDate < DATEADD(minute, -5, GETDATE())
)
GROUP BY {{sortColumn}}

Verify Permissions

-- Check SELECT permission
SELECT TOP 1 * FROM {{tableName}}
-- If this fails, you don't have permission

Check for Gaps

-- Verify no gaps in sequence (for ID columns)
SELECT
  {{sortColumn}},
  LEAD({{sortColumn}}) OVER (ORDER BY {{sortColumn}}) as NextValue,
  LEAD({{sortColumn}}) OVER (ORDER BY {{sortColumn}}) - {{sortColumn}} as Gap
FROM {{tableName}}
WHERE LEAD({{sortColumn}}) OVER (ORDER BY {{sortColumn}}) - {{sortColumn}} > 1

Best Practices

Choose Optimal Sort Column

Best Choices:

1. Identity column (IDENTITY)
2. Sequence column (SEQUENCE)
3. TIMESTAMP/ROWVERSION (binary increasing)
4. DateTime with DEFAULT GETDATE()

Avoid:

• User-entered values
• Updateable columns
• Nullable columns

Process and Mark Pattern

Wait Row (detects new row)
  ↓
Start Transaction
  ↓
Query (SELECT with UPDLOCK to lock row)
  ↓
Process Data
  ↓
Non Query (UPDATE set Processed = 1)
  ↓
Commit Transaction

This prevents duplicate processing in multi-instance scenarios.

Implement Timeout

Start Timer
  ↓
Parallel:
  Wait Row
  Wait (timeout)
  ↓
First to complete triggers
  ↓
Handle result or timeout

Continuous Processing

WHILE automation is running:
  Wait Row
  Process
  Mark as Processed
  Continue (loop back to Wait Row)

See Also

• Wait Table - Wait for new tables
• Wait Column - Wait for new columns
• Connect - Establish database connections
• Query - Execute SELECT queries
• Non Query - Execute UPDATE to mark processed