a!queryRecordType() Function

Executes a query on a given record type and returns the result.

Syntax

a!queryRecordType(recordType, fields, filters, pagingInfo, fetchTotalCount)

Parameters

Keyword Type Description

recordType

RecordType

A reference to a record type. You must reference the record type directly from the recordType! domain. For example, recordType!Case.

fields

Any Type

Fields to be retrieved for the query. This parameter accepts different values depending on the type of query to run. When performing a selection, the fields parameter should use a list of record field references defined with the recordType! domain. If performing an aggregation, use a!aggregationFields() to define the configuration for the aggregated fields.

filters

Any Type

A single, logical expression or a list of query filters can be provided to filter the results. Without a logical expression, a list of query filters will only return those records where all filters evaluate to true (AND comparisons). Queries also apply the default filters defined on the referenced record type.

pagingInfo

PagingInfo

The paging and sorting configurations to apply when retrieving the record data.

fetchTotalCount

Boolean

If set to true, runs a separate query that retrieves the total number of records in the totalCount parameter of the query result. In cases where you don't need the totalCount, skipping this additional query can improve performance. Can only be used with record types that source from a data store entity.

Types of Queries

There are two methods of returning data using a!queryRecordType:

  • A selection returns each record as a separate item in the response. Any field of the record type can returned by providing the field within a list in the fields parameter.
  • An aggregation groups fields by common values and also allows using a function to produce a calculated result. An aggregation requires using supporting functions a!aggregationFields, a!grouping, and a!measure to define the query.

Returns

The return type of a!queryRecordType will be a Map data type with the following parameters:

  • success (Boolean)
  • data (List of Record Maps or List of Maps)
  • startIndex (Integer)
  • batchSize (Integer)
  • sort (List of SortInfo)
  • totalCount (Integer)
  • identifiers (List of Integer or List of Text)
  • errorCode (Text)

This map will have the same named fields as a DataSubset (so that it can seamlessly be cast to that type when being passed around your application) with the addition of "success" and "errorCode" fields, like results from an Integration object, so app developers can build error-handling into their applications.

The type for the data parameter varies depending on the type of query:

  • When selecting data, the return type is a list of record map that matches the specified record type.
  • When aggregating data, the return type is a list of map where the keys of the map match the aliases of each grouping or measure.

You can refine the function's output by using dot notation (.) to access specific fields. To have the expression return just the queried data, add .data to the end of the a!queryRecordType() function. Then, to access the data contained in a particular field, add the field name with a record field reference: data[recordType!<record type name>.fields.<field name>]

Error codes

a!queryRecordType returns a query result even if a runtime error happened. In these cases the "success" field of the result would have a value of false and the "errorCode" field will return an Appian Error Code indicating what has happened. You can use these codes to decide what to do next in your application.

Error Code Description Usage
APNX-1-4205-038 The user does not have access to this record type or the underlying data source. This error code could be used to hide elements of an interface.
APNX-1-4205-039 This is a record type with sync enabled, and is currently unavailable due to a sync issue. This error code could be used as a condition on which to query the data source instead of waiting for the sync issue to be resolved.
APNX-1-4205-040 The record type's data source could not be reached, or the query limit for that source has been reached. While uncommon, for finicky data sources, this error code could be used to prevent an interface from breaking.

Notes

  • Service-backed and Salesforce-backed record types without data sync enabled are not supported.
  • The batchSize in your pagingInfo for a!queryRecordType cannot be larger than 5000, and cannot be -1.
  • If you don't specify a selection of fields, all fields are returned.
  • Multiple sortInfos is not yet available for process-backed record types.
  • If the record type isn't sorted by the identifier, a final identifier sort is added to ensure deterministic sorting when using a selection.
  • You must update the target record type after upgrading to 20.3 in order to use this query.

Examples

NOTE: These examples use the record type "Customer" for the purpose of illustration only. If you copy and paste the expression below into the Expression Rule Interface, it will not evaluate in your Test Rules interface. Use it as a reference only.

Selection of Customer Fields

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
a!queryRecordType(
  recordType: recordType!Customer,
  fields: {
    recordType!Customer.fields.Name,
    recordType!Customer.fields.LogoID,
    recordType!Customer.fields.Industry
  },
  filters: {
    a!queryFilter(
      field: recordType!Customer.fields.InactiveFlag,
      operator: "=",
      value: false
    )
  },
  pagingInfo: a!pagingInfo(
    startIndex: 1,
    batchSize: 5000,
    sort: {
      a!sortInfo(
        field: recordType!Customer.fields.UpdatedOn,
        ascending: false
      ),
      a!sortInfo(
        field: recordType!Customer.fields.Name,
        ascending: true
      )
    }
  ),
  fetchTotalCount: true
)

Aggregation of Customers by Type and Region

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
a!queryRecordType(
  recordType: recordType!Customer,
  fields: a!aggregationFields(
    groupings: {
      a!grouping(
        field: recordType!Customer.fields.type,
        alias: "type"
      ),
      a!grouping(
        field: recordType!Customer.fields.region,
        alias: "status"
      )
    },
    measures: {
      a!measure(
        field: recordType!Customer.fields.id,
        function: "COUNT",
        alias: "id_count"
      ),
      a!measure(
        field: recordType!Customer.fields.totalOrders,
        function: "SUM",
        alias: "orders_sum"
      )
    }
  ),
  filters: a!queryLogicalExpression(
    operator: "OR",
    filters: {
      a!queryFilter(
        field: recordType!Customer.fields.isActive,
        operator: "=",
        value: true
      ),
      a!queryFilter(
        field: recordType!Customer.fields.region,
        operator: "in",
        value: {"East", "Central", "West"}
      )
    }
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1,
    batchSize: 5000,
    sort: {
      a!sortInfo(
        field: "id_count",
        ascending: false
      ),
    }
  )
)

See Also

  • Record Type: Additional information on the data type accepted for the recordType value.
  • Query: Additional information on the data type accepted for the query value and how to create a type constructor for it including which fields are required/optional.
  • Query Recipes - A list of examples of how to use the Query object to meet common use cases.
  • DataSubset: Additional information on the structure of this data type.
  • Constructing Data Type Values: Additional information on creating the query value via a type constructor.
  • a!queryAggregationColumn() Function: Additional information on grouping Date and Date and Time fields by year and month.

Old versions

There are older versions of this function. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

Old Versions Reason for Update
a!queryRecordType_20r4

Replaced selection with fields, which now allows for both selection and aggregation of record data when querying a given record type.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Open in Github Built: Thu, Feb 23, 2023 (02:59:22 PM)

On This Page

FEEDBACK