Handlebar Helper Function: QueryFirst
Retrieves the first record from Sales Cloud, marketing objects, or data graphs that matches the specified criteria.
This helper is available in the Summer ’26 release of Marketing Cloud Next (API version 67.0).
| Parameter | Type | Description |
|---|---|---|
fields | String | A comma-separated list of field names to retrieve from the record. |
id | String | The Salesforce ID of the target object. Use this parameter only when type is CRM. |
object | String | Required. The API name of the target Salesforce object, marketing object, or data graph. |
params | Object | Parameter values for where placeholders. Every parameter name in the where clause must have a corresponding key. See Params Values. |
sortBy | String | Indicates the sort order to apply to results before selecting the first result. Possible values: ASC or DESC. Use this parameter only when type is CRM. |
type | String | Required. The type of data source to query. Possible values: "CRM" (for Sales Cloud objects), "MO" (for marketing objects), or "DG" (for data graphs). |
where | String | A filter for the query. Use :paramName placeholders. Can’t be combined with inline field conditions or the id parameter. See Where Clause Syntax. |
The where parameter supports these elements:
- Operators:
=,!=,<,>,<=,>=,LIKE - Logic:
AND,ORwith parenthesized grouping - Placeholders:
:paramNamevalues that match keys in theparamsobject
You can use parentheses to create logical groupings. For example, to add a filter that includes active records and either the Revenue value or the CreationDate value is greater than a specified parameter, use Status = "Active" AND (Revenue > 100000 OR CreationDate > "2025-01-01").
Use the hash function to specify parameters. This example uses the hash function to create an object with two properties: name and status. The where statement then refers to these parameters.
The function returns the first matching record as an object.
This example retrieves an account by its CRM ID.
This example retrieves a customer record from a marketing object.
This example retrieves a unified profile from Data Graph.
This example uses a WHERE clause with parameter placeholders.
This example retrieves a record and accesses its properties.
Nest the queryFirst function within the fallback function to handle the case where the specified record isn’t found.
You can use the if helper to check for the existence of a record.