Free cookie consent management tool by TermsFeed

a!queryRecordByIdentifier() Function

Function

a!queryRecordByIdentifier( recordType, identifier, fields, relatedRecordData )

Executes a query on a given record identifier and returns the record data.

a!queryRecordByIdentifier() and a!queryRecordType() are designed to be used in specific situations, and one is often a better choice than the other. Read more about choosing the right query function.

See also: Query Recipes, a!queryRecordType()

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.

identifier

Any Type

The identifier of the record to query. This is typically the primary key field.

fields

Any Type

Fields to be retrieved for the query. Use a list of record field or related record field references defined with the recordType! domain. When this parameter is null, all record fields from the specified record type are returned.

relatedRecordData

List of RelatedRecordData

When selecting one-to-many related record data, use a!relatedRecordData() to filter, sort, and limit the related record sets.

Returns

Record Type

Usage considerations

a!queryRecordByIdentifier() versus a!queryRecordType()

In most cases, you'll use a!queryRecordType() because it lets you select or aggregate multiple records and then filter those records to the exact set a user needs. This lets you build data-dense interfaces to showcase your business data and let users take action on it.

a!queryRecordByIdentifier() is suited for situations involving a single record, especially one with a large amount of related record data. Examples of these cases include populating a record view, passing a record and its related data into a related action, or moving a record through a process model.

  a!queryRecordByIdentifier() a!queryRecordType()
Number of base records Just one More than one
Number of related records per relationship Up to 100 Up to 10
Batching Automatic Configured with a!pagingInfo()
Query editor support No Yes

Note:  a!queryRecordByIdentifier() should not be used in a loop. If you need to query more than one base record or more than 100 related records, the related record type should be queried separately.

Using the fields parameter

By default, this function will return the fields from the base record type. If you also want to return related record fields, you can reference the fields or the relationship in the fields parameter.

To return… Use… Example fields value
A record field The recordType! domain to reference a record field. recordType!Case.fields.description
All record fields No reference. If you don't include the fields parameters, the function will return all record fields. N/A
A related record field The recordType! domain to reference a relationship and related record field. recordType!Customer.relationships.cases.fields.status
All related record fields from a relationship The recordType! domain to reference a relationship. recordType!Customer.relationships.cases

If you are querying a one-to-many relationship, a maximum of 100 related records will be returned. For example, when querying customers and their related support cases, the query will return up to 100 related support cases for the customer.

Using the relatedRecordData parameter

The relatedRecordData parameter allows you to filter, sort, and limit related record data from a one-to-many relationship using the a!relatedRecordData() function.

For example, let's say you're querying the Customer record type and you only want to return the last three cases associated with each customer. Since a customer can have many cases, by default, the query will return up to 100 cases related to each customer. In the relatedRecordData parameter, you could use the a!relatedRecordData() function to limit the result to three and sort the cases so the most recent appears first.

1
2
3
4
5
6
7
8
9
10
11
12
a!queryRecordByIdentifier(
  recordType: recordType!Customer,
  identifier: ri!id,
  relatedRecordData: a!relatedRecordData(
    relationship: recordType!Customer.relationships.case,
    limit: 3,
    sort: a!sortInfo(
      field: recordType!Customer.relationships.case.fields.entryDate,
      ascending: true
    )
  )
)

When applying a filter or sort to a!relatedRecordData(), your record field or related record field reference must start from the related record type specified in the relationship parameter. See additional usage considerations for using the a!relatedRecordData() function.

The a!aggregationFields() function is not supported with a!queryRecordByIdentifier().

If you need to aggregate related record data, use a!queryRecordType() instead.

Examples

See Query Recipes for examples of queries using a!queryRecordByIdentifier().

Feature compatibility

The table below lists this function's compatibility with various features in Appian.
Feature Compatibility Note
Portals Partially compatible

Can be used with Appian Portals to query synced record types.

Offline Mobile Partially compatible

Can be used with offline mobile if it is loaded at the top of the form.

Sync-Time Custom Record Fields Incompatible
Real-Time Custom Record Fields Incompatible

Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.

Process Reports Incompatible

Cannot be used to configure a process report.

Process Events Incompatible

Cannot be used to configure a process event node, such as a start event or timer event.

Feedback