Function customFormula

customFormula( title, formula, context, dataType?): Attribute

Creates a calculated attribute (a formula-based Attribute) from a valid custom formula.

This is the attribute counterpart of measureFactory.customFormula: the resulting element is consumed as an attribute (for example, in the category/breakBy of a chart's data options, or in dimensions of a query) and produces categorical/grouping values rather than an aggregated number.

Use square brackets ([]) within the formula to reference attributes. Each unique reference must be defined using a property:value pair in the context parameter. Supported functions include string functions (for example Concat, Left, Right) and conditional expressions (IF, CASE). See full list of supported dashboard functions for calculated attributes.

Pass dataType when the result type is known, for example a CASE that returns numbers, so filters on the attribute compare values correctly.

Parameters

Parameter	Type	Description
`title`	`string`	Title of the calculated attribute to be displayed
`formula`	`string`	Formula used to compute the attribute's values
`context`	`CustomFormulaContext`	Formula context as a map of names to attributes (and, in advanced cases, measures or filters)
`dataType`?	`CalculatedAttributeDataType`	Optional JAQL data type of the formula's result (`text`, `numeric` or `datetime`); when omitted, the query client resolves it at query time

Returns

Attribute

A calculated attribute instance

Example

Combine two attributes into a single text attribute.

const ageAndGender = attributeFactory.customFormula(
  'Age & Gender',
  'Concat([ageRange], " ", [gender])',
  {
    ageRange: DM.Commerce.AgeRange,
    gender: DM.Commerce.Gender,
  },
);

Bucket a numeric attribute into named groups with a CASE expression.

const ageGroup = attributeFactory.customFormula(
  'Age Group',
  "CASE WHEN [ageRange] = '0-18' THEN 'Minor' WHEN [ageRange] = '65+' THEN 'Senior' ELSE 'Adult' END",
  { ageRange: DM.Commerce.AgeRange },
);