a!queryRecordByIdentifier() Function

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.

Related recipes and functions:

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

Parameters

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

Returns

Record Type

Using the function

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. This function 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 following table outlines the key differences between these two functions:

Using the fields parameter

The fields parameter allows you to specify which record fields and related record fields are returned from the query. If you leave this parameter empty, only the primary key field from the base record type is returned.

As a best practice, only query the fields you need. Before creating a query, consider what data you actually need, since it can take longer to return large volumes of data or expensive fields, like real-time custom record fields or Extra Long Text fields.

To reference:

• A record field, use the recordType! domain.

  For example, recordType!Customer.fields.firstName returns the firstName field from the Customer record type.
  
  

• A related record field, use the recordType! domain to reference a relationship and select a related record field.

  For example, recordType!Customer.relationships.cases.fields.status is using the relationship on the Customer record type to select the status field from the Case record type.

If you must query all fields from a record type, you can use the a!selectionFields() function in the fields parameter. However, you should only use this function when it is absolutely necessary to return all fields.

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. By default, the query returns up to 100 cases related to each customer. In the relatedRecordData parameter, 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
13
14
15
16
a!queryRecordByIdentifier(
  recordType: recordType!Customer,
  identifier: ri!id,
  fields: {
    recordType!Customer.fields.fullName,
    recordType!Customer.relationships.case.fields.name
  },
  relatedRecordData: a!relatedRecordData(
    relationship: recordType!Customer.relationships.case,
    limit: 3,
    sort: a!sortInfo(
      field: recordType!Case.fields.entryDate,
      ascending: true
    )
  )
)

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

Aggregate related record data

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

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

Query composite key records

For record types with a composite primary key, pass a record map in the identifier parameter with values for all fields that make up the key.

For example, if the Part Supplier record type has a composite primary key of {partId, supplierId}, you can query a specific record by providing the partId and supplierId in a record map.

1
2
3
4
5
6
7
8
9
10
11
12
13
a!queryRecordByIdentifier(
  recordType: recordType!Part Supplier,
/* Record map providing the all key fields */
  identifier: recordType!Part Supplier(
    recordType!Part Supplier.fields.partId: 4,
    recordType!Part Supplier.fields.supplierId: 45
  ),
  fields: {
    recordType!Part Supplier.fields.partId,
    recordType!Part Supplier.fields.supplierId,
    recordType!Part Supplier.fields.quantity
  }
)

Using async loading for slow queries

For slower queries, consider using a!asyncVariable() to load the data asynchronously. This allows users to interact with the rest of the interface while waiting for the data to load. See Asynchronous Loading for more information.

Examples

The following examples show how to use a!queryRecordByIdentifier() to query fields from a single record.

These examples reference a record type from another environment. If you try to use these record type references in your environment, they return an error. Use these examples as a reference only.

See Recipes for Querying Records for more examples.

Return specific fields for a record

This a!queryRecordByIdentifier() example returns the first name, last name, and industry name for a customer from the AT Customer and AT Industry record types.

1
2
3
4
5
6
7
8
9
a!queryRecordByIdentifier(
  recordType: recordType!AT Customer,
  identifier: 1,
  fields: {
    recordType!AT Customer.fields.firstName,
    recordType!AT Customer.fields.lastName,
    recordType!AT Customer.relationships.industry.fields.value
  }
)

Returns

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Return all fields for a record

This a!queryRecordByIdentifier() example returns all fields for a customer from the AT Customer record type, except any real-time custom record fields or Extra Long Text fields.

1
2
3
4
5
6
7
8
9
10
a!queryRecordByIdentifier(
  recordType: recordType!AT Customer,
  identifier: 1,
  fields: {
    /* Only use this function when all fields are necessary */ 
    a!selectionFields(
      allFieldsFromRecordType: recordType!AT Customer,
    )
  }
)

Returns

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Return all fields for a record and its related record

This a!queryRecordByIdentifier() example returns all fields for a customer from the AT Customer and AT Industry record types, except any real-time custom record fields or Extra Long Text fields.

1
2
3
4
5
6
7
8
9
10
11
12
13
a!queryRecordByIdentifier(
  recordType: recordType!AT Customer,
  identifier: 1,
  fields: {
    /* Only use this function when all fields are necessary */
    a!selectionFields(
      allFieldsFromRecordType: {
        recordType!AT Customer,
        recordType!AT Customer.relationships.industry
      }
    )
  }
)

Returns

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Return specific fields and limit related record data

This a!queryRecordByIdentifier() example returns specific fields from the AT Customer, AT Industry, and AT Order record types, and limits the related order data to a single record.

Because there is a one-to-many relationship between AT Customer and AT Order (one customer can have multiple orders), the a!relatedRecordData() function limits the results so only the order with the highest priority is returned.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
a!queryRecordByIdentifier(
  recordType: recordType!AT Customer,
  identifier: 1,
  fields: {
    recordType!AT Customer.fields.firstName,
    recordType!AT Customer.fields.lastName,
    recordType!AT Customer.relationships.industry.fields.value,
    recordType!AT Customer.relationships.order.fields.name,
    recordType!AT Customer.relationships.order.relationships.priority.fields.value
  },
  relatedRecordData: a!relatedRecordData(
    relationship: recordType!AT Customer.relationships.order,
    limit: 1,
    sort: a!sortInfo(
      field: recordType!AT Order.fields.priorityId,
      ascending: false
    )
  )
)

Returns

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Feature compatibility

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.

To use the latest version of the function, replace the function with a version suffix with a new function reference.

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

Feedback