DB Query Node: Reading Live Data from Your Systems During a Process

What it is

The DB Query node lets a workflow pause at a specific step, retrieve live records from a connected database, and make those records available as a variable for all subsequent steps. Instead of working only with data the requester typed into a form, your workflow can look up current information — current contract status, the requester's active budget, open purchase orders, employee records — and use that information to route decisions, populate email notifications, or feed into an AI analysis step.

The node supports two data sources: the app database (used by internal low-code apps built in Applications) and the Workflow DB (the workflow engine's own operational database). Once a query runs, its results are stored in a named variable you choose — for example, {{db_rows}} — and every downstream node can read the data.

For advanced scenarios, an optional Reactive Triggers feature installs a change listener on the source table. When a row is inserted, updated, or deleted in that table, the listener instantly notifies the workflow engine so downstream nodes can react without waiting for any polling interval.

Why it's useful / Key benefits

• Decisions based on real data, not just form inputs. Before routing an approval, the workflow can look up whether the requester has remaining budget, whether a vendor is on the approved list, or whether a contract is still active — using live database records, not stale snapshots.
• Eliminate manual lookups. Processes that used to require an approver to open another system, look up a record, then return to approve are now fully automated. The lookup happens inside the workflow.
• Dynamic routing powered by live data. Combine a DB Query node with a Condition node to branch automatically: if the retrieved record shows "status = approved," take one path; if "status = pending review," take another — all without human intervention.
• Feeds downstream AI analysis. The result set from a DB Query node can be passed directly to an AI Agent node, which can reason over the records and return a structured decision.
• Instant reaction to data changes (with Reactive Triggers). The Reactive Triggers option means workflows can start reacting the moment a row changes in your source system — approvals triggered by a database INSERT, tasks cancelled by a DELETE — with no scheduled polling delay.
• Named output for clean downstream references. You choose the variable name (e.g., db_rows, active_contracts) so subsequent nodes use a readable, meaningful tag like {{active_contracts}} rather than a cryptic identifier.

Before you start

• The DB Query node is available to all workflow designers. The Reactive Triggers feature on the Triggers tab requires Administrator access to configure (it installs a database-level listener on the source table).
• You must know which database to query (App Database or Workflow DB) and have at least basic familiarity with SQL SELECT queries.
• The Max Rows cap defaults to 1000 and can be set up to 10,000. Very large result sets can impact performance; design queries with appropriate WHERE clauses and LIMIT values.
• Required permission: Manage Workflows.

Where to find it: In the Visual Designer's Elements panel, scroll to the LOGIC tab. Drag the DB Query node onto the canvas.

How to use it — step by step

Step 1 — Place the node

1. Open a workflow in the Visual Designer.
2. In the Elements panel on the left, click the LOGIC tab.
3. Drag the DB Query node onto the canvas at the point where you want the data lookup to happen. Place it before any node that will use the retrieved data.
4. Connect it to the preceding node and to the node that should receive the query results.
5. Double-click the DB Query node to open the DB Query Node configuration dialog.

Step 2 — Configure the query (Query tab)

The Query tab is shown first.

6. Name (optional): Enter a short display name for this node, such as "Load Active Contracts" or "Check Budget Balance." This name appears on the canvas node label and in version history.

7. Description (optional): Briefly describe what the query retrieves, for example "Returns all open purchase orders for the requester's department." This helps colleagues maintain the workflow.

8. Datasource: Select the database to query.

   • Applications Database — the app database used by internal apps built in Applications (this is the on-screen dropdown label). Use this to look up application data.
   • Workflow DB — the workflow engine's own operational data (instances, tasks, actions). Use this for workflow-introspection scenarios.

   Reactive Triggers (see Step 3) are only available for the Applications Database datasource (the app database).

9. SQL Query: Type your SELECT statement in the code area. The field accepts standard SQL. Examples:

   • SELECT * FROM public.purchase_orders WHERE status = 'pending' LIMIT 100
   • SELECT budget_remaining FROM public.budgets WHERE department = '{{form_department}}'
   • SELECT id, vendor_name, status FROM public.vendors WHERE approved = true ORDER BY vendor_name

   Using workflow variables in queries: You can embed merge tags from upstream nodes directly in the SQL, for example WHERE employee_id = '{{form_employee_id}}'. The platform substitutes the value at runtime before executing the query. This is powerful but use it carefully — only with trusted, validated input.

10. Output Variable Name: Enter the name you want to use to reference the results in downstream nodes. Default is db_rows. Choose a name that makes the data self-explanatory — for example, active_contracts, budget_info, or pending_orders.

    • The help text below the field shows the exact merge tag that will be generated, e.g., {{db_rows}} or {{active_contracts}}.

11. Max Rows: Set the maximum number of rows to return. Default 1000, maximum 10000. Set a lower value if you know the result set is small to improve performance. Use LIMIT in the SQL as well for belt-and-braces control.

Step 3 — Configure reactive triggers (Triggers tab, optional, Administrator)

This step is optional and requires Administrator access.

12. Click the Triggers tab.
13. If you selected Workflow DB as the datasource, a notice appears that triggers are only available for the app database. Switch the datasource back to Applications Database on the Query tab if you need triggers.
14. Check the Enable Reactive Triggers checkbox to turn on change-listening for the source table. When enabled, the workflow engine installs a listener that fires downstream processing automatically whenever the specified events occur.
15. Under Trigger on:, check the event types you want to respond to:
    • INSERT — "Run downstream when a new row is added." Use this to start or advance a workflow when a new record is created in the source system.
    • UPDATE — "Re-run downstream when a row changes." Use this to re-evaluate routing when an existing record is modified.
    • DELETE — "Cancel downstream tasks for removed rows." Use this to clean up workflow tasks when the source record is deleted.
16. Key Column: Enter the column name that uniquely identifies each row in the source table (typically id). The listener uses this to match incoming events to the correct workflow instance.
    • The Table field below is auto-detected from the FROM clause in your SQL query and shown for confirmation.

Step 4 — Save and test

17. Click Save in the dialog footer. The dialog closes. The DB Query node on the canvas shows your chosen name and a database icon.
18. Save the full workflow with Ctrl+S or the Save toolbar button.
19. To verify the node works, run a test instance of the workflow (see Running a Workflow) and inspect the workflow detail view to confirm the {{db_rows}} variable is populated with the expected rows.

Options & settings explained

Query tab

Triggers tab (Applications Database — app database — only)

Output variable structure

The output variable is an array of row objects. Each object has one key per column returned by the SQL query. For example, if the query selects id, vendor_name, and status, the variable {{active_vendors}} contains:

[
  { "id": 1, "vendor_name": "Acme Corp", "status": "approved" },
  { "id": 2, "vendor_name": "Beta Ltd",  "status": "pending" }
]

Downstream nodes (Condition, AI Agent, Email body) can reference the full array or, where the platform supports it, individual fields using dot notation.

Tips & best practices

• Keep SQL queries narrow. Select only the columns you need — avoid SELECT * in production flows. Narrow queries are faster and the resulting variable is easier to work with downstream.
• Add a LIMIT clause in the SQL itself in addition to setting Max Rows. Two independent caps prevent accidentally large result sets.
• Use WHERE clauses with workflow variables to filter for the right record. Instead of returning 10,000 rows and filtering in a condition node, write WHERE employee_id = '{{form_employee_id}}' and return the single relevant record.
• Name the output variable for its content. {{active_contracts}} is more readable in downstream email bodies and conditions than the default {{db_rows}}.
• Place the DB Query node before any node that needs its data. Variables from nodes that run later in the graph are not available earlier in the graph.
• Only enable Reactive Triggers when you truly need real-time response. Each trigger installs a listener on the source table. For workflows that can tolerate running on a schedule or manual trigger, keep triggers off.
• Test with a LIMIT 1 query first. Confirm the query syntax and output variable structure before expanding to the full result set.
• Combine with an AI Agent node. Pass the DB Query result into an AI Agent node to get intelligent analysis of the retrieved data — for example, "summarize these purchase orders and flag any that exceed policy."

Frequently asked questions

Q: Can I update or delete records with a DB Query node? No. The DB Query node executes read-only SELECT queries. To modify data, use a custom integration or the Webhook node to call an external API that performs the write operation.

Q: What happens if the query returns no rows? The output variable is set to an empty array []. Downstream Condition nodes should handle this case — for example, branching to a "no data found" path when the array is empty (using the "is empty" operator on the variable).

Q: Can I use a merge tag inside the SQL WHERE clause? Yes. For example: SELECT * FROM budgets WHERE department = '{{form_department}}'. The platform substitutes the variable value before executing the query. Always validate and sanitize form inputs upstream to prevent unexpected query behavior.

Q: How many rows can I retrieve? The maximum is 10,000 rows. Set Max Rows on the Query tab and add a LIMIT clause in the SQL for double protection. Very large result sets are best handled by writing more targeted WHERE clauses rather than increasing the limit.

Q: What does "Reactive Triggers" do exactly? When enabled, the platform installs a lightweight notification mechanism on the source database table. Whenever a qualifying INSERT, UPDATE, or DELETE happens on that table, the platform is notified instantly and can re-run or advance the relevant workflow steps — without any scheduled polling. This means the workflow responds in seconds rather than minutes to changes in your source data.

Q: Can I have more than one DB Query node in the same workflow? Yes. Each node runs its own independent query against its own datasource and stores results in its own output variable. Name them distinctly so downstream nodes can reference the right dataset.

Q: My query runs but the output variable is empty. What should I check? Check: (1) The table and column names are correctly spelled and match your database schema exactly (they are case-sensitive in PostgreSQL). (2) The WHERE clause does not accidentally filter out all rows — try removing it temporarily to see if rows return. (3) The datasource selection (App Database vs Workflow DB) is correct. (4) Max Rows is not set to 0.