Use the LOOKUP function to look up values in a source module or list and display the values in a target module. 

For example, you can look up the salary for each employee in a module based on grade and region and display them in a results module. 

Syntax

Values to lookup[LOOKUP: Mapping, LOOKUP: Mapping 2]

Never use SUM and LOOKUP in the same formula. This can lead to extremely long calculation times. For more information, see Formulas and their effects on model performance .

Arguments

ArgumentData typeDescription
Values to lookupNumber, Boolean, date, time period, list, or text line item.The data source to retrieve a value from. This can be a module line item module.lineitem or a list property list.property, and can be in any data format.
MappingList, date, or time line item, or a property from the source.

The mapping is the cross-reference criteria. It can be a line item with a data type of list or time period. It can also be a property from the source or a date data type. The mapping matches the source line item or property with the target line item. 

A common dimension must link the source and the mapping cross-reference.

You can enter multiple arguments as mappings. Arguments must be separated by a comma. For example: 

Pay Table.BasicPay[LOOKUP: Grade, LOOKUP: Region, LOOKUP: Period, ...]

The LOOKUP function returns a result of the same data type as the Values to lookup. 

Note: In Classic, LOOKUP returns the value of the aggregate item in a composite hierarchy, and the default value for the line item in a non-composite hierarchy.

LOOKUP and time periods

You can use LOOKUP when the source line item is a finer timescale than the mapping line item data type. You can also use LOOKUP when the dimension of the target line item is a finer timescale than the dimension of the mapping line item.

However, if the time scale that you use in the results doesn't exist in the source, then LOOKUP returns 0. For example if you select Half-year totals in the results but it isn't selected in the source, LOOKUP returns 0.

Steps to use LOOKUP 

To use LOOKUP:

  1. In the target module, open the formula editor for the target line item.
  2. Open the source module (if different from the target) and select the line item or list property heading. 
  3.  In the target module, type [LOOKUP: in the editor.
  4. Open the module that contains the mapping criteria, if different, and then select the line item to use for mapping. Either a:
    • List data type
    • Time period or date data type
    • List property

      You can also type the mapping criteria in the format module.lineitem or list.property.
  5. If you have multiple mapping criteria, separate them with a comma, and end with a  ]. For example, Pay Table.BasicPay[LOOKUP: Grade, LOOKUP: Region]

Calculation engine functionality differences

In Polaris, the LOOKUP function returns the value of the aggregate item in composite and non-composite hierarchies. The Classic Engine returns the value of the aggregate item in a composite hierarchy, and the default value for the line item in a non-composite hierarchy. 

In Polaris, you can't use the LOOKUP function in a result line item with a time scale greater than the values you look up. The Classic Engine returns a value of 0 in this case.

In Polaris, if the target line item can't reference the mapping line item, then the LOOKUP is invalid.

Syntax example

Pay table.Basic pay[LOOKUP: Grade, LOOKUP: Region]

Where:

  • Pay table is the source module
  • Basic pay is a line item in the source module
  • Grade and Region are the dimensions in the source module and also line items in the results module

Additional information 

For more information on when to use LOOKUP, see Formula usage tips. 

Excel equivalent function

LOOKUP

SELECT

Examples

Use the LOOKUP function to look up values in a source module or list and display the values in a target module using mapping criteria. These examples demonstrate how you can use LOOKUP in different scenarios in your models. Select each example to expand.