Skip to main content
Version: Current

Execute Query

Description​

The Execute Query activity executes a raw SQL query against a connected database and returns the resulting records as an IbDataTable.

It is primarily intended for advanced data retrieval scenarios where you need to execute custom SELECT queries, such as queries involving joins, subqueries, aggregations, Common Table Expressions (CTEs), or other database-specific SQL constructs.

Prerequisites​

  • Create and test a database connection in the AI Command Center.
  • Ensure the database is reachable from the environment that runs the workflow.
  • Ensure the connection account has permission to read the tables or views referenced by the query.
  • Confirm the database object names and SQL syntax for the selected database engine.

Common Capabilities​

Process Data Support​

info

This activity supports dynamic configuration using variables from the Process Data drawer.

You can bind values from Agent Data, Workflow Data, Form Data, System Data, Enterprise Variables, and Activity Outputs.

Learn more → Using Process Data

Design-Time Configuration​

The following properties define how the activity connects to the database and executes the SQL query.

Connection Type​

Specifies the database engine (for example, SQL Server, Oracle, MySQL, PostgreSQL). Selecting the correct type ensures compatibility with the target database.

Connection Name​

Select a preconfigured database connection that matches Connection Type and points to the intended database. The connection defines the server, credentials, and security settings.

Query​

Specifies the raw SQL query to be executed.

The query must be valid for the selected database engine and should return a result set.

Use this property to define custom SELECT queries, including complex queries involving:

  • Joins
  • Subqueries
  • Aggregations and grouping
  • Common Table Expressions (CTEs)
  • Database-specific SQL functions and expressions
note

The Execute Query activity is intended for retrieving data. For custom INSERT, UPDATE, DELETE, or schema (DDL) statements that do not return rows, use Execute Non-Query. For visual table selection and pagination, use Select Records.

Timeout​

Specifies the maximum time (in seconds) that the activity will wait for the query to complete.

The default value is 600 seconds.

Outputs​

DataTable​

Returns an IbDataTable containing the result set produced by the SQL query.

Each row in the query result is represented as a row in the DataTable, with columns corresponding to the fields returned by the query.

If the query does not return any records, the DataTable will contain no rows.

Execution Control and Error Handling​

Wait All Incoming​

Execution Control

Controls how this activity behaves when multiple incoming execution paths converge.

Determines whether the activity executes when:

  • any incoming path completes, or
  • all relevant paths have completed before execution

Learn more → Execution Control

On Error​

Error Handling Strategy

Defines how the workflow behaves if this activity encounters a runtime error.

Supported strategies include Fault, Continue, Suspend, and Retry. Select Inherit to use the workflow-level policy.

Learn more → Error Handling

Example: Retrieve Pending Orders​

This example uses a SQL Server table named dbo.Orders with OrderId and Status columns.

  1. Add Execute Query, set Connection Type to SQL Server, and select the database connection.

  2. Set Query to the following SQL:

    SELECT OrderId, Status
    FROM dbo.Orders
    WHERE Status = 'Pending'
    ORDER BY OrderId ASC;

  3. Configure Timeout and On Error, then run the workflow.

  4. Pass the DataTable output to the next activity. Each returned row represents a pending order. If none match, the output contains no rows.

Adapt the object names and SQL syntax to the selected database engine. Select only the columns needed by the workflow. For large result sets, apply an appropriate filter or use Select Records with pagination.

note

Binding workflow data to Query does not by itself establish SQL parameterization. Avoid concatenating untrusted values into SQL. Use Execute Stored Procedure when the operation requires mapped input arguments.

Help improve this page