Design

Lookup

Find a value in a list or dictionary using a search filter
COMMUNITY FEATURE Available for:
Carbone Cloud
Carbone On-premise
Embedded Carbone JS v5.2+ NEW

Lookup values from another array

NEW v5.2.0+

To use this early-adopter feature, you must enable the pre-release flag by setting {o.preReleaseFeatureIn=5002000}. Learn how to activate pre-release features here.

It’s common to have an array where you only store the ID of an object, and want to display a property from the related object stored in a different array. This is called a "lookup" or a "join" between arrays (like a join in a database, or VLOOKUP in Excel).

For example, imagine you have one array with movie actors, and another with movies, where each movie only stores the actor's ID. You want to print the name of each movie along with the main actor’s first name.

data

{
  "movies": [
    { "actorId" : 10, "name" : "Matrix"    },
    { "actorId" : 20, "name" : "Babylon"   },
    { "actorId" : 10, "name" : "John Wick" }
  ],
  "actors": [
    { "id" : 10, "firstName" : "Keanu"  },
    { "id" : 20, "firstName" : "Margot" }
  ]
}

template

Movie NameMain Actor  {o.preReleaseFeatureIn=5002000}{d.movies[i].name}{d.movies[i].actorId:print(..actors[id=.actorId].firstName)}{d.movies[i+1].name}

result

Movie NameMain Actor  MatrixKeanuBabylonMargotJohn WickKeanu

Detailed Documentation: Lookup Syntax

You can use several types of search expressions to look up values from another array. Here’s how each type works:

Index Lookup: `[INTEGER]`

Selects the item at a specific index in the target array.

Example:
{d[i].movies[i].id:print(..actors[10].name)}
This prints the name of the actor at index 10 of the actors array.

Current Iterator Lookup: `[.i]`

This method selects the item from the target array that shares the same index as the current item in your loop.

For a deeper explanation, see the Access the Loop Iterator Value section.

Example:
{d.movies[i].id:print(..otherTable[.i].name)}
This prints the name at the same index in otherTable as the current index in movies.

Equality Lookup: `[X = Y]`

Finds the first element in the target array where a field matches a value, like a SQL join or Excel VLOOKUP.

Usage Example:
{d.movies[i].actorId:print(..actors[id=.actorId].firstName)}
- This finds the item in actors where id equals the current movie’s actorId and returns firstName.
One equality per lookup:
You can use only one = comparison in each lookup.
Left side (LEFT_OPERAND):
- Refers to a property of each item in the searched array (like id or .id).
- If you write something like d.sub.id, here, d is interpreted as a property of the searched item, not an absolute path.
Right side (RIGHT_OPERAND):
- Can be a relative path from the main tag (starting with .),
  or an absolute path starting with d. or c.
- Most common: use a relative path (like .actorId) to reference a field in your data source.
- If RIGHT_OPERAND doesn't start with ., d., or c., it is treated as a fixed string.
  - Note: these constant strings can’t have spaces.
  - Make sure the data types on both sides of the = are the same (for example, both should be numbers, or both should be strings).

Summary Table

Syntax Type	Description	Example
`[NUMBER]`	Select by index	`{...:print(..array[2].field)}`
`[.i]`	Use current index from main loop	`{...:print(..array[.i].field)}`
`[field = .otherField]`	Join with array item where field matches value	`{...:print(..array[id=.someId].name)}`
`[field = text]`	Lookup constant value (no spaces in the constant)	`{...:print(..array[name=Tom].score)}`