Predict and Forecast

Predict and Forecast both bring predictive values into a semantic query, but they come from opposite places. Predict surfaces the output of an Einstein Data Cloud (EDC) prediction model that is authored in the Semantic Data Model — the query only references the resulting field by its API name. Forecast projects a numeric measure forward over time and is configured entirely per query — there is no model metadata behind it.

Use Predict when a scoring model already lives in the model and you want each row (or grouped result) to carry its model-scored value alongside your regular fields. Use Forecast when you want a time-series projection (for example, revenue by close date over the next several weeks) computed directly from the data the query already selects.

The single most important thing to know: these are separate mechanisms. Predict adds no request syntax at all — if a prediction field exists in the model, you query it by API name. Forecast adds a query-native forecast_field (and optional forecast_options) that is not defined in the model.

Predict brings the output of an Einstein Data Cloud (EDC) prediction model into a semantic query as an ordinary field. A prediction is defined in the Semantic Data Model as a calculated measurement whose expression invokes predict('<prediction-model-api-name>'), backed by a SemanticPredictionModel that names the underlying EDC model and maps its inputs to fields in the model. At query time none of that configuration is passed in the request — the entire prediction surface is authored in the model, and the query simply references the resulting field by its API name.

Because the prediction is expressed as a calculated field, you reference it exactly like any other calculated field: put its API name in a semantic_field expression inside fields[], and — if you want them — select the companion prediction-insight fields the model generates. Predict adds no new request syntax. There is no predict block, model reference, or input mapping in structuredSemanticQuery. If a prediction field exists in the model, you query it by API name; if it doesn’t, there is nothing to query.

A prediction is a Predict-typed SemanticCalculatedMeasurement whose expression is predict('<prediction-model-api-name>'), paired with a SemanticPredictionModel entry in the model that declares the EDC modelApiName, the input fieldMapping, and knobs such as maxRecommendations and maxTopPredictors. The model author also chooses whether to expose the prediction-insight companion fields. None of this is set per query — see Semantic Calculated Measurement in the Authoring API for how prediction calcs and their backing models are defined.

Select a prediction result the same way you select any model-defined calculated field: place its API name in a semantic_field expression. The example below queries a model whose semanticPredictionModels entry defines the prediction, and selects the generated insight field by name.

1{
2  "structured_semantic_query": {
3    "fields": [
4      {
5        "expression": {
6          "semantic_field": {
7            "name": "Predicted_ssot_Id_pi_prediction_insight"
8          }
9        },
10        "alias": "Predicted_ssot_Id_pi_prediction_insight",
11        "row_grouping": true
12      }
13    ],
14    "options": {
15      "limit_options": {
16        "limit": 100
17      }
18    }
19    // ...
20  },
21  "semantic_model": {
22    "apiName": "test131_2",
23    "semanticCalculatedMeasurements": [
24      {
25        "apiName": "Predicted_ssot_Id_pi",
26        "dataType": "Number",
27        "expression": "predict('Predicted_ssot_Id_CM_12l_GuB103dbad1_prediction_model5')",
28        "syntax": "Tua",
29        "level": "Row"
30      }
31      // ...
32    ],
33    "semanticPredictionModels": [
34      {
35        "apiName": "Predicted_ssot_Id_CM_12l_GuB103dbad1_prediction_model5",
36        "modelApiName": "Predicted_ssot_Id_CM_12l_GuB103dbad1",
37        "predict": {
38          "maxRecommendations": 1,
39          "maxTopPredictors": 2,
40          "fieldMapping": [
41            {
42              "dataCloudFieldApiName": "Account_Revenue_Feature",
43              "semanticFieldReference": {
44                "calculatedFieldApiName": "Account_Revenue_Feature_Calc"
45              }
46            }
47          ]
48        }
49      }
50    ]
51    // ...
52  }
53}

When a prediction model is configured to surface insights, the model exposes three companion calculated fields you can select by their API name:

• prediction_insight_type — a dimension describing the kind of insight.
• prediction_insight — a dimension carrying the insight value.
• prediction_insight_impact — a measurement carrying the numeric impact.

Each is a model-defined calculated field (its authored expression wraps the parent predict calc, e.g. prediction_insight([Predicted_ssot_Id_pi])), so you reference it by its API name through a semantic_field expression and can sort or group by it like any other field. The example below selects the insight field and sorts on it.

1{
2  "structured_semantic_query": {
3    "fields": [
4      {
5        "expression": {
6          "semantic_field": {
7            "name": "Predicted_ssot_Id_pi_prediction_insight"
8          }
9        },
10        "alias": "Predicted_ssot_Id_pi_prediction_insight",
11        "row_grouping": true
12      }
13    ],
14    "options": {
15      "sort_orders": [
16        {
17          "simple_sort_order": {
18            "sort_by_field_alias": "Predicted_ssot_Id_pi_prediction_insight",
19            "sorting_order": "ASC"
20          }
21        }
22      ],
23      "limit_options": {
24        "limit": 100
25      }
26    }
27    // ...
28  },
29  "semantic_model": {
30    "semanticCalculatedDimensions": [
31      {
32        "apiName": "Predicted_ssot_Id_pi_prediction_insight",
33        "label": "prediction_insight([Predicted_ssot_Id_pi])",
34        "dataType": "Text",
35        "expression": "prediction_insight([Predicted_ssot_Id_pi])",
36        "syntax": "Tua",
37        "level": "Row"
38      }
39      // ...
40    ]
41    // ...
42  }
43}

Performance: Scoring a prediction model is comparatively expensive — the model runs over the rows the query produces, so cost grows with the size of the result set. Keep the scored result under about 1,000 rows: add filters to restrict the rows returned, and use grouping so the model scores aggregated results rather than raw detail rows.

Forecasting projects a numeric measure forward over time inside a single semantic query. Given a date or datetime dimension and a numeric measure, add a forecast_field to your query and the response returns both the historical rows and the projected future rows in one result set — no separate call, no pre-trained model to manage. The forecast is trained and evaluated at query time.

Use forecasting when you want a time-series projection (for example, revenue by close date over the next several weeks) computed directly from the data the query already selects. Forecasting is a query-native construct: you configure it per request. It is distinct from EDC Predict() calculated fields — a forecast is not defined in the model and does not reference a persisted prediction model.

The single most important thing to know: a forecast reads exactly one non-aggregated date (or datetime) dimension as its time axis, and projects an aggregated numeric measure over it. You point the forecast_field at those fields by their query aliases, choose how far into the future to project, and optionally pick a model, confidence bounds, and how to treat gaps in the series. A query can carry more than one forecast field when the window and model are supplied through the top-level forecast_options object.

No dedicated model metadata — forecasting is configured per query. A forecast_field has no authoring entity of its own.

The two inputs a forecast references are defined in the model: the date/datetime dimension and the numeric measure. You reference them by their query aliases, and they resolve to fields defined on a Semantic Data Object (or to a calculated dimension/measurement). For how those fields are defined, see Semantic Data Object Field in the Authoring API.

Add a forecast_field expression to fields[]. It carries a measure whose field_alias names the aggregated numeric field to project, and a dims[] entry whose date_dim.field_alias names the date/datetime dimension that supplies the time axis. Both aliases must match aliases of other fields in the same query. Give the forecast field its own alias, and set its semantic_aggregation_method to SEMANTIC_AGGREGATION_METHOD_USER_AGG (the forecast value is already aggregated). The from, to, and forecast_model members set the projection window and the model.

1{
2  "structured_semantic_query": {
3    "fields": [
4      {
5        "expression": {
6          "table_field": { "name": "test1", "table_name": "SemanticAccount__dlm" }
7        },
8        "alias": "test1",
9        "row_grouping": true
10      },
11      {
12        "expression": {
13          "table_field": { "name": "test1", "table_name": "SemanticContact__dlm" }
14        },
15        "alias": "mes1",
16        "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_MAX"
17      },
18      {
19        "expression": {
20          "forecast_field": {
21            "dims": [
22              { "date_dim": { "field_alias": "test1" } }
23            ],
24            "measure": { "field_alias": "mes1" },
25            "from": { "predefined_date": "LATEST_DATA" },
26            "to": {
27              "forecast_interval": { "time_unit": "DAYS", "value": 7 }
28            },
29            "forecast_model": { "ridge_regression": {} }
30          }
31        },
32        "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG",
33        "alias": "Forecast_sum days"
34      }
35    ]
36  },
37  "semantic_model": {
38    // ...
39  }
40}

You can also supply the window and model in a top-level forecast_options object that is a sibling of fields[], leaving the forecast_field itself to carry only the measure:

1{
2  "structured_semantic_query": {
3    "fields": [
4      // ... date dimension aliased "test1", measure aliased "mes1" ...
5      {
6        "expression": {
7          "forecast_field": {
8            "measure": { "field_alias": "mes1" }
9          }
10        },
11        "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG",
12        "alias": "Forecast_sum days"
13      }
14    ],
15    "forecast_options": {
16      "forecast_from": { "predefined_date": "LATEST_DATA" },
17      "forecast_to": {
18        "forecast_interval": { "value": 7, "time_unit": "DAYS" }
19      },
20      "forecast_model": { "holt_winters": {} },
21      "forecast_context": { "model_uuid": "test_mode_id" }
22    }
23  },
24  "semantic_model": {
25    // ...
26  }
27}

The window has a start (forecast_from) and an end (forecast_to / to). Give each either a named anchor or an explicit calendar date:

• predefined_date — LATEST_DATA, or NOW. forecast_from defaults to the latest date present in the data, so the projection begins where history ends.
• explicit_date — an exact date_expression with year, month, and day.
• forecast_interval (for the end only) — a value plus a time_unit of MINUTES, HOURS, DAYS, WEEKS, MONTHS, QUARTERS, or YEARS. The end is that many units past the start.

This example forecasts from one explicit date to another:

1{
2  "forecast_options": {
3    "forecast_from": {
4      "explicit_date": {
5        "date_expression": { "month": 9, "day": 3, "year": 2022 }
6      }
7    },
8    "forecast_to": {
9      "explicit_date": {
10        "date_expression": { "month": 9, "day": 9, "year": 2022 }
11      }
12    },
13    "forecast_model": { "holt_winters": {} },
14    "forecast_context": { "model_uuid": "test_mode_id" }
15  }
16}

Set forecast_model to one of two runtime models:

• holt_winters — exponential smoothing with trend and seasonality. This is the default when forecast_model is omitted. Holt-Winters tries multiple seasonalities and selects the one with the lowest error, so you do not specify a seasonality period.
• ridge_regression — a ridge-regression fit (used by Tableau Pulse).

Each is an empty object; the model is selected by which key you set.

1{
2  "forecast_options": {
3    "forecast_model": { "ridge_regression": {} }
4  }
5}

Request confidence output through confidence_params inside forecast_context. Set confidence_level (for example, LEVEL_95) and turn on the columns you want: include_interval_col adds the confidence-level column, and include_lower_bound_col / include_upper_bound_col add the lower and upper bound columns. All three column flags default to false. When you request any confidence output you must set confidence_level — the level is required in the forecast context.

1{
2  "forecast_context": {
3    "model_uuid": "test_mode_id",
4    "confidence_params": {
5      "confidence_level": "LEVEL_95",
6      "include_interval_col": true,
7      "include_lower_bound_col": true,
8      "include_upper_bound_col": true
9    }
10  }
11}

To keep incomplete recent data out of the model while still forecasting from the true end of the series, set ignore_last_periods inside forecast_context.source_data. The value is the number of trailing periods (in the grain of the date dimension) to drop from training. The forecast still projects forward for the full window you requested.

1{
2  "forecast_context": {
3    "model_uuid": "test_mode_id",
4    "source_data": {
5      "ignore_last_periods": 5
6    }
7  }
8}

Time-series models expect one row per period. If the underlying data is sparse, densify the date dimension so missing periods become explicit rows before the forecast trains. Set show_missing_values with enabled: true on the date-dimension field:

1{
2  "expression": {
3    "calculated_field": {
4      "name": "order_date_extended",
5      "expression": "DATE(DATETRUNC(\"month\",[order_date_extended]))",
6      "calculated_dimension_expression": {
7        "dimension_output_type": "SEMANTIC_DIMENSION_TYPE_DATE"
8      },
9      "syntax": "Tua"
10    }
11  },
12  "alias": "TIME DIMENSION COLUMN",
13  "row_grouping": true,
14  "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_NONE",
15  "semantic_dimension_type": "SEMANTIC_DIMENSION_TYPE_DATE",
16  "show_missing_values": { "enabled": true }
17}

To treat the densified gaps as zeros rather than nulls when training, set missing_values inside forecast_context.source_data to FILL_WITH_ZERO:

1{
2  "forecast_context": {
3    "model_uuid": "test_mode_id",
4    "source_data": {
5      "missing_values": { "predefined": "FILL_WITH_ZERO" }
6    }
7  }
8}

The fields below are grouped by mechanism: Predict adds no request-specific fields, while Forecast introduces the forecast_field and forecast_options shapes.

Predict introduces no request-specific fields. A prediction result and its insight fields are referenced with the standard semantic_field expression:

For the full request schema, see Request Reference. For how field references work in general, see Dimensions, Measurements, and Semantic Data Objects.

Predict introduces no request-specific limitations — a prediction is referenced like any other calculated field. The following limits apply to Forecast:

• One non-aggregated date dimension per query. The forecast reads a single date/datetime dimension as its time axis. (A query may contain multiple forecast fields when the window and model are set through the top-level forecast_options object.)
• The time axis must be a date or datetime dimension. Non-date dimensions cannot drive a forecast.
• The measure must be aggregated. The forecast field itself uses SEMANTIC_AGGREGATION_METHOD_USER_AGG; a non-aggregated measure is rejected.
• Confidence output requires a confidence level. If you request interval or bound columns, confidence_level must be set in the forecast context.
• Not combinable with subtotals or grand totals. The forecast changes the granularity of the series, so totals are not supported alongside it.
• Not combinable with table calculations.
• Not combinable with detail rows. Forecasting requires aggregated results.
• Not supported on hard-join models.
• Forecast values cannot be referenced by other calculated fields. The forecast column is terminal — no calc may read from it.

• Semantic Calculated Measurement — Authoring API for defining prediction calcs and their backing models.
• Semantic Calculated Dimension — Authoring API for the prediction-insight dimension fields.
• Semantic Data Object Field — Authoring API for the fields a forecast references.
• Calculated Fields — Referencing model-defined calculated fields by API name; a calculated dimension/measurement can serve as a forecast input.
• Selecting fields — aliasing the measure and date dimension a forecast references.
• Grouping — how the date dimension is grouped to form the time axis.
• Aggregation & Totals — aggregation methods, including USER_AGG; forecasts are mutually exclusive with totals.
• Data 360 Architecture — Where Einstein Studio and bring-your-own-model (BYOM) fit in the platform; background on the models a prediction is backed by.
• Use Predictive Model Calls in Custom Functions — Invoking a deployed Einstein Studio predictive model, including how features map to inputs and how the prediction is returned.
• Request Reference — complete field schema.

j

Get Started

Authoring API

Semantic Query API

Overview

Dimensions, Measurements, and Data Objects

Relationships and Joins

Parameters

Calculated Fields

Functions and Formulas

Filtering

Grouping

Aggregation and Totals

Sorting and Limiting

Predict and Forecast

Logical Views

Shared Dimensions

Currency and Fiscal Handling

SemanticQueryRequest Fields

Semantic Metric Query API