Write custom expressions

This guide explains how to use custom expressions in schema mapping.

What are custom expressions

Custom expressions let you write Python-like code to generate attribute values. Combine multiple fields, perform calculations, or apply transformations to create the exact value you need.

Custom expressions use cases

Use custom expressions when you want to:

• Combine data from multiple fields into a single attribute.
• Calculate values based on product or variant data.
• Transform data in ways different than built-in transformations.
• Access nested or hierarchical data structures.

How custom expressions work

Access record data

Your record data is available through the br object. The record information you can access depends on whether you're configuring a product-level or variant-level attribute.

At the product level, you have access to:

• br['product']: The current product and all its fields.
• br['product']['variants']: All child variants of the product.

At the variant level, you have access to:

• br['variant']: The current variant and its fields.
• br['product']: The parent product of the current variant.

Access field values

To access a field value, use bracket notation with the field name as a string:

# Access product-level field called collections
br['product']['fields']['collections']

# Access all variants of a product
br['product']['variants']

# Access variant-level field called color
br['variant']['fields']['color']

You can't use dot notation for field access (like br.product.fields.color). Always use bracket notation with the exact field name from your records.

📘

Note

Field names are case-sensitive. If your source data has a field named Color, you must reference it as br['product']['fields']['Color'], not br['product']['fields']['color'].

Available functions

Use built-in functions and methods in your expressions.

Common functions

• len(): Get the length of a string or list.
• max(): Find the maximum value in a collection.
• min(): Find the minimum value in a collection.
• range(): Generate a sequence of numbers.
• sorted(): Sort a list.

String methods

• .lower(): Convert to lowercase.
• .upper(): Convert to uppercase.
• .removeprefix(): Remove a prefix from a string.
• .removesuffix(): Remove a suffix from a string.
• .split(): Split a string into a list.

List methods

• .append(): Add an item to a list.
• .remove(): Remove an item from a list.
• .index(): Find the position of an item.

Combine these functions and methods to build complex transformations. For a complete reference of available operations, see the full specification.

Write expressions

Single-line expressions

For simple operations, write a single-line expression that returns the value directly:

br['product']['fields']['default']['status'].lower()

Multi-line expressions

For complex logic, you can write multi-line scripts. When using multiple lines, you must include a return statement as the final line:

paths = []
for collection in br['product']['fields']['collections']:
    paths.append([{"name": collection['title'], "id": collection['handle']}])
return paths

Example expressions

Remove a URL prefix

Strip https:// from a URL field:

br['product']['fields']['default']['product_url'].removeprefix("https://")

Convert text to lowercase

Normalize a text field to lowercase:

br['product']['fields']['default']['category'].lower()

Combine fields from product and variant

Create a variant attribute that combines product-level and variant-level data:

brand = br['product']['fields']['default']['brand']
color = br['variant']['fields']['default']['color']
return brand + " - " + color

Limitations

Custom expressions run within reasonable resource limits to ensure system stability. Understanding these limits helps you design efficient expressions and troubleshoot errors.

Execution limits

Each custom expression has two types of limits:

• Time limit: Each expression must complete within a set time period. This limits the total amount of time an expression can run.

• Step limit: The system tracks the number of internal operations (or steps) an expression performs. If an expression exceeds this limit, the attribute will be ignored, or the system will follow the exceptional scenario configuration you set for the attribute.

• Item-level timeout: Beyond individual attribute limits, there is a global timeout for processing a single item. If one item has many custom expressions and their combined processing time exceeds this limit, the item update will fail.

View the processing failure in the specific limit under Jobs.

Optimize custom expressions

If you encounter limit errors, consider these approaches:

Reduce computational complexity

• Access only the data you need rather than looping through all variants. If you only need data for one variant, access it directly.
• Avoid loops when possible.

Move transformations upstream

If your expressions consistently hit limits, consider preprocessing the transformation in your source system before sending data to Data hub. This is especially relevant for very complex calculations that combine large datasets.

If your use case requires capabilities beyond these constraints, work with Bloomreach Support to explore alternative approaches.