Skip to main content

Tom Grammar Language (TGL) Guide

TGL (Tom Grammar Language) is the expression language TOM uses to define audiences. For example, SEX.D1 AND EDA1.D3 selects the people who answered category D1 of the variable SEX and category D3 of the variable EDA1.

1. Where TGL is used​

In the TOM External API you write TGL in these fields:

FieldWhereWhat the expression defines
target.filterTglRequests of POST /api/v2/table/{surveyCode}, .../html, POST /api/v2/reach/{surveyCode}, .../ranking, .../evaluation and .../response-curveThe audience the whole calculation is restricted to
filterTgl of a TARGET_VARA VARIABLES axis of a table or Reach requestOne audience as a row, column or plane of the table
targetBase.filterTglRequests of POST /api/v2/table/{surveyCode}, .../html, POST /api/v2/reach/{surveyCode}, .../ranking, .../evaluation, .../evaluation/save/{workspaceId}, .../response-curve and POST /api/v2/survey/{surveyCode}/optimizationsThe population base: the group the percentages are calculated over
target.filterTglPOST /api/v2/survey/{surveyCode}/optimizationsThe audience of the optimization, applied as a filter
tglPOST .../target and PUT .../target/{elementId}The audience saved in a target

Wherever a saved target is accepted, you can send the target id instead of an expression. When a request carries both a target id and a filterTgl, read the operation reference: some operations reject the request and others use the expression.

Each TGL field takes one single expression. For audience definitions, use boolean expressions (section 2).

2. Codes and how to find them​

TGL refers to variables and categories by code:

  • A variable code is the id of a variable returned by GET /api/v2/survey/{surveyCode}/variables, for example SEX.
  • A category is written VARIABLE.CATEGORY, with the id of the category, for example SEX.D1. Category ids repeat under different variables (D1 exists in many), so always write the variable too.
  • If you browse the tree with POST /api/v2/survey/{surveyCode}/tree/query, use the code of a node, never its id: the node id is opaque, belongs to the tree only and can change.
  • Codes are not case-sensitive. By convention, write them in UPPERCASE.

A variable code starts with a letter and can contain letters, digits and _, with no spaces: AGE, REGION_CODE.

3. Constants​

TypeExample
Integer42, 1_000 (digits can be grouped with underscores)
Decimal3.14, 0.5
Text"hello" (always double quotes)
BooleanTRUE, FALSE

Single quotes are not for text: they delimit names, labels and weights (section 7).

4. Operators​

4.1. Arithmetic​

+, -, *, /, ** (power), % (modulo), MIN and MAX. Precedence, from highest to lowest: * and /; then +, -, % and **; then MIN and MAX. Use parentheses to change the order: (INCOME + BONUS) * 1.21.

4.2. Comparison​

=, <> (also != and /=), <, <=, > and >=.

AGE > 18
AGE <> 30

Use a single = for equality: == is not valid.

4.3. Logical​

AND, OR, XOR and NOT(...). NOT is written as a function: the parentheses are required. AND binds tighter than OR and XOR. When you mix them, use parentheses:

(AGE > 18 AND SEX.D1) OR SEX.D2
NOT(EDA1.D3)

5. Sets and ranges​

  • IN and NOT IN test a numeric variable against an integer range: AGE IN 18..34, AGE NOT IN 18..34. Write the range with two dots; 18-34 is not valid.
  • A range of categories uses two dots between category codes: EDA1.D1..D5 selects the categories from D1 to D5 of EDA1.
  • A category can also be given by its text, in double quotes: REGION."NORTH". A range of such categories is REGION."NORTH".."SOUTH".

6. Functions​

Function names are followed by an opening parenthesis, as in UPPER(NAME). The grammar accepts these names:

KindNames
BooleanANY(...), ALL(...), RECORDED(...), FOUND_IN(...)
NumericABS(...), COUNT(...), EXP(...), FOUND_AT(...), INTEGER(...), RANDOM(...), REAL(...), STRLEN(...), RSCALE(...)
TextUPPER(...)
ConditionalIIF(condition, value_if_true, value_if_false)

This guide does not describe the arguments of each function. Functions are not available in saved targets (section 8).

7. Names, labels and weights​

  • Name: prefix the expression with a name in single quotes and a colon, as in 'Adults': AGE >= 18. A name can contain letters, digits, spaces and the characters . , ! ? / - _.
  • Label: suffix a part of the expression with a colon and a label in single quotes, as in AGE IN 18..65 :'Working age'.
  • Weight: an integer in single quotes followed by @, placed before the expression it applies to, as in '1'@ SEX.D1.

8. Using TGL in targets​

The tgl field of POST .../target and PUT .../target/{elementId} accepts a subset of the language. The expression is checked against the variables of the survey before anything is saved.

Accepted:

  • Category references: VARIABLE.CATEGORY, for example EDA1.D3.
  • Comparisons on numeric variables, followed by a number: AGE >= 18.
  • Integer ranges on numeric variables: AGE IN 18..34 and AGE NOT IN 18..34.
  • AND, OR, parentheses and NOT(...). AND is evaluated before OR.
  • Optional weights and labels.

Not supported:

  • A variable on its own, without a category or a condition (for example SEX): it is rejected.
  • Functions, arithmetic, text comparisons, text category references, TRUE and FALSE.
  • XOR: it is not rejected, but it is saved as OR. Write OR explicitly.
  • Comparisons and ranges on variables that are not numeric.

A name at the start of the expression ('Adults': ...) is ignored: the name of the target always comes from its label.

9. Examples​

SEX.D1
SEX.D1 AND EDA1.D3
SEX.D1 AND (EDA1.D3 OR EDA1.D4)
EDA1.D3 AND NOT(SEX.D1)
EDA1.D1..D5
AGE >= 18
AGE IN 25..54 AND SEX.D2
'Young men': SEX.D1 AND EDA1.D1..D2

AGE stands for a numeric variable of your survey. Every code must exist in the survey you calculate on.

10. Common mistakes​

WrongRight
REGION.'NORTH'REGION."NORTH" (text is always in double quotes)
AGE IN 18-65AGE IN 18..65
AGE == 18AGE = 18
NOT AGE > 18NOT(AGE > 18)
FIRST NAMEFIRST_NAME
D3 to mean a categoryEDA1.D3
A tree node id in an expressionThe code of the node, or the id from the variables list
SEX.D1 OR EDA1.D3 AND EDA1.D4 (ambiguous)SEX.D1 OR (EDA1.D3 AND EDA1.D4)
SEX alone in a saved targetSEX.D1

11. Errors​

WhereStatuserrorCodeMeaning
Create or update a target422TGL_INVALIDThe expression cannot be parsed, or uses a variable without a category or a condition. The body of this response currently reads Internal Server Error and 500 in status and statusCode: rely on the HTTP status and on errorCode.
Create or update a target400TGL_ERR_101The expression references a variable or category that does not exist in the survey.
CalculationsUsually 400The calculation engine's own codeThe expression of filterTgl is rejected by the engine. Read the errorCode together with the errorMessage, which can be in the user's language.
Optimization409 on the result callAE_ERR_413, with the origin code in the message, for example TGL_ERR_...The target of a job could not be resolved.

The Errors and troubleshooting page explains how to react to each family of codes.

12. Quick recap​

  • One expression per TGL field.
  • Variables and categories by code: VARIABLE.CATEGORY.
  • Text in double quotes; names, labels and weights in single quotes.
  • Ranges with two dots: 18..65.
  • AND binds tighter than OR: when unsure, use parentheses.
  • Codes are not case-sensitive, but keep them in UPPERCASE for readability.
  • Saved targets accept only a subset of the language (section 8).