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('<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.

Metadata in the model

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.

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.

{
  "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.

{
  "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 to restrict the rows returned, and use grouping 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 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.

{
  "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:

{
  "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:

{
  "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.

{
  "forecast_options": {
    "forecast_model": { "ridge_regression": {} }
  }
}

To use the Moirai model, set the moirai key instead:

{
  "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.

{
  "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.

{
  "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:

{
  "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:

{
  "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:

Forecast fields

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

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 — 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.