Define Simple Queries

The Simple Query element allows you to query the Entities of your eSpace. Simple Queries are design to be easy to use and highly performant, so they only provide a subset of the most used SQL primitives.

Simple Query Interface

Simple queries are black-boxes, meaning that they can only have access to data that is sent through input parameters, and other logic can only access what they return through the output parameter.

As such, a simple query can have:

- Input parameters: The only way to send data that can be used inside the simple query. Input parameters are optional. Learn more about Simple Query Parameters;
- Output parameter: In the OutSystems Platform, simple queries always have two output parameters, even when the query executed did not return any results:
- - List: The record list returned by the query. If the query did not return any results, this list is empty.
  - Count:The number of records returned by the query without considering the Max Records limitation specified in the simple query properties.

Execute an Advanced Query

To execute a simple query use the following steps:

1. Inside an action, drag the simple query from the toolbox on the left to the middle of the action flow;
2. Double-click the simple query to start editing it;
3. Define its input parameters, the entities and the conditions;
4. Test your query by clicking the Test button;
5. If you defined any input parameter, you need to specify the arguments to send: click the simple query, and in the properties on your right hand side specify the arguments to send.

What you Should Know

The OutSystems Platform starts a transaction when the web request arrives to the server, and commits the transaction before sending the reply to the user. If an exception is left uncaught, the transaction is rolled back to ensure your data is always consistent. This means that your advanced queries run inside this transaction and their changes are rolled back if something goes wrong;

Re-executing a Query

There are scenarios in which you might need to execute the same query twice. For example fetching the data in the Preparation, before the screen loads, and then execute the same logic after the end-user has executed an action. In such situations you can place your query in the Preparation of the Web Screen and use the Refresh Query tool on the flow of the screen action where you need to re-execute the query.

Query Time-out

To ensure the scalability of your infrastructure, queries are only allowed to run for a specified time: if the query does not return results within that time frame, the query is aborted ensuring your database performance is not compromised, an exception is thrown and the error is logged in Service Center.

By default, the query time-out is 30 seconds, but you can adjust this value to your needs as follows:

- Globally change the time-out for all queries: in the Platform Server Configuration Tool, change the Default query timeout parameter at the Database tab. If you don't have access to the Configuration Tool, ask your OutSystems Platform administrator.
- Change the time-out for a specific query: define the Timeout in Seconds property with the suitable value.

Due to limitations of the database connector used in the .Net version of the Agile Platform, queries executed over Oracle databases don't have a timeout, even if one is specified. In these scenarios you should ensure that your queries are carefully designed, to avoid deteriorating the performance of the database server.

Improving Runtime Performance

To improve the runtime performance of your Simple Queries, you can use cache, to avoid fetching twice the same data from the database. To do so, simply set a value in the Cache in Minutes property of the advanced query.

Learn more about caching contents.