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()
| Keyword | Type | Description |
|---|---|---|
|
|
RecordType |
A reference to a record type. You must reference the record type directly from the |
|
|
Any Type |
The identifier of the record to query. This is typically the primary key field. |
|
|
Any Type |
Fields to be retrieved for the query. Use a list of record field or related record field references defined with the |
|
|
List of RelatedRecordData |
When selecting one-to-many related record data, use |
Record Type
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.
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.
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.
See Query Recipes for examples of queries using a!queryRecordByIdentifier().
| 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. |
