A calculated field is an expression-based value derived from your data — for example, a discount ratio, a concatenated label, or a running total. Calculated fields are not a query-native object: a query never defines a stored field. Instead, a query either references a calculated field that already lives in the Semantic Data Model (by its API name) or carries an inline, query-scoped calculation in the request body. In both cases the value is computed at query time and is never persisted to the underlying tables.
There are two roles, mirroring the two authoring entities: a calculated dimension produces a non-numeric, non-aggregatable value used to classify or group rows, and a calculated measurement produces a numeric value with an aggregation method. Use a model calculated field when the calculation is reusable and governed centrally; use an on-the-fly calculated field when the calculation is specific to one request and you do not want to change the model.
You can reference a calculated field almost anywhere an expression is accepted — in fields, in filter, in aggregate_filter (HAVING), in a sort order, and as a grouping axis. The formula grammar itself (functions, operators, level-of-detail syntax) is shared with the rest of the expression language.
Model calculated fields are defined at authoring time as one of two entities: a SemanticCalculatedDimension (a non-aggregatable, expression-based dimension) or a SemanticCalculatedMeasurement (a numeric calculation with a default aggregation type, data type, and decimal places). Each carries an expression, a syntax (formula dialect), and an optional set of filters that scope the data the expression sees. A query references either one by its apiName. For how to define these entities, see Semantic Calculated Dimension and Semantic Calculated Measurement in the Authoring API.
On-the-fly calculated fields have no model metadata — they are declared entirely within a single query request.
Reference a persisted calculated field the same way you reference any model field: with a semantic_field expression carrying the field’s apiName. The model defines the formula; the query only names it. A model calculated measurement can reference other calculated fields, so its expression can be nested. Optionally set semantic_aggregation_method to override the field’s default aggregation for this query.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "semantic_field": {
7 "name": "formula_measurement_example"
8 }
9 },
10 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM"
11 }
12 // ...
13 ],
14 "options": {
15 "detailed_rows": true
16 }
17 },
18 "semantic_model": {
19 "apiName": "Sales",
20 "label": "Sales",
21 // ... semanticDataObjects ...
22 "semanticCalculatedMeasurements": [
23 {
24 "apiName": "formula_measurement_example",
25 "label": "formula_measurement_example",
26 "dataType": "Number",
27 "decimalPlace": 3,
28 "expression": "10 * inner_formula_measurement_example",
29 "syntax": "Salesforce"
30 },
31 {
32 "apiName": "inner_formula_measurement_example",
33 "label": "inner_formula_measurement_example",
34 "dataType": "Number",
35 "decimalPlace": 3,
36 "expression": "100 + SemanticAccount__dlm.semantic__Number__c",
37 "syntax": "Salesforce"
38 }
39 ]
40 }
41}Carry a calculation that exists only for this request as an inline calculated_field object inside a QueryField expression. It never touches the model. A calculated_field declares a name, an expression, and its output kind: a numeric measurement uses calculated_measure_expression, and a non-numeric dimension uses calculated_dimension_expression (see the next two sub-sections). For a measurement, set semantic_aggregation_method to control aggregation; SEMANTIC_AGGREGATION_METHOD_USER_AGG treats the expression as already aggregated, which is also permitted for a formula that evaluates to a static number such as POWER(2,2).
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "calculated_field": {
7 "name": "simple_power_calc",
8 "expression": "POWER(2,2)",
9 "calculated_measure_expression": {
10 "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER"
11 }
12 }
13 },
14 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM",
15 "alias": "simple_power_calc"
16 }
17 ],
18 "options": {
19 "detailed_rows": true,
20 "grand_total": true,
21 "row_counts": true
22 }
23 },
24 "semantic_model": {
25 "apiName": "Sales",
26 "label": "Sales"
27 // ...
28 }
29}A calculated_field object carries:
name — a label for the calculation within the query.expression — the formula string.syntax — the formula dialect ("Tua" or "Salesforce"); optional.calculated_measure_expression (numeric) or calculated_dimension_expression (non-numeric).For a measurement, calculated_measure_expression may include decimal_places_options.decimal_places. To use an on-the-fly dimension as a grouping axis, set grouping: "ROW_GROUPING" on the enclosing QueryField (see Grouping). The example below selects one dimension calc as a grouping axis and one measure calc aggregated with USER_AGG.
1{
2 "structuredSemanticQuery": {
3 "fields": [
4 {
5 "alias": "simple calc",
6 "expression": {
7 "calculated_field": {
8 "name": "simple-calc",
9 "expression": "[SemanticAccount__dlm].[sdm__LastModifiedDate__c]",
10 "calculated_dimension_expression": {
11 "dimension_output_type": "SEMANTIC_DIMENSION_TYPE_DATE_TIME"
12 }
13 }
14 },
15 "grouping": "ROW_GROUPING"
16 },
17 {
18 "expression": {
19 "calculated_field": {
20 "name": "summary-calc-in-select",
21 "expression": "SUM([SemanticAccount__dlm].[sdm__AccountTypeId__c])",
22 "calculated_measure_expression": {
23 "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER",
24 "decimal_places_options": {
25 "decimal_places": 2
26 }
27 }
28 }
29 },
30 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG"
31 }
32 // ...
33 ]
34 },
35 "semantic_model": {
36 // ...
37 }
38}The output declaration determines whether the calculated field behaves as a dimension or a measurement:
calculated_dimension_expression.dimension_output_type — a SEMANTIC_DIMENSION_TYPE_* value such as SEMANTIC_DIMENSION_TYPE_TEXT or SEMANTIC_DIMENSION_TYPE_DATE_TIME. Dimension calcs are not aggregated.calculated_measure_expression.measure_output_type — a SEMANTIC_MEASUREMENT_TYPE_* value such as SEMANTIC_MEASUREMENT_TYPE_NUMBER. Pair it with a semantic_aggregation_method.The example below declares a text dimension calc (used inside a filter):
1{
2 "structured_semantic_query": {
3 "fields": [
4 // ...
5 ],
6 "context_filter": {
7 "simple_dimension_filter": {
8 "unary_predicate": {
9 "expression": {
10 "calculated_field": {
11 "name": "formula_on_the_fly_example",
12 "expression": "UPPER([SemanticAccount__dlm].[sdm__AccountSource__c])",
13 "syntax": "Tua",
14 "calculated_dimension_expression": {
15 "dimension_output_type": "SEMANTIC_DIMENSION_TYPE_TEXT"
16 }
17 }
18 },
19 "unary_operator": "UNARY_OPERATOR_IS_NOT_NULL"
20 }
21 }
22 }
23 },
24 "semantic_model": {
25 // ...
26 }
27}How a formula names a data field depends on the dialect:
[Table].[Field] — for example COUNTD([SemanticAccount__dlm].[semantic__AccountSource__c]).Table.Field — for example 100 + SemanticAccount__dlm.semantic__Number__c.A formula can reference raw fields and other calculated fields by name.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "calculated_field": {
7 "name": "countd",
8 "expression": "COUNTD([SemanticAccount__dlm].[semantic__AccountSource__c])",
9 "calculated_measure_expression": {
10 "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER"
11 }
12 }
13 },
14 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG",
15 "alias": "Count Distinct"
16 }
17 ],
18 "options": {
19 "detailed_rows": true,
20 "grand_total": true,
21 "row_counts": true
22 }
23 },
24 "semantic_model": {
25 "apiName": "Sales",
26 "label": "Sales"
27 // ...
28 }
29}Set syntax on a calculated_field to choose the formula dialect: "Tua" or "Salesforce". On-the-fly calculations use the Tua grammar by default; set syntax to "Salesforce" to write the expression in the Salesforce dialect. Dialects can interoperate — a Salesforce-syntax calc can reference a model calculated field authored in Tua syntax by its API name.
1{
2 "structured_semantic_query": {
3 "fields": [
4 {
5 "expression": {
6 "calculated_field": {
7 "name": "sf_calc_referring_to_tua_calc",
8 "expression": "tua_model_calc + 123",
9 "syntax": "Salesforce",
10 "calculated_measure_expression": {
11 "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER"
12 }
13 }
14 },
15 "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG",
16 "alias": "SF referring to TUA"
17 }
18 ]
19 },
20 "semantic_model": {
21 "apiName": "Sales",
22 "label": "Sales",
23 // ...
24 "semanticCalculatedMeasurements": [
25 {
26 "apiName": "tua_model_calc",
27 "label": "tua_model_calc",
28 "dataType": "Number",
29 "decimalPlace": 3,
30 "expression": "SUM([SemanticAccount__dlm].[semantic__Number__c])",
31 "syntax": "Tua"
32 }
33 ]
34 }
35}A level-of-detail expression computes an aggregation at a granularity that differs from the query’s selected dimensions. It has the form { FIXED | INCLUDE | EXCLUDE [Dim1], [Dim2], ... : AGG([Measure]) }:
LOD expressions are written in the Tua dialect and can be nested up to six levels deep. Only FIXED LOD expressions can be used as a calculated dimension. The following model calculated dimension uses nested FIXED LOD expressions:
1{
2 "semanticModel": {
3 "apiName": "Sales_Insights_KPI_Semantics",
4 // ...
5 "semanticCalculatedDimensions": [
6 {
7 "apiName": "Last_Stage_RI_clc",
8 "label": "Last Stage",
9 "dataType": "Text",
10 "expression": "IF { FIXED [Opportunity].[Opportunity_Id]: COUNT([Opportunity_History].[Opportunity_History_Id]) } > 1 AND [Opportunity_History].[Opportunity_History_Id] = { FIXED [Opportunity].[Opportunity_Id]: MAX([Opportunity_History].[Opportunity_History_Id]) } THEN \"true\" \nELSE \"false\"\nEND",
11 "level": "Row"
12 }
13 // ...
14 ]
15 }
16}Performance: A
FIXEDLOD is computed before dimension filters, so ordinary dimension filters do not reduce the rows it scans — they apply only to the LOD’s dimension subquery, not to its calculation.INCLUDEandEXCLUDELODs are computed after dimension filters, so those filters do apply to the calculation. To reduce aFIXEDLOD’s scan, use a context filter (which applies before it) or anINCLUDE/EXCLUDELOD instead.
Performance: Each LOD expression generates its own subquery joined back to the query, and nesting LODs compounds this. Use the fewest and shallowest LODs that express the calculation.
Performance: A filter that references an LOD expression disables the window-function optimization and forces a subquery-and-join plan.
Reference a calculated field in select fields, in filter, in aggregate_filter (HAVING), in a sort order, and as a grouping axis. In aggregate_filter, the calculation must be an aggregated measure so the predicate runs after aggregation, like a SQL HAVING clause.
1{
2 "structured_semantic_query": {
3 "fields": [
4 // ...
5 ],
6 "aggregate_filter": {
7 "binary_predicate": {
8 "left_expression": {
9 "calculated_field": {
10 "name": "summary",
11 "expression": "1+sum(AccountSemanticLayer__dll.AnnualRevenue__c)",
12 "calculated_measure_expression": {
13 "measure_output_type": "SEMANTIC_MEASUREMENT_TYPE_NUMBER"
14 }
15 }
16 },
17 "binary_operator": "BINARY_OPERATOR_GREATER_THAN",
18 "right_expression": {
19 "int_expression": 5
20 }
21 }
22 }
23 },
24 "semanticModelApiName": "test_model"
25}| Field (wire name) | Type | Required | Description |
|---|---|---|---|
calculated_field | CalculatedField | N | An inline (on-the-fly) or referenced calculation within an expression. |
calculated_field.name | String | Y | Name of the calculation within the query. |
calculated_field.expression | String | Y | The formula string. |
calculated_field.syntax | String (enum) | N | Formula dialect: "Tua" (default for on-the-fly) or "Salesforce". |
calculated_measure_expression | CalculatedMeasureExpression | N* | Declares a numeric output; carries measure_output_type and optional decimal_places_options. |
calculated_measure_expression.measure_output_type | String (enum) | Y | SEMANTIC_MEASUREMENT_TYPE_* value (e.g. SEMANTIC_MEASUREMENT_TYPE_NUMBER). |
calculated_dimension_expression | CalculatedDimensionExpression | N* | Declares a non-numeric output; carries dimension_output_type. |
calculated_dimension_expression.dimension_output_type | String (enum) | Y | SEMANTIC_DIMENSION_TYPE_* value (e.g. SEMANTIC_DIMENSION_TYPE_TEXT, SEMANTIC_DIMENSION_TYPE_DATE_TIME). |
semantic_field.name | String | Y | API name used to reference a model calculated field. |
* Exactly one of calculated_measure_expression or calculated_dimension_expression is set per calculated_field.
For the full request schema, see Request Reference.
SEMANTIC_AGGREGATION_METHOD_NONE, SEMANTIC_AGGREGATION_METHOD_AUTO, or SEMANTIC_AGGREGATION_METHOD_USER_AGG. USER_AGG is also allowed for a formula that evaluates to a static number with no field references (for example 123, INT(1.0), PI() + 4), which the query treats as already aggregated.detailed_rows is true. Aggregated fields and aggregate (HAVING) filters are likewise disallowed when detailed_rows is true.filter and aggregate_filter (HAVING).grouping: "ROW_GROUPING".USER_AGG, applied to calculated measurements.
j