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.

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	Compatible
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

Was this page helpful?