--- schema_version: "1" id: 60bea1b76c4305bef1363d9d9f314df62c2046dad2646173dad6591851410dff title: Predict and Forecast collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/data-cloud/semantic-layer/guides/query-api-in-depth-predict-forecast.md canonical_url: https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-predict-forecast.html source_site: developer.salesforce.com content_type: documentation content_hash: 7a5a9d98d4e906ecec6baf52d1ce757dc15b814db6b037919b368a07b1546d06 products: - Tableau Semantics Layer APIs - Data 360 Developer Documentation --- # Predict and Forecast ## Overview 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 (EDC Models) 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('')`, 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. ### Metadata in the model A prediction is a `Predict`-typed `SemanticCalculatedMeasurement` whose `expression` is `predict('')`, 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](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-calculated-measurement-semanticcalcmeasurement) in the Authoring API for how prediction calcs and their backing models are defined. ### Reference a prediction field by API name 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. ```json { "structured_semantic_query": { "fields": [ { "expression": { "semantic_field": { "name": "Predicted_ssot_Id_pi_prediction_insight" } }, "alias": "Predicted_ssot_Id_pi_prediction_insight", "row_grouping": true } ], "options": { "limit_options": { "limit": 100 } } // ... }, "semantic_model": { "apiName": "test131_2", "semanticCalculatedMeasurements": [ { "apiName": "Predicted_ssot_Id_pi", "dataType": "Number", "expression": "predict('Predicted_ssot_Id_CM_12l_GuB103dbad1_prediction_model5')", "syntax": "Tua", "level": "Row" } // ... ], "semanticPredictionModels": [ { "apiName": "Predicted_ssot_Id_CM_12l_GuB103dbad1_prediction_model5", "modelApiName": "Predicted_ssot_Id_CM_12l_GuB103dbad1", "predict": { "maxRecommendations": 1, "maxTopPredictors": 2, "fieldMapping": [ { "dataCloudFieldApiName": "Account_Revenue_Feature", "semanticFieldReference": { "calculatedFieldApiName": "Account_Revenue_Feature_Calc" } } ] } } ] // ... } } ``` ### Prediction insight fields 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. ```json { "structured_semantic_query": { "fields": [ { "expression": { "semantic_field": { "name": "Predicted_ssot_Id_pi_prediction_insight" } }, "alias": "Predicted_ssot_Id_pi_prediction_insight", "row_grouping": true } ], "options": { "sort_orders": [ { "simple_sort_order": { "sort_by_field_alias": "Predicted_ssot_Id_pi_prediction_insight", "sorting_order": "ASC" } } ], "limit_options": { "limit": 100 } } // ... }, "semantic_model": { "semanticCalculatedDimensions": [ { "apiName": "Predicted_ssot_Id_pi_prediction_insight", "label": "prediction_insight([Predicted_ssot_Id_pi])", "dataType": "Text", "expression": "prediction_insight([Predicted_ssot_Id_pi])", "syntax": "Tua", "level": "Row" } // ... ] // ... } } ``` > **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](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-filtering.md) to restrict the rows returned, and use [grouping](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-grouping.md) so the model scores aggregated results rather than raw detail rows. ## Forecast 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. ### Metadata in the model 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](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-field-semanticdataobjectfield) in the Authoring API. ### The forecast field 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. ```json { "structured_semantic_query": { "fields": [ { "expression": { "table_field": { "name": "test1", "table_name": "SemanticAccount__dlm" } }, "alias": "test1", "row_grouping": true }, { "expression": { "table_field": { "name": "test1", "table_name": "SemanticContact__dlm" } }, "alias": "mes1", "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_MAX" }, { "expression": { "forecast_field": { "dims": [ { "date_dim": { "field_alias": "test1" } } ], "measure": { "field_alias": "mes1" }, "from": { "predefined_date": "LATEST_DATA" }, "to": { "forecast_interval": { "time_unit": "DAYS", "value": 7 } }, "forecast_model": { "ridge_regression": {} } } }, "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG", "alias": "Forecast_sum days" } ] }, "semantic_model": { // ... } } ``` 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`: ```json { "structured_semantic_query": { "fields": [ // ... date dimension aliased "test1", measure aliased "mes1" ... { "expression": { "forecast_field": { "measure": { "field_alias": "mes1" } } }, "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG", "alias": "Forecast_sum days" } ], "forecast_options": { "forecast_from": { "predefined_date": "LATEST_DATA" }, "forecast_to": { "forecast_interval": { "value": 7, "time_unit": "DAYS" } }, "forecast_model": { "holt_winters": {} }, "forecast_context": { "model_uuid": "test_mode_id" } } }, "semantic_model": { // ... } } ``` ### Setting the forecast window 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`. `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: ```json { "forecast_options": { "forecast_from": { "explicit_date": { "date_expression": { "month": 9, "day": 3, "year": 2022 } } }, "forecast_to": { "explicit_date": { "date_expression": { "month": 9, "day": 9, "year": 2022 } } }, "forecast_model": { "holt_winters": {} }, "forecast_context": { "model_uuid": "test_mode_id" } } } ``` ### Choosing a forecast model Set `forecast_model` to one of three 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). - `moirai` — a pre-trained time-series foundation model that projects the series without fitting per-query coefficients. Each is an empty object; the model is selected by which key you set. ```json { "forecast_options": { "forecast_model": { "ridge_regression": {} } } } ``` To use the Moirai model, set the `moirai` key instead: ```json { "forecast_options": { "forecast_model": { "moirai": {} } } } ``` ### Confidence intervals and bounds 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. ```json { "forecast_context": { "model_uuid": "test_mode_id", "confidence_params": { "confidence_level": "LEVEL_95", "include_interval_col": true, "include_lower_bound_col": true, "include_upper_bound_col": true } } } ``` ### Excluding recent periods from training 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. ```json { "forecast_context": { "model_uuid": "test_mode_id", "source_data": { "ignore_last_periods": 5 } } } ``` ### Densifying a sparse series and filling gaps 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: ```json { "expression": { "calculated_field": { "name": "order_date_extended", "expression": "DATE(DATETRUNC(\"month\",[order_date_extended]))", "calculated_dimension_expression": { "dimension_output_type": "SEMANTIC_DIMENSION_TYPE_DATE" }, "syntax": "Tua" } }, "alias": "TIME DIMENSION COLUMN", "row_grouping": true, "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_NONE", "semantic_dimension_type": "SEMANTIC_DIMENSION_TYPE_DATE", "show_missing_values": { "enabled": true } } ``` To treat the densified gaps as zeros rather than nulls when training, set `missing_values` inside `forecast_context.source_data` to `FILL_WITH_ZERO`: ```json { "forecast_context": { "model_uuid": "test_mode_id", "source_data": { "missing_values": { "predefined": "FILL_WITH_ZERO" } } } } ``` ## Reference The fields below are grouped by mechanism: Predict adds no request-specific fields, while Forecast introduces the `forecast_field` and `forecast_options` shapes. ### Predict fields Predict introduces no request-specific fields. A prediction result and its insight fields are referenced with the standard `semantic_field` expression: | Field (wire name) | Type | Required | Description | | --- | --- | --- | --- | | `semantic_field.name` | String | Y* | API name of a model-defined field. Use it to reference a prediction calc or a `prediction_insight_type` / `prediction_insight` / `prediction_insight_impact` field. | ### Forecast fields | Field (wire name) | Type | Required | Description | | --- | --- | --- | --- | | `forecast_field` | ForecastField | N | Expression in `fields[]` that projects a measure over a date dimension. | | `forecast_field.measure.field_alias` | String | Y | Alias of the aggregated numeric measure to forecast. | | `forecast_field.dims[].date_dim.field_alias` | String | Y | Alias of the date/datetime dimension used as the time axis. | | `forecast_options` | ForecastOptions | N | Top-level sibling of `fields[]` holding window, model, and context; alternative to setting them inside `forecast_field`. | | `forecast_from` / `from` | ForecastDate | N | Window start. Defaults to the latest date in the data. | | `forecast_to` / `to` | ForecastDate | Y | Window end (`forecast_interval` or `explicit_date`). | | `explicit_date.date_expression` | DateExpression | N | Exact `year` / `month` / `day`. | | `forecast_interval` | ForecastInterval | N | `value` + `time_unit` (`MINUTES`, `HOURS`, `DAYS`, `WEEKS`, `MONTHS`, `QUARTERS`, `YEARS`). | | `forecast_model` | ForecastModel | N | `holt_winters` (default), `ridge_regression`, or `moirai`. | | `forecast_context.confidence_params` | ConfidenceParams | N | `confidence_level` + `include_interval_col` / `include_lower_bound_col` / `include_upper_bound_col` (each default `false`). | | `forecast_context.source_data.ignore_last_periods` | Integer | N | Trailing periods excluded from training. | | `forecast_context.source_data.missing_values.predefined` | String (enum) | N | Gap handling, e.g. `FILL_WITH_ZERO`. | | `show_missing_values.enabled` | Boolean | N | Per-field densification of the date dimension. | For the full request schema, see [Request Reference](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md). For how field references work in general, see [Dimensions, Measurements, and Semantic Data Objects](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md). ## Limitations 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. ## Related - [Semantic Calculated Measurement](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-calculated-measurement-semanticcalcmeasurement) — Authoring API for defining prediction calcs and their backing models. - [Semantic Calculated Dimension](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-calculated-dimension-semanticcalcdimension) — Authoring API for the prediction-insight dimension fields. - [Semantic Data Object Field](https://developer.salesforce.com/docs/data/semantic-layer/guide/connect-api-in-depth-entities.md#semantic-data-object-field-semanticdataobjectfield) — Authoring API for the fields a forecast references. - [Calculated Fields](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-calculated-fields.md) — Referencing model-defined calculated fields by API name; a calculated dimension/measurement can serve as a forecast input. - [Selecting fields](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md) — aliasing the measure and date dimension a forecast references. - [Grouping](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-grouping.md) — how the date dimension is grouped to form the time axis. - [Aggregation & Totals](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-aggregation.md) — aggregation methods, including `USER_AGG`; forecasts are mutually exclusive with totals. - [Data 360 Architecture](https://developer.salesforce.com/docs/data/data-cloud-dev/guides/dc-architecture.md) — 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](https://developer.salesforce.com/docs/data/data-cloud-code-ext/guides/function/use-predictive-model-in-custom-function.md) — Invoking a deployed Einstein Studio predictive model, including how features map to inputs and how the prediction is returned. - [Request Reference](https://developer.salesforce.com/docs/data/semantic-layer/guide/query-api-in-depth-fields.md) — complete field schema.