Searching Configuration
Source JEXL Mapping
The displayed fields in a search response can be customized using JEXL mappings.
This allows you to transform and map document fields dynamically before they are returned in a result.
Only fields that are defined in the search mapping can be used in mapping functions. If a field is not part of the search mapping, it will not be available in the search response and therefore cannot be referenced by any mapping function.
Trick: If you need a field for intermediate transformations but don't want it in the final result, map the field in the search mapping first, then use removeField to exclude it from the response. This way, the field is available for other functions (e.g., replace, firstField) during processing but won't appear in the output.
jexl:a.replace('${internalCode} - ${sku}').removeField('internalCode')
The following mapping functions are available:
replace
Description:
Replace values using placeholders from the document.
Example:
jexl:a.replace('${sku} - ${supplierId}').replace('${sku}')
When to use: Use when you want to combine or format multiple fields into a single string (e.g., SKU and supplier ID).
firstValue
Description: Take the first element of an array. If the value is not an array, the original value is used.
Example:
jexl:a.firstValue('customerArticleNumbers')
When to use: Use when you only need one value from a list (e.g., the primary customer article number).
concat
Description: Concatenate an array of values with a separator.
Example:
jexl:a.concat('title', ' ')
When to use: Use when you want to join multiple values into a single string (e.g., all titles, tags, or categories).
firstField
Description: Use the first non-null value from a list of fields.
Example:
jexl:a.firstField('title', 'name')
When to use:
Use when there are fallback fields and you want to pick the first available (e.g., prefer title, else use name).
removeField
Description: Remove a field from the document.
Example:
jexl:a.removeField('myField')
When to use: Use when a field should not be indexed or exposed (e.g., internal fields or sensitive information).
replaceAll
Description: Replace all regex matches in a string.
Example:
jexl:a.replaceAll('.*?_(.*)', '$1')
When to use: Use when you need to normalize values (e.g., remove prefixes/suffixes from IDs).
replaceFirst
Description: Replace only the first regex match in a string.
Example:
jexl:a.replaceFirst('.*?_(.*)', '$1')
When to use: Use when only the first occurrence should be modified (e.g., strip a single prefix from a code).
mapValueByPrefix
Description: Map values that start with a given prefix (taken from a query parameter).
Example:
jexl:a.mapValueByPrefix('stockStatus', 'marketId')
When to use: Use when values should depend on runtime parameters (e.g., mapping stock status per market).
Chaining Functions
Description: Combine multiple transformations in sequence.
Example:
jexl:a.replace('${sku} - ${supplierId}').replace('${sku}')
When to use: Use when one transformation depends on another (e.g., format a field, then clean it with regex).
Advanced Transformations
scaleToPercentage
Description: Scale a numeric score field into a percentage (0–100).
Example:
jexl:a.scaleToPercentage('score', 0.0, 10.0)
When to use: Use when you need normalized scoring (e.g., showing scores as percentages in results).
mapScoreToColor
Description: Map numeric scores to traffic-light colors.
Example:
jexl:a.mapScoreToColor('score', 0.3, 0.7)
When to use: Use when scores should be categorized visually (e.g., red/yellow/green indicators).
Best Practices
- ✅ Use
firstFieldfor fallback chains of possible fields. - ✅ Use
concatfor multi-value attributes (tags, categories, etc.). - ⚠️ Test regex replacements carefully to avoid unexpected results.
- 🔗 Functions can be chained for complex mappings.