Handlebar Helper Function: QueryFirst

Retrieves the first record from Sales Cloud, marketing objects, or data graphs that matches the specified criteria.

Availability

This helper is available in the Summer ’26 release of Marketing Cloud Next (API version 67.0).

Syntax

1{{queryfirst type=CRM|MO|DG object=OBJECT_NAME [id=SALESFORCE_ID] [fields=FIELD_1, ...FIELD_N] [sortBy=FIELDNAME ASC|DESC] [where=FILTER] [params=PARAMS]}}

Parameters

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.

Where Clause Syntax

The where parameter supports these elements:

Operators: =, !=, <, >, <=, >=, LIKE
Logic: AND, OR with parenthesized grouping
Placeholders: :paramName values that match keys in the params object

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").

Params Values

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.

1{{queryfirst type="CRM" object="Account" fields="Name"
2  where="Name LIKE :name AND Status = :status" params=(hash name=firstName status="Active")}}

Return Value

The function returns the first matching record as an object.

Usage

CRM Lookup by ID

This example retrieves an account by its CRM ID.

1{{queryfirst type="CRM" object="Account" id="001xx"}}

Marketing Object Lookup

This example retrieves a customer record from a marketing object.

1{{queryfirst type="MO" object="LegacyCustomerList" Email="test@example.com"}}

Data Graph Lookup

This example retrieves a unified profile from Data Graph.

1{{queryfirst type="DG" object="UnifiedProfile" contactPointEmail=email}}

Including a WHERE Clause

This example uses a WHERE clause with parameter placeholders.

1{{queryfirst type="CRM" object="Account" fields="Name"
2  where="Name LIKE :search" params=(hash search="Acme%")}}

Accessing Retrieved Properties

This example retrieves a record and accesses its properties.

1{{#with (queryfirst type="CRM" object="Contact" Email=userEmail)}}
2  <p>Hello {{FirstName}} {{LastName}}!</p>
3{{/with}}

Providing a Fallback Value

Nest the queryFirst function within the fallback function to handle the case where the specified record isn’t found.

1{{fallback (queryfirst type="MO" object="Preferences_DE" SubscriberId=subId).Language "en-US"}}

Using Conditional Logic

You can use the if helper to check for the existence of a record.

1{{#if (queryfirst type="CRM" object="Opportunity" AccountId=accountId Stage="Closed Won")}}
2  <p>Thank you for your business!</p>
3{{else}}
4  <p>Interested in learning more?</p>
5{{/if}}