---
schema_version: "1"
id: 15e5766dff11393e17e8eb640f3df36714f73fac904406f20bb0d33d6ced7595
title: "Handlebars Helper Function: queryFirst"
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/handlebars/reference/data/mcn-handlebars-reference-data-queryfirst.md
canonical_url: https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-data-references/mcn-handlebars-reference-data-queryfirst.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 5ae024944e4f9fa7e4a4a129001869d281a21801f35aeac64bae810e090acd46
products:
  - Handlebars for Marketing Cloud Next
  - Marketing Cloud
---
# 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

```handlebars
{{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](#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). |

### 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](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-data-references/mcn-handlebars-reference-data-hash.md) 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.

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

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

### Marketing Object Lookup

This example retrieves a customer record from a marketing object.

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

### Data Graph Lookup

This example retrieves a unified profile from Data Graph.

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

### Including a WHERE Clause

This example uses a WHERE clause with parameter placeholders.

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

```handlebars
{{#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.

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

```handlebars
{{#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

- [query](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-data-references/mcn-handlebars-reference-data-query.md)
- [hash](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-data-references/mcn-handlebars-reference-data-hash.md)
- [fallback](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/utility/mcn-handlebars-reference-utility-fallback.md)
- [with](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/utility/mcn-handlebars-reference-utility-with.md)