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:
| Field | Where | What the expression defines |
|---|---|---|
target.filterTgl | Requests of POST /api/v2/table/{surveyCode}, .../html, POST /api/v2/reach/{surveyCode}, .../ranking, .../evaluation and .../response-curve | The audience the whole calculation is restricted to |
filterTgl of a TARGET_VAR | A VARIABLES axis of a table or Reach request | One audience as a row, column or plane of the table |
targetBase.filterTgl | Requests 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}/optimizations | The population base: the group the percentages are calculated over |
target.filterTgl | POST /api/v2/survey/{surveyCode}/optimizations | The audience of the optimization, applied as a filter |
tgl | POST .../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
idof a variable returned byGET /api/v2/survey/{surveyCode}/variables, for exampleSEX. - A category is written
VARIABLE.CATEGORY, with theidof the category, for exampleSEX.D1. Category ids repeat under different variables (D1exists in many), so always write the variable too. - If you browse the tree with
POST /api/v2/survey/{surveyCode}/tree/query, use thecodeof a node, never itsid: the nodeidis 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
| Type | Example |
|---|---|
| Integer | 42, 1_000 (digits can be grouped with underscores) |
| Decimal | 3.14, 0.5 |
| Text | "hello" (always double quotes) |
| Boolean | TRUE, 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
INandNOT INtest a numeric variable against an integer range:AGE IN 18..34,AGE NOT IN 18..34. Write the range with two dots;18-34is not valid.- A range of categories uses two dots between category codes:
EDA1.D1..D5selects the categories fromD1toD5ofEDA1. - A category can also be given by its text, in double quotes:
REGION."NORTH". A range of such categories isREGION."NORTH".."SOUTH".
6. Functions
Function names are followed by an opening parenthesis, as in UPPER(NAME). The grammar accepts these names:
| Kind | Names |
|---|---|
| Boolean | ANY(...), ALL(...), RECORDED(...), FOUND_IN(...) |
| Numeric | ABS(...), COUNT(...), EXP(...), FOUND_AT(...), INTEGER(...), RANDOM(...), REAL(...), STRLEN(...), RSCALE(...) |
| Text | UPPER(...) |
| Conditional | IIF(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 exampleEDA1.D3. - Comparisons on numeric variables, followed by a number:
AGE >= 18. - Integer ranges on numeric variables:
AGE IN 18..34andAGE NOT IN 18..34. AND,OR, parentheses andNOT(...).ANDis evaluated beforeOR.- 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,
TRUEandFALSE. XOR: it is not rejected, but it is saved asOR. WriteORexplicitly.- 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
| Wrong | Right |
|---|---|
REGION.'NORTH' | REGION."NORTH" (text is always in double quotes) |
AGE IN 18-65 | AGE IN 18..65 |
AGE == 18 | AGE = 18 |
NOT AGE > 18 | NOT(AGE > 18) |
FIRST NAME | FIRST_NAME |
D3 to mean a category | EDA1.D3 |
A tree node id in an expression | The 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 target | SEX.D1 |
11. Errors
| Where | Status | errorCode | Meaning |
|---|---|---|---|
| Create or update a target | 422 | TGL_INVALID | The 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 target | 400 | TGL_ERR_101 | The expression references a variable or category that does not exist in the survey. |
| Calculations | Usually 400 | The calculation engine's own code | The expression of filterTgl is rejected by the engine. Read the errorCode together with the errorMessage, which can be in the user's language. |
| Optimization | 409 on the result call | AE_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. ANDbinds tighter thanOR: 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).