a!queryRecordByIdentifier_25r2() Function

Function

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

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

a!queryRecordByIdentifier_25r2() 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:

• Recipes for Querying Records
• a!queryRecordType()
• a!relatedRecordData()

Parameters

Returns

Record Type

Usage considerations

a!queryRecordByIdentifier() versus a!queryRecordType()

Depending on the amount of data you need and whether you want to aggregate that data, you can use:

• a!queryRecordType() function to select or aggregate data from a record type. This function is great for building interfaces that show multiple records to users.

• a!queryRecordByIdentifier() function to return data for a specific record and any of its related record data. This function is a good choice when building summary views and related actions that update a single record. It can also be used in the process models for record actions where you need to act on new or updated record data after a Write Records node.

The table below outlines the key differences between these two functions:

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.

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_25r2(
  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.

Aggregating related record data

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

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

New version details

The a!queryRecordByIdentifier() function was evolved to reinforce query performance best practices.

The new version of the function includes the following behavior changes:

• Changed the fields parameter behavior so when the parameter is null or empty, only the primary key field from the base record type is returned. Likewise, only referencing a relationship will return the primary key fields from both the base and related record types.
• The relatedRecordData parameter to accept a limit of up to 250 related records.

Feature compatibility

Feedback