Skip to content

Metric Exports#

An export writes the rows of a saved query into a feature group, and a job refreshes them on a schedule or on demand. Feature views, training data, models and pipelines then read the metrics as any other feature group. The examples use the sales semantic project of Define metrics.

Define an export#

An export is dbt's exports: on a saved query, and its Hopsworks settings go under the saved query's config.meta.hopsworks.exports, keyed by the export's name:

saved_queries:
  - name: daily_revenue_by_country
    label: Daily revenue by country
    query_params:
      metrics:
        - revenue
        - orders
      group_by:
        - TimeDimension('metric_time', 'day')
        - Dimension('customer__country')
    exports:
      - name: revenue_by_country_daily
        config:
          export_as: table
          alias: revenue_by_country_daily
    config:
      meta:
        hopsworks:
          exports:
            revenue_by_country_daily:
              schedule: "0 0 2 * * ?"
              version: 1
              lookback: 7 days
              enabled: true
Key Value
exports[].name The export's name: lower case letters, digits and underscores, starting with a letter, at most 63 characters, unique in the semantic project.
exports[].config.export_as table. The saved query's own config.export_as sets it for all its exports.
exports[].config.alias The feature group's name; the export's name when not set.
exports[].config.schema Not used: the feature group is created in the project's feature store.
schedule A Quartz cron expression with 0 seconds, such as 0 0 2 * * ? for 02:00 every day. Without it, the export runs only when a Data Owner runs it.
version The feature group's version, 1 by default.
lookback <count> <granularity> with a granularity from second to year, such as 7 days, 3 months or 1 year: each run replaces only the rows of that window, see Refreshes. Without it, each run replaces every row.
enabled false takes the schedule off the export's job and refuses runs; true by default.

Exports compile with the build, and take effect when that build answers queries: at once in FOLLOW mode, on a promote in PINNED mode, see Serving modes.

Validation#

A compile checks every export, and each problem is an issue at the export's file and line, as for any validation rule:

RULE Level Reports
EXPORT_NAME ERROR An export name that is not a feature group name, or that two saved queries define.
EXPORT_AS ERROR An export without export_as, or with export_as: view or anything but table.
EXPORT_TARGET ERROR A feature group name, the alias or the export's name, that is not valid, or that two exports write; a version below 1. A WARNING for a schema, which is not used.
EXPORT_SCHEDULE ERROR A schedule that is not a Quartz cron expression, is longer than 255 characters, or does not have 0 as its seconds field.
EXPORT_LOOKBACK ERROR A lookback that is not <count> <granularity> with a count of at least 1, or a saved query that does not group by metric_time at a grain, the column the window is cut on.
EXPORT_KEYS ERROR A saved query without group-bys: they are the feature group's primary key and event time.
EXPORT_SETTINGS ERROR A config.meta.hopsworks.exports that does not map export names to settings, or that has settings for a name that is not an export of the saved query.
EXPORT_SERVING WARNING A saved query whose rows can depend on when it runs, through CURRENT_DATE, now() or a function the compiler does not know, such as a UDF: its exports are refreshed, and never answer queries.

The feature group#

The export's first run creates the feature group, as the semantic project's owner, and records its id. For revenue_by_country_daily:

Feature Type Role
metric_time__day timestamp Event time
customer__country string Primary key
revenue double
orders bigint
  • The features are the saved query's group-bys and metrics, named as the columns of a query.
  • The primary key is every group-by except the metric_time one, whose column is the event time; when metric_time is the only group-by, it is the primary key too. A date part, such as metric_time__extract_dow, is a key column, not the event time.
  • Without a metric_time group-by, the feature group has no event time.
  • It is a Delta feature group in the offline feature store only, without statistics.
  • Its description is the saved query's description, or Export <export> of saved query <saved query> of semantic project <semantic project>.
  • Each successful run links it to the feature groups the saved query reads as its provenance parents.

Later runs write the feature group the first run created, and no other. A change of alias or version points the export at a new feature group, which its next run creates; the old one stays. A change of the saved query's metrics or group-bys changes the columns, which the existing feature group refuses: raise version with it. A deleted export feature group is created again by the next run.

import hopsworks


project = hopsworks.login()
fs = project.get_feature_store()
fg = fs.get_feature_group("revenue_by_country_daily", version=1)
print(fg.read().head())

Refreshes#

Every run runs the whole saved query, past the result cache and never from an export, and replaces rows of the feature group in one commit that keeps the feature group and its id.

Export A run replaces
Without lookback Every row.
With lookback The rows whose metric_time is at or after the window start; the rows before it stay.
  • The window starts at the run's logical time minus the lookback, truncated to the grain of metric_time; weeks start on Monday.
  • A scheduled run's logical time is the start of its schedule interval, the schedule's previous fire time. The run of 0 0 2 * * ? at 02:00 on 2026-11-07 has the logical time 2026-11-06 02:00, so with lookback: 7 days and a daily metric_time it replaces the rows from 2026-10-30 00:00 on.
  • A run started by hand takes the start of the schedule's latest complete interval, the logical time of the last scheduled run, or the time it starts when the export has no schedule.
  • Groups that vanished from the window are removed, and an empty result empties the window.
  • Cumulative and offset metrics in the window see their full history, since the whole saved query runs.
  • The first run writes every row.
  • A metric_time at a custom granularity of the time spine cannot be truncated, so such a run replaces every row and says so in its message.

A run writes nothing when the result reaches the gateway's row cap, TRUNCATED, since the rows may be incomplete, or when the target feature group exists and the export did not create it, TARGET_EXISTS.

Who runs an export#

Each export has a Python job, semantic-export-<semantic project id>-<export>, that Hopsworks creates in the python-feature-pipeline environment and keeps in step with the export:

  • The job runs as the semantic project's owner, who must be a Data Owner of the project, as creating feature groups needs, and whose project role must allow Semantic layer: Run exports. The owner is the member who registered the semantic project, until a Data Owner transfers it to another Data Owner. While the owner is not a Data Owner, has left the project, or has a custom project role that removes that permission, the export has no job and its status is OWNER_NOT_DATA_OWNER.
  • Its script is SemanticExports/semantic_export.py, in a dataset that only Data Owners can edit.
  • Its schedule is the export's: runs that the schedule missed are not made up, and runs of one export never overlap.
  • Hopsworks updates the job right after a build with changed exports starts answering queries, and checks every job every two minutes.
  • An export the served build no longer defines loses its job, and its feature group stays; so does a deleted semantic project.
  • A transfer of the semantic project replaces the jobs with jobs of the new owner at once, with the same names and schedules. Removing the owner from the project hands the semantic project over in the same request, see When the owner leaves the project.

The job needs the Hopsworks 5.3 library in the python-feature-pipeline environment; with an older one, the run fails before writing and the job's log says update the python-feature-pipeline environment to 5.3.

List exports and their status#

hops semantic export list sales
NAME                      SAVED QUERY               FEATURE GROUP                SCHEDULE     LOOKBACK  STATUS     LAST RUN              ROWS  MESSAGE
------------------------  ------------------------  ---------------------------  -----------  --------  ---------  --------------------  ----  -----------------------------------------------
revenue_by_country_daily  daily_revenue_by_country  revenue_by_country_daily v1  0 0 2 * * ?  7 days    SUCCEEDED  2026-11-06T02:00:00Z  22    Replaced the rows from 2026-10-30T00:00:00Z on.
import hopsworks


project = hopsworks.login()
sales = project.get_semantic_layer_api().get_project("sales")
for export in sales.exports():
    print(export.name, export.feature_group_id, export.last_status, export.last_rows)
revenue_by_country_daily 501 SUCCEEDED 22

LAST RUN is the last run's logical time, and ROWS the rows it wrote: with a lookback, those of the window. In the UI, the Exports card of the semantic project's overview lists each export with its saved query, its feature group, which links to the feature group once a run has created it, its schedule and lookback, or On demand and Full refresh, its status, its last run and rows, its message, and a link to its job. The status badge explains the status on hover. A saved query's sheet lists its exports with their feature groups and statuses under Exports.

hops semantic export list sales --json prints every field of SemanticExport, and the list_exports tool of the MCP server lists them for an agent.

Status Meaning Fix
NEVER_RUN No run has reported since the export was defined.
RUNNING A run is going on. A run whose job ended without reporting reads FAILED, with The run ended without reporting a result; see the job's logs.
SUCCEEDED The last run wrote the rows; the message says which.
FAILED The saved query or the write failed; the message holds the error. Fix the cause and run again.
TRUNCATED The saved query returned as many rows as the gateway's row cap, so the run wrote nothing. Narrow the saved query with a filter, fewer group-bys or a coarser grain, or raise the semantic-gateway value maxRows.
TARGET_EXISTS A feature group of the target's name and version exists that the export did not create, so the run wrote nothing. See Target exists.
OWNER_NOT_DATA_OWNER The semantic project has no owner, or its owner is not a Data Owner of the project or has a custom project role that removes Semantic layer: Run exports, so the export has no job. Transfer the semantic project to a Data Owner whose role allows Run exports, or give the owner such a role.
JOB_ERROR Hopsworks could not create or update the job; the message says why, and it tries again every two minutes. Fix the cause, such as a job of the export's name that the export did not create.
DISABLED The definition sets enabled: false: the job has no schedule and runs are refused.

A run that started under an earlier definition of the export reports into the message only, as A run of an earlier definition of this export (generation <n>) reported <status>, and leaves the status as it is.

Run an export now#

hops semantic export run sales revenue_by_country_daily --wait
Export revenue_by_country_daily SUCCEEDED: 22 rows. Replaced the rows from 2026-10-30T00:00:00Z on.
import hopsworks


project = hopsworks.login()
sales = project.get_semantic_layer_api().get_project("sales")
execution = sales.run_export("revenue_by_country_daily", wait=True)
print(execution.state)

Starting a run with an API key needs the JOB scope, unlike the other export calls, which need FEATURESTORE. This run started at 10:15 on 2026-11-07, and replaced the window of the 02:00 run that day, see Refreshes. Without --wait, the CLI prints Started export revenue_by_country_daily (execution #42). and returns. In the UI, Run now on the Exports card starts the run; it shows to Data Owners, and is disabled with the reason for an export that cannot run. Starting a run while another run of the export goes on is refused with SEMANTIC_LAYER_EXPORT_NOT_RUNNABLE, naming the execution in progress.

Error Code Status Meaning
SEMANTIC_LAYER_FORBIDDEN 600003 403 The caller is not a Data Owner of the project.
SEMANTIC_LAYER_EXPORT_NOT_FOUND 600020 404 The build that answers queries defines no export of that name.
SEMANTIC_LAYER_EXPORT_NOT_RUNNABLE 600021 409 The export is disabled, its owner is not a Data Owner, Hopsworks has not created its job yet, or a run is in progress; the message says which.

A run that wrote nothing fails its job execution: with --wait, the CLI exits with The run of export <export> failed: ... and points to hops semantic export list, and run_export(..., wait=True) raises JobExecutionException.

Target exists#

An export writes only a feature group it created, so a feature group of the same name and version that it did not create stops it:

Feature group revenue_by_country_daily version 1 exists and export 'revenue_by_country_daily' did not create it, so nothing was written. Delete it, or give the export another alias or version.
  • Delete that feature group when nothing needs it, then run the export again.
  • Or change the export's alias or version in the YAML and compile; the next run creates the new feature group.

Answer queries from an export#

When an export holds the exact rows a query asks for, read from the data its sources hold now, the gateway reads the rows from the export's feature group instead of computing them from the sources. It never serves rows that differ from what the sources would give: when any condition below does not hold, the query runs on the sources.

saved_queries:
  - name: monthly_revenue_by_country
    query_params:
      metrics:
        - revenue
        - orders
      group_by:
        - TimeDimension('metric_time', 'month')
        - Dimension('customer__country')
    exports:
      - name: revenue_by_country_monthly
        config:
          export_as: table
    config:
      meta:
        hopsworks:
          exports:
            revenue_by_country_monthly:
              schedule: "0 0 3 * * ?"

After a run of revenue_by_country_monthly, and before any write to orders or customers:

curl -s -D - -o /dev/null -X POST -H "Authorization: ApiKey $HOPSWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"savedQuery": "monthly_revenue_by_country", "orderBy": [{"name": "revenue", "descending": true}], "limit": 5}' \
  "https://hopsworks.example.com/semantic-layer/v1/projects/7/query"
HTTP/1.1 200 OK
X-Semantic-Definition: 8c1f0e2b9d7a4c35e6f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7
X-Semantic-Source-Versions: {"11":42,"12":7}
X-Semantic-Served-From: export:revenue_by_country_monthly
X-Semantic-Export-Feature-Group: 503
X-Semantic-Feature-Groups: 11,12
X-Semantic-Cache: miss

When an export answers#

All of these hold:

  • The export has no lookback, so each run replaces every row.
  • Its saved query has no limit, order_by or group limit, no filter or time range relative to the current date or time, and calls no function whose value depends on when it runs, such as CURRENT_DATE, now() or random(), and no function the compiler does not know, such as a UDF. The build warns with EXPORT_SERVING of a saved query whose result may depend on when it runs, through CURRENT_DATE, now() or a function the compiler does not know; it gives no warning for limit, order_by or a group limit.
  • The query asks for the saved query's rows: the same metrics, the same group-bys at the same grains, and the same filters and time range, whether it names the saved query or spells the same query out. It may add having, order_by and limit over the saved query's columns, and nothing else: an extra filter is applied before the metrics are computed, so it is not a filter on the export's rows.
  • The saved query's definition, its SQL on the build that answers the query, is the one the export's last run read.
  • Every feature group the query reads, the time spine included, is a Delta feature group at the commit the last run read, and the export's feature group is at the commit that run wrote.
  • No Trino row filter, column mask or denied column applies to a source or to the export's feature group, under the rules in force when the run wrote it and now. New Trino rules count from a minute after Hopsworks publishes them and Trino has loaded them.
  • Every source is the project's own feature group or one shared with the project whole, not with only some of its features, and the caller can read the export's feature group.

The export stops answering as soon as one of these changes: a write to a source, another write to the export's feature group, a change of the saved query or of what it reads, or a new access rule. The next successful run makes it answer again. A run records what it read and wrote only when the export has no lookback, every source is a Delta feature group, and no row filter, column mask or denied column applies; the other exports still run, and never answer queries.

Which clients it applies to#

Client Answered from an export
REST query: Python, the CLI, the UI, the agent tools Yes, with the headers below.
Arrow Flight SQL: dbt-sl-sdk, ADBC, JDBC with dbt's JDBC dialect Yes, without headers; not with SQL around the call or metric aliases.
SQL over the BI tables No.
  • The query history records servedFrom: export:<export> for each answer read from an export, on every surface.
  • The result cache keys an answer from an export by the export's commit as well as the sources'.
  • When Trino refuses to read the export's feature group before any row is sent, the gateway answers from the sources.
Header Value
X-Semantic-Served-From export:<export>, on an answer read from an export.
X-Semantic-Export-Feature-Group The id of the export's feature group.
X-Semantic-Source-Versions The Delta version of each source, by feature group id, that the rows were computed from.
X-Semantic-Definition The definition fingerprint of the saved query, on every query that names one.

"useExports": false in a REST query body computes the rows from the sources, as export runs do. The Python client and the CLI do not take this option.

Over REST#

The exports are under /hopsworks-api/api/project/<project id>/semantic/projects/<semantic project id>/:

Method Path Does
GET exports Lists the exports of the build that answers queries, with their state. Data Owners and Data Scientists; an API key needs the FEATURESTORE scope.
POST exports/<export>/run Starts the export's job and answers {"jobName", "executionId"}. Data Owners; an API key needs the JOB scope.
PUT exports/<export>/status The job's report of a run. Accepted only from a running execution of the export's job.
{
  "items": [
    {
      "name": "revenue_by_country_daily",
      "savedQuery": "daily_revenue_by_country",
      "exportAs": "TABLE",
      "featureGroup": "revenue_by_country_daily",
      "featureGroupId": 501,
      "version": 1,
      "schedule": "0 0 2 * * ?",
      "lookback": "7 days",
      "enabled": true,
      "jobName": "semantic-export-7-revenue_by_country_daily",
      "lastStatus": "SUCCEEDED",
      "lastRun": "2026-11-06T02:00:00Z",
      "lastRows": 22,
      "lastMessage": "Replaced the rows from 2026-10-30T00:00:00Z on."
    }
  ],
  "count": 1
}

The gateway's saved-queries listing, the EXPORTS column of dbt's semantic_layer.saved_queries(), and the exports field of GraphQL's savedQueries carry each saved query's exports too, see Connect dbt clients.