Skip to content

Saved Queries#

A saved query is a metric query defined by name in the semantic project's YAML: its metrics, group-bys, filters, order and limit. It compiles with the build, and every client runs it by name, refined with its own group-bys, filters or limit. The examples use the sales semantic project of Define metrics.

Define a saved query#

Saved queries go under saved_queries: in any YAML file under model-paths:

saved_queries:
  - name: revenue_by_country
    label: Revenue by country
    description: Monthly revenue and orders per country, cancelled orders left out.
    query_params:
      metrics:
        - revenue
        - orders
      group_by:
        - TimeDimension('metric_time', 'month')
        - Dimension('customer__country')
      where:
        - "{{ Dimension('order__status') }} != 'cancelled'"
      order_by:
        - TimeDimension('metric_time', 'month')
        - Metric('revenue').descending(True)
    config:
      meta:
        hopsworks:
          tags:
            domain: "sales"
Key Value
name Lower case letters, digits and underscores, unique among the saved queries.
label, description Shown in the UI and in the listings; the label is the name when not set.
query_params.metrics Metric names.
query_params.group_by Dimension('<entity>__<dimension>'), TimeDimension('<name>', '<grain>') or Entity('<entity>'); a call takes .grain('<grain>') and .date_part('<part>').
query_params.where Filters in the call syntax of queries, combined with AND.
query_params.order_by Metrics, as Metric('<metric>'), and group-bys of the saved query; .descending(True) sorts descending.
query_params.limit The most rows to return.
config.meta.hopsworks.tags Tags, tag schema name to value, checked against their schemas as the tags of a metric are.

A compile checks each saved query, its metrics, group-bys, order and filters, under the SAVED_QUERY and WHERE_FILTER rules, then plans it once, so a saved query that would fail is an error at its file and line. A saved query's exports write its rows into feature groups, see Export to a feature group.

List the saved queries#

hops semantic saved-queries sales
NAME                LABEL               METRICS         GROUP-BYS
------------------  ------------------  --------------  ------------------------------------
revenue_by_country  Revenue by country  revenue,orders  metric_time__month,customer__country
import hopsworks


project = hopsworks.login()
sales = project.get_semantic_layer_api().get_project("sales")
for saved in sales.list_saved_queries():
    print(saved.name, saved.metrics, saved.group_by, saved.order_by)
revenue_by_country ['revenue', 'orders'] ['metric_time__month', 'customer__country'] [{'name': 'metric_time__month', 'descending': False}, {'name': 'revenue', 'descending': True}]

The listing names each group-by and order-by as a query does, such as metric_time__month. hops semantic saved-queries sales --json prints every field, and the gateway lists them at GET saved-queries:

{
  "buildId": 12,
  "stale": false,
  "savedQueries": [
    {
      "name": "revenue_by_country",
      "label": "Revenue by country",
      "description": "Monthly revenue and orders per country, cancelled orders left out.",
      "metrics": ["revenue", "orders"],
      "groupBy": ["metric_time__month", "customer__country"],
      "where": ["{{ Dimension('order__status') }} != 'cancelled'"],
      "orderBy": [{"name": "metric_time__month"}, {"name": "revenue", "descending": true}],
      "limit": null,
      "tags": {"domain": "sales"},
      "exports": []
    }
  ]
}

In the UI, the Saved queries card of the semantic project's overview lists them; clicking one shows its metrics, group-bys, filters, order, limit and tags, and the status of its exports.

Run a saved query#

hops semantic query sales --saved-query revenue_by_country -o csv
metric_time__month,customer__country,revenue,orders
2026-01-01,SE,140.25,2
2026-01-01,DE,60.0,1
2026-02-01,SE,30.0,1
2026-02-01,DE,15.5,1
2026-03-01,US,55.75,1
import hopsworks


project = hopsworks.login()
sales = project.get_semantic_layer_api().get_project("sales")
df = sales.query(saved_query="revenue_by_country")

--saved-query takes the place of --metrics, and saved_query= of metrics; giving both is refused. An unknown saved query is 404 SEMANTIC_LAYER_NOT_FOUND:

Error: Semantic layer request on 'sales' failed (HTTP 404, SEMANTIC_LAYER_NOT_FOUND): no saved query 'revenue_by_region'

In the UI, Run in the saved query's sheet opens the query workbench on the saved query and runs it. Its metrics are fixed and its filters shown; the group-bys, order and limit picked there replace its own, and added filters narrow it.

Over REST, the query body takes "savedQuery": "<name>" and no metrics, see Query over REST.

Refine a saved query#

A query of a saved query can change it:

Part A query that gives it
Group-bys Replace the saved ones. An empty list of group-bys asks for totals; leaving them out keeps the saved ones.
Order Replaces the saved order. A saved order by a group-by the query's group-bys leave out is dropped.
Limit Replaces the saved limit.
where and structured filters Are added to the saved filters, combined with AND.
having, time range, offset, group limit Apply as in any query; a saved query has none of its own.
Metrics Are refused: a saved query's metrics are its own.
hops semantic query sales --saved-query revenue_by_country --group-by customer__country -o csv
customer__country,revenue,orders
SE,170.25,3
DE,75.5,2
US,55.75,1

The saved order by month is dropped with the month, and the order by revenue, descending, stays.

hops semantic query sales --saved-query revenue_by_country \
  --where "{{ Dimension('customer__country') }} = 'SE'" -o csv
metric_time__month,customer__country,revenue,orders
2026-01-01,SE,140.25,2
2026-02-01,SE,30.0,1

The totals of a saved query need an empty list of group-bys, which the CLI sends as --group-by "":

hops semantic query sales --saved-query revenue_by_country --group-by ""

In Python, group_by=[]:

import hopsworks


project = hopsworks.login()
sales = project.get_semantic_layer_api().get_project("sales")
print(sales.query(saved_query="revenue_by_country", group_by=[]))
   revenue  orders
0    301.5       6

Over REST, the body is {"savedQuery": "revenue_by_country", "groupBy": []}.

Show the SQL#

hops semantic sql sales --saved-query revenue_by_country
hops semantic query sales --saved-query revenue_by_country --explain
import hopsworks


project = hopsworks.login()
sales = project.get_semantic_layer_api().get_project("sales")
print(sales.sql(saved_query="revenue_by_country"))

Both print the Trino SQL of the saved query, refined by the same options as a query, without running it. In the UI, Show SQL in the saved query's sheet shows it under the saved query's definition.

Export to a feature group#

An export writes a saved query's rows into a feature group, which a job refreshes on a schedule or when a Data Owner runs it:

saved_queries:
  - name: daily_revenue_by_country
    query_params:
      metrics:
        - revenue
      group_by:
        - TimeDimension('metric_time', 'day')
        - Dimension('customer__country')
    exports:
      - name: revenue_by_country_daily
        config:
          export_as: table
    config:
      meta:
        hopsworks:
          exports:
            revenue_by_country_daily:
              schedule: "0 0 2 * * ?"
              lookback: 7 days

The feature group is keyed by customer__country, with metric_time__day as its event time. Metric exports covers the settings, the refreshes, who the job runs as, and the statuses.

From an agent#

The Hopsworks MCP server has two READ tools for saved queries, among its semantic layer tools:

Tool Arguments Returns
list_saved_queries semantic_project CSV with the columns name, label, description, metrics and group_by, the last two space-separated.
query_saved_query semantic_project, name, then group_by, where and limit (optional) CSV of the rows. group_by replaces the saved group-bys, where adds to the saved filters, and limit, 100 by default, replaces the saved limit.
{"semantic_project": "sales", "name": "revenue_by_country", "group_by": ["customer__country"]}
customer__country,revenue,orders
SE,170.25,3
DE,75.5,2
US,55.75,1

Dashboards from a saved query#

A Superset dashboard can chart a saved query instead of a list of metrics, see Dashboards in Superset for the prerequisites:

hops semantic dashboard sales --saved-query revenue_by_country
Created dashboard 14 "sales: Revenue by country": https://<hopsworks host>/hopsworks-api/superset/dashboard/14/?projectId=119
import hopsworks


project = hopsworks.login()
sales = project.get_semantic_layer_api().get_project("sales")
dashboard = sales.create_dashboard(saved_query="revenue_by_country")
print(dashboard["url"])

The dashboard has the layout of a dashboard of metrics, over the saved query's metrics, and is built on a dataset of the saved query's table on your connection, so every chart reads the saved query's rows, under its filters. The breakdown table and the filters use the saved query's categorical dimensions and entities, customer__country here. The title is <semantic project>: <saved query label> unless --title or title= gives one.

In the UI, Create dashboard in the saved query's sheet opens the Create a Superset dashboard dialog on the saved query. Over REST, the dashboard request takes {"savedQuery": "<name>", "title": "<title>"} in place of metrics and groupBy.

Error Status Meaning
SEMANTIC_LAYER_NOT_FOUND 404 No saved query of that name in the build that answers queries.
SEMANTIC_LAYER_ILLEGAL_ARGUMENT 400 Metrics or group-bys given with the saved query, or a saved query with no metrics or more than eight.

The other errors are those of a dashboard of metrics.

The Superset table of a saved query#

Each saved query of a semantic project is a table on your semantic connection in Superset, in the semantic project's schema, named as the saved query, such as revenue_by_country, next to the metrics table. A chart on a dataset of it can pick:

  • the saved query's metrics, and no others, each as SUM(<metric>);
  • its group-bys.

The rows are the saved query's metrics and group-bys under the saved query's filters, with the chart's filters added; the saved query's order and limit do not apply, the chart's do, see The tables. The connection lists the tables of the build that answers queries, so a saved query added or removed by a new build appears or disappears with it.