OutSystems Performance and Robustness: Entity Get Actions vs Aggregates?

This article approaches a question that is asked frequently, and usually by new developers of the OutSystems community:

“Is it better to use an Aggregate, or an Entity Get Action, in a query to the database, for a Single Result?”

This topic is important, because a wrong implementation can originate errors that impact user experience.

In a nutshell, I’ll approach the answer to this question in three steps:

1. Explaining the basics about Aggregates and Entity Action Get;
2. Their difference in Performance;
3. Aiming for Robustness to avoid errors.

1. Basics about Aggregate and Entity Action Get

These are two OutSystems objects used to query a database.

Illustration of an Entity Get Method (left side), and an Aggregate (right side).

Basic differences are the number of results obtained from queries, the possibility to join more queries, and their ways of usage:

• An Aggregate can return more than one result, while an Entity Get Method returns at maximum one result.
• An Aggregate allow to make joins between different Entities (tables), and filtering results. An Entity Get Method searches only by an identifier.
• An Entity Get Method can be used as a function inside other logic as calculations or expressions.

Illustration of an Entity (Product Table), with focus on one Entity Get Action (GetProduct).

There are more differences, but for the purpose of this article, this already gives a context to understand the next sections.

2. Difference in Performance

To talk about performance, we need to consider the same comparison method and conditions, to allow reach good conclusions. The conditions to consider in this comparison of performance are:

• Queries are applied to dynamic entities only (see my other article about Static vs Dynamic Entities performance);
• There is only a single result, to be fetched from the database;
• Query used in action and not used in a screen because OutSystems optimizes the query based on which entity attributes are used (*);
• There is only one source Entity to search and all attributes are returned;
• The aggregate has only one filter, correspondent to the record identifier, and no other filters or sorts are applied;

In the conditions described above, there is a little or no difference of performance, between using an Aggregate or an Entity Get Method.

(*) One important note: when using Aggregates in screens, OutSystems might optimize the query, to only retrieve attributes in use, reducing the amount of data in circulation. But when an aggregate is encapsulated in an action, the Platform will not optimize the query result when output is the full record.

Updated: “Screen” Aggregates (Reactive Web) are optimized the same way as “Action” Aggregates (Traditional Web) based on the attributes used.

An usual anti-pattern in development, is when Entity Get Actions are used as a function in expressions, and repeated multiple times by a “blind” copy/paste.

Tip: avoid multiple Entity Get Actions in the same context, since this reduces performance and maintainability. Instead consider an Aggregate.

Furthermore, another aspect to consider, is the usage of both Aggregates and Entity Get Actions, explained in the next section.

3. Aiming for Robustness

Addressing how to use both, is more interesting to enable robust applications. First we need to understand the impacts of using Entity Get Actions in certain scenarios, take this example (which happens more often, than we would like):

• A page contains an expression, using for its calculation, one Entity Attribute using the Entity Get Action.
• This Entity Get Action queries the database, using an identifier that no longer exists in the database (there could be many reasons).
• Because Entity Get Action query, does not find the correspondent record in the database, it returns an exception.
• Because this exception was not covered, the calculation of the screen expression fails, and the user sees an error.

Of course, this is an hypothetical scenario and contains certain ambiguity. But the point here, is to underline a fact: it’s important to use the Entity Get Action carefully (specially as a function). In these cases consider to use wrappers (*).

Example of an Entity Get Action wrapper (Product_GetNameById), covering possible exceptions.

These three tips increase robustness of your application, given this topic:

• Don’t assume that an identifier is provided to Entity Get Action (there could be a non-mandatory identifier field).
• Use an Entity Get Action to get a specific record in one Entity, an Aggregate to get more than one result and multiple Entities.
• Encapsulate Entity Get Actions to handle exceptions and avoid errors (read also this article that Justin James wrote).

(*) Another important note: when increasing robustness, we might slightly decrease performance, due to wrapping values and adding up memory usage. There is always a trade-off.

4. Conclusion

Aggregates and Entity Get Actions have roughly the same performance, in similar conditions. To increase robustness of the application, when possible encapsulate Entity Get Actions (used as functions) to cover exceptions (but trading-off on performance).

“What more?” you may ask? For additional content like this, take a look into my other articles. Please share, applause or send questions for more articles!