Personalization syntax personalization-syntax

Personalization in Journey Optimizer uses two complementary syntaxes that work together in the same expression:

Understanding which context you are in is key to avoiding runtime errors. For example, a PQL function call placed inside {{...}} will fail because Handlebars tries to resolve it as a helper rather than evaluate it as a PQL expression.

Examples:

The attributes structure is defined in an Adobe Experience Platform XDM Schema. Learn more.

Syntax general rules general-rules

Reserved keywords reserved-keywords

Certain keywords are reserved in Profile Query Language (PQL) and cannot be used directly as field or variable names in personalization expressions. If your XDM schema contains fields with names that match reserved keywords, you must escape them using backticks (`) to reference them in your expressions.`

Reserved keywords include:

Example:

If your profile schema has a field named next, you must wrap it in backticks:

{{profile.person.`next`.name}}

Without the backticks, the personalization editor will fail validation with an error.

PQL syntax rules for special attribute keys pql-special-keys

Beyond reserved keywords, two additional cases require backtick escaping in PQL expressions.

Hyphenated attribute keys hyphenated-keys

If your XDM schema contains field names with hyphens (e.g. my-field, event-type) or names that start with or contain numbers, wrap the key in backticks inside PQL expressions:

{%= profile.events.`order-total` > 100 %}

Without backticks in a PQL expression, the hyphen is interpreted as a subtraction operator and causes a PQL syntax error.

Numeric event IDs in context attributes numeric-event-ids

When referencing context event attributes where the event ID is a number (e.g. 1697323153), wrap it in backticks. This also applies inside functions like formatDate():

{% let ts = formatDate(toDateTime(context.journey.events.`1697323153`.timestamp), "dd/MM/yyyy") %}
{{ts}}

Type coercion type-coercion

PQL is strongly typed. When comparing or passing values, both sides must be the same type. Common cases:

Available namespaces namespaces

Helpers helpers-all

A Handlebars helper is a simple identifier that may be followed by parameters. Each parameter is a Handlebars expression. These helpers can be accessed from any context in a template.

These block helpers are identified by a # preceding the helper name and require a matching closing /, of the same name.

Blocks are expressions that have a block opening ({{# }}) and closing ({{/}}).

For more information on helper functions, refer to this section.

Literal types literal-types

Adobe Journey Optimizer supports the following literal types:

Best practices best-practices

Review these syntax rules before building personalization expressions. Most runtime errors come from mixing up Handlebars and PQL contexts.

Use the correct conditional block syntax

Always use {%#if%} / {%else if%} / {%else%} / {%/if%}. The {% if %} / {% elseif %} / {% endif %} syntax is not supported.

{%#if profile.loyalty.tier = "gold"%}
Gold member content
{%else if profile.loyalty.tier = "silver"%}
Silver member content
{%else%}
Default content
{%/if%}

Do not call PQL functions inside {{...}} Handlebars blocks

{{...}} resolves Handlebars variables and helpers only — it does not evaluate PQL. Wrapping a PQL function like upperCase() inside {{...}} causes a “could not find helper” error. Use {%= ... %} instead:

Use a named loop alias when combining {{#each}} with {%#if%}

this.field is resolved by the Handlebars renderer but not by the PQL evaluator inside a {%#if%} condition. Define a named alias with as |item| so both contexts can resolve the field:

{{#each profile.orders as |order|}}
  {%#if order.status = "pending"%}
  Order {{order.id}} is pending.
  {%/if%}
{{/each}}

Assign PQL function results to a variable before looping

PQL UDFs such as topN cannot be called directly inside {{#each}}. Evaluate them first with {% let %}, then iterate over the result:

{% let topOrders = topN(profile.orders, price, 3) %}
{{#each topOrders}}
  {{this.name}} — {{this.price}}€
{{/each}}

Use {% let %} to avoid repeating function calls

When a computed value is needed more than once, store it in a variable. This improves readability and prevents redundant evaluations:

{% let cleanName = replaceAll(profile.person.name.firstName, "[^a-zA-Z]", "") %}
Hi {{cleanName}}, your code is: WELCOME-{%= upperCase(cleanName) %}

Use the correct argument order for dateDiff

dateDiff(start, end) takes the earlier date first. To compute days remaining until a future date, pass the current date as the first argument:

{% let daysLeft = dateDiff(getCurrentZonedDateTime(), stringToDate(profile.loyalty.expiryDate)) %}

Use = for equality comparisons in PQL, not ==

PQL uses a single = operator for equality. Using == results in a syntax error.

Use backticks for hyphenated field names — in PQL expressions only

If an XDM schema field name contains a hyphen (e.g. order-total), wrap it in backticks to prevent the hyphen from being parsed as a subtraction operator. This is only supported inside {%= ... %} PQL expressions, not in {{...}} Handlebars blocks:

{%= profile.events.`order-total` > 100 %}

For ready-to-use expressions you can copy directly into your content, see Personalization recipes.