Skip to main content
Version: Current

Select Records

Description​

The Select Records activity retrieves records from a specified database table and returns the results as an IbDataTable.

It provides a simple, UI-based way to select columns, define filter conditions, sort records, and retrieve either all matching records, subject to an optional limit, or a single page of results without writing SQL queries.

tip

Use Select Records for retrieving data from a specific database table using UI-based configuration.

For advanced data retrieval involving joins, subqueries, aggregations, Common Table Expressions (CTEs), or other custom SQL, use the Execute Query activity.

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 selected table.
  • Identify the schema, table, and columns needed by the workflow.

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 retrieves records.

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.

Schema​

Specifies the database schema that contains the target table.

Table Name​

Specifies the database table from which records will be retrieved.

Columns​

Specifies the columns to retrieve from the selected database table.

Select only the columns required by the workflow to avoid retrieving unnecessary data.

Leave this empty to retrieve all columns from the table.

Filter​

Defines optional conditions used to determine which records are retrieved from the selected table.

Use the Filter Expression builder to configure filter conditions without writing SQL.

If no filter is specified, records are retrieved without applying filter conditions, subject to the configured pagination settings.

Sort Columns​

Specifies how the retrieved records should be sorted.

Enter one or more columns with an optional direction, separated by commas (for example, column1 ASC, column2 DESC).

For pagination, include a unique column in the sort order, such as OrderId ASC, or use it to break ties, such as Status ASC, OrderId ASC. Without a consistent, unique ordering, rows with equal sort values may appear on different pages between executions. Changes to the underlying data can also shift page contents.

Read All​

Controls how many matching records are returned.

  • When on, the activity returns all matching records, optionally limited by Max Records.
  • When off, the activity returns a single page of results using Page Size and Page Number.

Max Records​

Shown when Read All is on.

Specifies the maximum number of records to return.

Using an appropriate limit is recommended when working with large database tables to avoid retrieving unnecessary data and consuming excessive system resources.

Page Size​

Shown when Read All is off.

Specifies how many records to return on the selected page. Use a positive whole number sized for the amount of data the workflow can process at once. The final page may contain fewer records.

Page Number​

Shown when Read All is off.

Specifies which page to return. Page numbering is 1-based:

  • Page 1 returns the first Page Size rows.
  • Page 2 returns the next Page Size rows, and so on.
Page NumberPage SizeRows returned (conceptually)
15First 5 rows
25Rows 6–10
35Rows 11–15

If Page Number is missing or less than 1, it is treated as 1.

Timeout​

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

The default value is 600 seconds.

Outputs​

DataTable​

Returns an IbDataTable containing the records retrieved from the selected database table.

The returned DataTable can be passed directly to other activities that accept IbDataTable, or used for further processing within the workflow.

If no records match the configured selection criteria, the DataTable will contain no rows. In pagination mode, this also occurs when the requested page is beyond the available matching records. The output contains the selected page, rather than all matching records.

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 Orders in Pages​

Assume the selected table contains a unique OrderId column and a Status column.

  1. Add Select Records and select the database connection, Schema, and Table Name.
  2. Choose the Columns needed by the next activity, such as OrderId and Status.
  3. Use Filter to select orders whose Status equals Pending.
  4. Set Sort Columns to OrderId ASC.
  5. Turn Read All off, set Page Size to 5, and set Page Number to 1.
  6. Run the activity and process its DataTable output. It contains up to five matching orders.
  7. To retrieve the next page, execute the activity again with Page Number set to 2, keeping the filter, page size, and sort order unchanged.

Each execution retrieves one page. To process multiple pages in a workflow, bind Page Number to a workflow variable, start at 1, and increment it after processing each page. Stop when the returned DataTable contains no rows.

note

Avoid changing the filter or sort values of matching records while paging through them. For example, updating each processed order from Pending to Processed changes the matching set and can cause later page numbers to skip orders. Choose a retrieval approach that accounts for such changes.

To retrieve a limited set in one execution instead, turn Read All on and configure Max Records. Page Size and Page Number apply only when Read All is off.

Help improve this page