a!queryEntity() Function

Executes a query on a given data store entity and returns the result.


a!queryEntity( entity, query, fetchTotalCount )

  • entity (Data Store Entity): The Data Store Entity to query.
  • query (Query): The query definition of the report including grouping, aggregation, filtering, paging, and sorting configurations, created with a!query().
  • fetchTotalCount (Boolean): If set to false, avoids running the query that retrieves the total number of rows in the totalCount parameter of the resulting datasubset. In cases where you don't need the total count, skipping this query can improve the performance of a!queryEntity(). Default: false.




The DataSubset returned by this function is used to generate report grids or graphs based on record data.

The entity value should be given as a constant of type Data Store Entity. The query value must be entered using the a!query() system function.

The logicalExpression|filter|search field of the query object can only be set to a LogicalExpression or a QueryFilter type. Search types are not supported.

The expression will fail to evaluate and an error will occur if the entity reference is not provided, invalid, or null, the user does not have permission to view the entity, the query value is not provided, invalid, incomplete, or an inconsistent query object.

This function allows a Query object with an array of SortInfo data type.

If called multiple times in the same expression with the same parameters, only one query is made to the data store when the expression is evaluated and the result is reused for each identical call. This caching only applies within a single expression evaluation. Return values are not cached in separate expressions, or in separate evaluations of the same expression.

If fetchTotalCount is set to false and the batchSize parameter in a!pagingInfo is set to -1, the totalCount parameter is populated with the number of rows after the filters are applied. This is because all of the data is already being retrieved, so the value of totalCount is already known without an additional query. See the following table for more information.

Batch Size Fetch Total Count Scenario Description Value of totalCount
-1 Any value The user wants to get all the rows. We know the total size and return it to the user. Total number of rows*
0 or positive `true` The user only wants a subset of rows, but also wants to know the total number of rows after filters are applied. We run an extra query to get the total size. Total number of rows*
0 or positive `false` The user only wants a subset of rows, and didn't ask for the total number of rows after filters are applied. We don't know the total size. -1
*Total number of rows after filters are applied

See Also

Data Store Entity: Data store entities are named, typed storage units within a data store.

query: The query data type defines the grouping, aggregation, filtering, paging, and sorting configuration to be applied when querying data.

a!query(): A System Function that returns a Query object.

Querying Data From an RDBMS: An explanation of the differences between a!queryEntity and queryrecord().

Query Recipes: Examples of queries.

Using the Query Editor: Instructions on how to create a query using the query editor.

Open in Github

On This Page