Help Centre › Building Processes
This article describes the RPA Database functionality to execute a SELECT query.
For a full list of available functions, please read DATABASE functions.
Description
The Run database query function executes a SELECT query against a database and returns the results as an array of dictionaries. Each dictionary represents a row, with column names as keys. You can use a named connection or provide inline connection details for legacy compatibility.
Setting it up
To use the Run database query function, follow these instructions:
{{popups:rpas/add:action=db-query}}
Once on a process map:
- Navigate to the process where you would like to add the Run database query function
- Click on the green button's drop-down (right side of the green button labelled "Process")
- On the menu that appears, click on the "+ Activity" item
- From here you can select the Run database query option
- Click "Add" once you are done
Input parameters
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
| Name | No | Text | - | The alias of a previously opened connection (from db-connect) |
| Query | Yes | Text | - | The SQL SELECT statement to execute |
| Params | No | Array | - | An array of values for parameterised queries (use %s or ? as placeholders) |
| Type | No | Select | - | Database type (legacy mode – use db-connect instead) |
| Host | No | Text | - | Database host (legacy mode) |
| Port | No | Number | - | Database port (legacy mode) |
| Database | No | Text | - | Database name (legacy mode) |
| Username | No | Text | - | Database username (legacy mode) |
| Variable | No | Text | query | Variable name to store the query results |
Output variables
| Variable | Type | Description |
|---|---|---|
| {query} | Array of dictionaries | The query results, where each dictionary represents a row with column names as keys |
Errors
| Error | Description |
|---|---|
| Connection failed | Unable to connect to the database (when using legacy inline connection) |
| Query error | The SQL query contains a syntax error or references invalid objects |
| Authentication failed | The username or password is incorrect (when using legacy inline connection) |
Tips
- Use parameterised queries with %s or ? placeholders to prevent SQL injection
- Use named connections (db-connect) for efficiency – legacy inline mode creates a new connection each time
- Add LIMIT to large result sets to avoid memory issues
- The results can be iterated with the "Each record in a list" loop action