OutSystems Aggregates: Complete Visual Query Builder Tutorial

In Service Studio, open your screen in the Screen Editor. Right-click anywhere on the canvas → Fetch data from Database. A new Aggregate editor opens as a tab within the screen. Alternatively: in the Interface tab, expand your screen → right-click → Fetch data from Database. A third option: drag the entity directly from the Data tab onto the screen canvas. This auto-creates both the Aggregate and a List widget bound to it in one step. The Aggregate editor shows four tabs: Sources, Filters, Sorts, Groups.

In the Aggregate editor, the Sources tab is active by default. Drag the Employee entity from the Data tab (left panel or right panel) into the Sources area. OutSystems immediately queries the database and shows live preview rows in the bottom preview pane. The Aggregate is now named 'GetEmployees' (auto-named from the entity). You can rename it by clicking the name at the top. In the bottom column list, you can see all available columns from Employee. Unused columns appear grayed out — OutSystems will not fetch them unless you use them in the UI (this is the auto-optimization behavior).

In the Aggregate editor, scroll to the right edge of the column list → click the + icon (Add Attribute) or double-click an empty area. Name it 'FullName'. In the Expression field, write: `Employee.FirstName + " " + Employee.LastName` Click OK. The preview pane immediately shows the computed FullName column. Other expression examples: - `If(Employee.IsActive, "Active", "Inactive")` — conditional text - `IntegerToText(Employee.Id)` — type conversion - `DiffDays(Employee.HireDate, CurrDate())` — days since hire Calculated attributes are computed in the database query (not in application memory) when they use simple expressions.

1/* Calculated attribute expressions in Aggregate editor */
2
3/* Full name from two columns */
4Employee.FirstName + " " + Employee.LastName
5
6/* Status label from Boolean */
7If(Employee.IsActive, "Active", "Inactive")
8
9/* Days since hire */
10DiffDays(Employee.HireDate, CurrDate())
11
12/* Formatted hire date */
13FormatDate(Employee.HireDate, "MMM dd, yyyy")

Close the Aggregate editor tab to return to the Screen editor. In the Toolbox (left panel), drag a List widget onto the screen canvas. In the Properties panel → Source, click the Expression editor icon and select: `GetEmployees.List` Inside the List widget, drag an Expression widget from the Toolbox. Set its Value property to: `GetEmployees.List.Current.Employee.FirstName + " " + GetEmployees.List.Current.Employee.LastName` The List widget iterates over each record. Inside the list body, use `GetEmployees.List.Current.<Entity>.<Attribute>` syntax to access fields. Alternatively, drag a Table widget instead of List for a grid layout — bind Source to `GetEmployees.List` and OutSystems auto-generates column bindings.

In the Aggregate editor, click the Aggregate node (the name at the top). In the Properties panel → Max Records, enter 20. This limits the query to 20 rows — critical for performance (see outsystems-aggregate-performance). To access the total count of records (regardless of Max Records limit), use `GetEmployees.Count` in expressions or action flows. Note: Count returns the full dataset size, not the count of rows fetched. For pagination, use the Start Index property: set it to a screen variable (e.g., `StartIndex`) and increment by Max Records per page. Action flow to access data: Start → GetEmployees Aggregate → If GetEmployees.List.Empty → [True] Message 'No employees found' → [False] Assign EmployeeList = GetEmployees.List → End

1/* Properties on Aggregate node */
2Max Records: 20
3Start Index: StartIndexVar  /* Integer local variable, starts at 0 */
4
5/* Accessing Aggregate output in action flow */
6GetEmployees.List          /* RecordList of Employee */
7GetEmployees.List.Current  /* Current record in a For Each loop */
8GetEmployees.Count         /* Total rows in DB matching filters */
9GetEmployees.List.Empty    /* Boolean: True when no records returned */
10
11/* Pagination expression */
12StartIndex = StartIndex + MaxRecords  /* Move to next page */

After a user creates, updates, or deletes a record, you must refresh the Aggregate so the screen displays current data. OutSystems does not auto-refresh. In your Save button's Client Action flow: Start → CreateEmployee(NewEmployee) → Refresh Data (drag from Toolbox) → select GetEmployees → End The Refresh Data node re-executes the Aggregate query and updates the bound List widget automatically. For Server-side data changes (e.g., in a Server Action called from Client Action): Client Action → Server Action (CreateEmployee) → back in Client Action → Refresh Data (GetEmployees) Alternative: after a CreateEmployee call in a Server Action within the same Client Action flow, the Refresh Data node in the Client Action will re-query the updated data.