Salesforce Docs Portal

Handlebars 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.

Syntax

{{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.

{{queryFirst type="CRM" object="Account" fields="Name"
  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

These examples show how to retrieve records from supported data sources and access their values.

CRM Lookup by ID

This example retrieves an account by its CRM ID.

{{queryFirst type="CRM" object="Account" id="001xx"}}

Marketing Object Lookup

This example retrieves a customer record from a marketing object.

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

Data Graph Lookup

This example retrieves a unified profile from Data Graph.

{{queryFirst type="DG" object="UnifiedProfile" contactPointEmail=email}}

Including a WHERE Clause

This example uses a WHERE clause with parameter placeholders.

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

Accessing Retrieved Properties

This example retrieves a record and accesses its properties.

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

Providing a Fallback Value

Nest the queryFirst function in the fallback function to handle the case where the specified record doesn't exist.

{{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.

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

See Also