Skip to content

hopsworks.semantic_layer #

SemanticBuild dataclass #

One compile of a semantic project's definitions, immutable once it ends.

status is COMPILING while the compile runs, then VALID, INVALID when the definitions have errors, or FAILED when the compile could not run. Only a VALID build can serve queries. git_commit is the commit the definitions were read at, and None outside a git repository. fingerprint identifies the files compiled, so compiling unchanged files returns their existing build. issues is filled by SemanticProject.get_build and is None on builds from a listing.

SemanticExport dataclass #

A saved query's export: a feature group that a job fills with the saved query's rows, on a schedule or on demand.

An export is defined in the YAML, under a saved query's exports: with export_as: table; its schedule, version, lookback and whether it is enabled are under the saved query's config.meta.hopsworks.exports.<export name>. feature_group and version name the Delta feature group it writes, the export's alias or else its name. feature_group_id is the feature group its first run created, None before that run; later runs write that feature group and no other, so a feature group of that name the export did not create fails the run with TARGET_EXISTS. Every group-by except metric_time is the feature group's primary key, and metric_time its event time. schedule is a Quartz cron expression, None to run only through SemanticProject.run_export. lookback, such as 7 days, makes each run replace only the rows whose metric_time is at or after the run's logical time minus the lookback, truncated to the metric_time grain; without it a run replaces every row. Either way the run computes the whole saved query and replaces the rows in one commit, keeping the feature group and its id. last_status is NEVER_RUN, RUNNING, SUCCEEDED, FAILED, TRUNCATED (the result reached the gateway's row cap, so it may be incomplete and nothing was written), TARGET_EXISTS, OWNER_NOT_DATA_OWNER (the semantic project has no owner, or its owner is not a Data Owner or has a project role that does not allow Semantic layer: Run exports, so the export has no job), JOB_ERROR or DISABLED, and last_message says more. last_rows is the number of rows the last run wrote.

SemanticGroupBy dataclass #

A dimension, time dimension or entity that metrics can be grouped and filtered by.

name is the qualified name to pass as a group-by, such as listing__country_latest; a time dimension also takes a grain suffix, as in metric_time__month. type is CATEGORICAL, TIME or ENTITY. entity_path is the chain of entities that qualifies the name, empty only for metric_time. dimension is the name the dimension has in its semantic model. For a time dimension, granularity is its finest grain and queryable_granularities every grain it can be grouped by, and date_parts_supported says whether date parts such as dow can be extracted from it. event_time is set on the time dimension linked to the event_time column of its feature group.

SemanticIssue dataclass #

A validation error or warning found while compiling a semantic project.

level is ERROR or WARNING; only errors make a build INVALID. rule is the validation that raised it, such as UNIQUE_NAMES. file, line and column locate it in the YAML, with file relative to the project's root path, and are None when the issue is not tied to one place. element names the definition it concerns, such as metric:bookings.

SemanticMetric dataclass #

A metric a semantic project serves.

type is SIMPLE, RATIO, DERIVED, CUMULATIVE or CONVERSION. agg is the aggregation of a simple metric, such as SUM or COUNT_DISTINCT, and None for the other types. queryable_granularities are the grains metric_time can be grouped by for this metric. requires_metric_time is set when every query of the metric must group by metric_time, because its value is defined per period: a cumulative metric with a window or grain-to-date, or a derived metric with an offset input. filter is the metric's own filter, applied to every query of it. tags are the schematised tags its definition sets in config.meta.hopsworks.tags, tag schema name to value, checked against the tag schemas when the project compiles.

SemanticProject #

Metric definitions in a HopsFS directory, compiled into builds and queried through the semantic gateway.

Get one with SemanticLayerApi.get_project. Discovery and queries are answered from the current build, which is the last valid one; an answer from a build older than the newest compile logs a warning.

Group-bys are qualified names such as "listing__country_latest" or "metric_time__month". A grain suffix from __nanosecond to __year sets the grain of a time dimension, and a suffix __extract_<part>, with <part> one of year, quarter, month, day, dow and doy, extracts a date part from it. A dict {"name": "metric_time", "grain": "month"} or {"name": "metric_time", "date_part": "dow"} says the same explicitly.

Compile, discover and query
import hopsworks

project = hopsworks.login()
sl = project.get_semantic_layer_api()
sales = sl.get_project("sales")

sales.compile()
print([m.name for m in sales.list_metrics()])
print([d.name for d in sales.dimensions(metrics=["revenue"])])

df = sales.query(
    metrics=["revenue", "order_count"],
    group_by=["metric_time__month", "customer__country"],
    where=["{{ Dimension('customer__country') }} != 'XX'"],
    order_by=["-revenue"],
    limit=100,
)

created property #

created: str | None

When the semantic project was registered, as an ISO-8601 UTC timestamp.

creator property #

creator: str | None

Username of the member who registered the semantic project, and its first owner.

current_build_id property #

current_build_id: int | None

Id of the build that answers queries, or None until a build is valid.

deployment_mode property #

deployment_mode: str | None

FOLLOW to serve every new valid build, or PINNED to serve a build until another is promoted.

format property #

format: str | None

Format of the definitions: DBT, NATIVE, MANIFEST_JSON, or AUTO to detect it from the files under root_path.

git_repository_id property #

git_repository_id: int | None

Id of the Hopsworks git repository holding root_path, whose pulls and checkouts recompile the project.

id property #

id: int | None

Id of the semantic project, also the environmentId dbt Semantic Layer clients connect with.

latest_build property #

latest_build: SemanticBuild | None

The newest build, which may be invalid or still compiling.

missing_mandatory_tags property #

missing_mandatory_tags: list[str]

Names of the mandatory semantic project tags the project lacks, empty when it has them all or on a community cluster.

name property #

name: str | None

Name of the semantic project, unique within its Hopsworks project.

owner property #

owner: str | None

Username of the member the export jobs run as, or None when that member's account no longer exists.

Hand it to another Data Owner with transfer_ownership.

project_id property #

project_id: int | None

Id of the Hopsworks project that owns the semantic project.

root_path property #

root_path: str | None

HopsFS directory the definitions are read from, for example a dbt project.

add_tag #

add_tag(name: str, value: Any) -> None

Attach a schematised tag to the semantic project, or replace its value.

The tag schema name must exist, and value must match it; administrators create the schemas. The value can be any JSON value: a string, number, boolean, list or object. Schematised tags need Hopsworks Enterprise; other editions refuse the request.

sales.add_tag("ownership", {"owner": "finance", "certified": True})
PARAMETER DESCRIPTION
name

Name of the tag schema.

TYPE: str

value

Value of the tag.

TYPE: Any

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the schema does not exist, the value does not match it, or the backend encounters another error.

compatible_metrics #

compatible_metrics(
    group_by: str
    | dict[str, Any]
    | Sequence[str | dict[str, Any]],
) -> list[str]

Names of the metrics that can be grouped by all of the given group-bys.

PARAMETER DESCRIPTION
group_by

Group-bys, as qualified names or dicts.

TYPE: str | dict[str, Any] | Sequence[str | dict[str, Any]]

RETURNS DESCRIPTION
list[str]

The metric names.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request, for example for an unknown group-by.

compile #

compile(wait: bool = True) -> SemanticBuild

Compile the definitions under root_path into a build.

In FOLLOW mode a valid build starts answering queries at once; in PINNED mode it waits for promote. An invalid build never answers queries, so the project keeps serving its last valid build.

PARAMETER DESCRIPTION
wait

Whether to block until the compile ends; without it the build is returned in status COMPILING.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
SemanticBuild

The build, in a final status when wait is set.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticBuildException

When wait is set and the build is INVALID or FAILED; its issues say what to fix.

hopsworks.client.exceptions.SemanticLayerException

When wait is set and the compile has not ended after ten minutes.

hopsworks.client.exceptions.RestAPIError

If the backend encounters an error when handling the request.

connection_info #

connection_info(
    ca_path: str | None = None,
) -> dict[str, Any]

What a dbt Semantic Layer client needs to reach this semantic project, apart from an API key.

dbt-sl-sdk takes the Hopsworks host, an API key and environment_id, with the env variables set; the Arrow Flight SQL JDBC driver takes jdbc_url and the API key as token. GraphQL at graphql_url serves metadata (metrics, dimensions, measures, entities, saved queries, granularities) and compileSql; queries run over Arrow Flight SQL at adbc_url or jdbc_url, or over REST. So dbt-sl-sdk's metrics(), dimensions(), compile_sql(), query() and dimension_values() work, the last two over ADBC, and a query sent as a GraphQL operation is refused. When the cluster's certificates come from a private CA, the CA is written to ca_path, and env also points SSL_CERT_FILE and REQUESTS_CA_BUNDLE at it.

Query the semantic project with dbt-sl-sdk
import os

info = sales.connection_info()
# dbt-sl-sdk reads its DBT_SL_* variables when it is imported, so set them first.
os.environ.update(info["env"])
from dbtsl import SemanticLayerClient

dbt = SemanticLayerClient(
    environment_id=info["environment_id"],
    auth_token=api_key,
    host="hopsworks.example.com",
)
PARAMETER DESCRIPTION
ca_path

File to write the CA certificate to; by default hopsworks_semantic_<project id>_<semantic project id>_ca.pem in the temporary directory.

TYPE: str | None DEFAULT: None

RETURNS DESCRIPTION
dict[str, Any]

A dict with environment_id, graphql_url, adbc_url, jdbc_url, flight_host, flight_port, env (environment variable name to value) and ca_path, which is None without a private CA.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the backend encounters an error when handling the request.

create_dashboard #

create_dashboard(
    metrics: str | Sequence[str] | None = None,
    group_by: str | Sequence[str] | None = None,
    title: str | None = None,
    saved_query: str | None = None,
) -> dict[str, Any]

Build a Superset dashboard of the metrics, owned by the caller, on the caller's own semantic connection in Superset.

Each member has one such connection per Hopsworks project, on which every semantic project of the project is a schema named after it. The charts read a dataset of the metrics table in this semantic project's schema, which runs each chart as a metric query with the caller's access, so they show the numbers query returns. The dashboard has a line chart of each metric over metric_time, a big number with a trendline for the first metric, a table broken down by a dimension, and native filters. A dashboard of the same title that the caller owns is updated in place, keeping its id and URL, so calling this again does not duplicate it. A dashboard from a saved query is built on the saved query's own table in that schema, with its metrics and group-bys.

PARAMETER DESCRIPTION
metrics

Metric names, one to eight; leave them out with saved_query.

TYPE: str | Sequence[str] | None DEFAULT: None

group_by

Dimensions for the breakdown table and the native filters, such as customer__country; without them, the first categorical dimension the metrics share.

TYPE: str | Sequence[str] | None DEFAULT: None

title

Title of the dashboard; without one, <semantic project>: <metric labels>, or <semantic project>: <saved query label> for a saved query.

TYPE: str | None DEFAULT: None

saved_query

Name of a saved query whose metrics and group-bys the dashboard shows, instead of metrics and group_by.

TYPE: str | None DEFAULT: None

RETURNS DESCRIPTION
dict[str, Any]

The dashboard's Superset id, its title, and the url that opens it through Hopsworks, such as https://<host>/hopsworks-api/superset/dashboard/12/?projectId=119.

RAISES DESCRIPTION
ValueError

If neither metrics nor saved_query is given, or saved_query is given with metrics or group_by.

hopsworks.client.exceptions.SemanticLayerException

With status 400 for an unknown metric or group-by or metrics with no time dimension in common, and 409 when the project has no valid build. With status 404 and error_code 600001 (SEMANTIC_LAYER_NOT_FOUND) for an unknown saved query. With status 503 and error_code 600014 (SEMANTIC_LAYER_DASHBOARDS_DISABLED) when semantic dashboards are not available: Superset 6, or Superset, its semantic dashboards or the project's Superset service off. With status 503 and error_code 600015 (SEMANTIC_LAYER_SUPERSET_ERROR) when Superset did not answer.

delete_tag #

delete_tag(name: str) -> None

Remove a tag from the semantic project.

A tag that a mandatory tag rule requires can still be removed; the project then lists it as missing.

PARAMETER DESCRIPTION
name

Name of the tag schema.

TYPE: str

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the backend encounters an error when handling the request.

dimension_values #

dimension_values(
    group_by: str | dict[str, Any],
    metrics: str | Sequence[str] | None = None,
    limit: int = 1000,
) -> list[Any]

Distinct values of one dimension, for example to fill a filter's choices.

PARAMETER DESCRIPTION
group_by

The dimension, as a qualified name or dict.

TYPE: str | dict[str, Any]

metrics

Metric names whose semantic models restrict the values, or None for every value.

TYPE: str | Sequence[str] | None DEFAULT: None

limit

Maximum number of values returned.

TYPE: int DEFAULT: 1000

RETURNS DESCRIPTION
list[Any]

The values.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request or the query fails.

dimensions #

dimensions(
    metrics: str | Sequence[str] | None = None,
) -> list[SemanticGroupBy]

Dimensions and time dimensions every one of the metrics can be grouped by.

PARAMETER DESCRIPTION
metrics

Metric names, or None for the dimensions of every semantic model.

TYPE: str | Sequence[str] | None DEFAULT: None

RETURNS DESCRIPTION
list[SemanticGroupBy]

The dimensions.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request, for example for an unknown metric.

entities #

entities(
    metrics: str | Sequence[str] | None = None,
) -> list[SemanticGroupBy]

Entities every one of the metrics can be grouped by.

PARAMETER DESCRIPTION
metrics

Metric names, or None for the entities of every semantic model.

TYPE: str | Sequence[str] | None DEFAULT: None

RETURNS DESCRIPTION
list[SemanticGroupBy]

The entities.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request, for example for an unknown metric.

explore_url #

explore_url(metric: str) -> str

A link that opens the metric in Superset's Explore view as a line chart over metric_time, on the caller's own semantic connection in Superset.

It creates the caller's dataset of the metrics table in this semantic project's schema on that connection, or refreshes its columns and metrics; no chart is saved until the caller saves one in Superset.

PARAMETER DESCRIPTION
metric

Name of the metric.

TYPE: str

RETURNS DESCRIPTION
str

The URL, through Hopsworks.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

For the same causes as create_dashboard.

exports #

exports() -> list[SemanticExport]

The exports of the build that answers queries, each with the outcome of its last run.

RETURNS DESCRIPTION
list[SemanticExport]

The exports, empty when no saved query defines one.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the backend encounters an error when handling the request.

get_build #

get_build(build_id: int) -> SemanticBuild

One build with its validation issues.

PARAMETER DESCRIPTION
build_id

Id of the build.

TYPE: int

RETURNS DESCRIPTION
SemanticBuild

The build, with issues filled.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the build does not exist or the backend encounters an error.

get_builds #

get_builds() -> list[SemanticBuild]

The project's retained builds, newest first, without their issues.

RETURNS DESCRIPTION
list[SemanticBuild]

The builds.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the backend encounters an error when handling the request.

get_tag #

get_tag(name: str) -> Any | None

The value of one tag attached to the semantic project.

PARAMETER DESCRIPTION
name

Name of the tag schema.

TYPE: str

RETURNS DESCRIPTION
Any | None

The tag value, or None if the project has no such tag.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the backend encounters an error when handling the request.

get_tags #

get_tags() -> dict[str, Any]

Every tag attached to the semantic project.

Metric tags are not included: they are part of each metric's definition, in SemanticMetric.tags.

RETURNS DESCRIPTION
dict[str, Any]

Tag schema names to tag values, empty when the project has none.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the backend encounters an error when handling the request.

group_bys #

group_bys(
    metrics: str | Sequence[str] | None = None,
) -> list[SemanticGroupBy]

Everything the metrics can be grouped by: dimensions, time dimensions, entities and metric_time.

PARAMETER DESCRIPTION
metrics

Metric names, or None for every semantic model.

TYPE: str | Sequence[str] | None DEFAULT: None

RETURNS DESCRIPTION
list[SemanticGroupBy]

The group-bys.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request, for example for an unknown metric.

list_metrics #

list_metrics(
    tag: str | Sequence[str] | None = None,
) -> list[SemanticMetric]

Every metric of the current build, or the metrics that carry every given tag.

PARAMETER DESCRIPTION
tag

Tag schema names; only metrics whose definitions set all of them are listed.

TYPE: str | Sequence[str] | None DEFAULT: None

RETURNS DESCRIPTION
list[SemanticMetric]

The metrics, each with its tags.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request, for example because no build is valid yet.

list_saved_queries #

list_saved_queries() -> list[SemanticSavedQuery]

Every saved query of the current build, as its YAML defines it.

Run one by name with saved_query= on query, sql or create_dashboard.

RETURNS DESCRIPTION
list[SemanticSavedQuery]

The saved queries.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request, for example because no build is valid yet.

promote #

promote(build_id: int) -> SemanticProject

Make a valid build the one that answers queries, in either deployment mode.

In FOLLOW mode the next valid compile replaces it again. This object is updated in place.

PARAMETER DESCRIPTION
build_id

Id of a VALID build of this project.

TYPE: int

RETURNS DESCRIPTION
SemanticProject

This semantic project, with its new current_build_id.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the build is not valid or the backend encounters an error.

query #

query(
    metrics: str | Sequence[str] | None = None,
    group_by: str
    | dict[str, Any]
    | Sequence[str | dict[str, Any]]
    | None = None,
    where: str | Sequence[str] | None = None,
    filters: Sequence[dict[str, Any] | tuple] | None = None,
    having: Sequence[dict[str, Any] | tuple] | None = None,
    order_by: str
    | dict[str, Any]
    | Sequence[str | dict[str, Any]]
    | None = None,
    limit: int | None = None,
    offset: int | None = None,
    time_range: tuple | dict[str, Any] | None = None,
    group_limit: dict[str, Any] | None = None,
    dataframe_type: Literal[
        "pandas", "polars", "pyarrow", "python"
    ] = "pandas",
    saved_query: str | None = None,
    read_cache: bool = True,
) -> (
    pd.DataFrame
    | pl.DataFrame
    | pa.Table
    | list[dict[str, Any]]
)

Run a metric query on the query engine, as the caller, and return its rows.

The arguments are those of sql, including how they refine a saved query. Results come back as an Arrow stream when pyarrow is installed, which keeps column types, and as JSON otherwise. The gateway caps the number of rows it returns, and a result that may have been cut by the cap logs a warning. The gateway may answer a repeated query from its result cache, which drops a result once a feature group the query reads has a new commit; a change of the caller's access reaches the cache within a minute.

Run a saved query, only for one country
df = sales.query(
    saved_query="revenue_by_country",
    where=["{{ Dimension('customer__country') }} = 'SE'"],
)
PARAMETER DESCRIPTION
metrics

Metric names; leave them out with saved_query.

TYPE: str | Sequence[str] | None DEFAULT: None

group_by

Group-bys, as qualified names or dicts.

TYPE: str | dict[str, Any] | Sequence[str | dict[str, Any]] | None DEFAULT: None

where

Text filters in MetricFlow's call syntax.

TYPE: str | Sequence[str] | None DEFAULT: None

filters

Structured filters, each a dict {"group_by", "op", "value"} or a tuple (group_by, op, value).

TYPE: Sequence[dict[str, Any] | tuple] | None DEFAULT: None

having

Filters on metric values, each a dict {"metric", "op", "value"} or a tuple (metric, op, value).

TYPE: Sequence[dict[str, Any] | tuple] | None DEFAULT: None

order_by

Metric or group-by column names; a leading - sorts descending.

TYPE: str | dict[str, Any] | Sequence[str | dict[str, Any]] | None DEFAULT: None

limit

Maximum number of rows.

TYPE: int | None DEFAULT: None

offset

Number of rows to skip.

TYPE: int | None DEFAULT: None

time_range

A (start, end) tuple or a {"start", "end"} dict bounding metric_time, both ends inclusive and truncated to the query's time grain.

TYPE: tuple | dict[str, Any] | None DEFAULT: None

group_limit

Keep only the top groups, as a dict {"group_by", "top", "metric", "descending"}.

TYPE: dict[str, Any] | None DEFAULT: None

dataframe_type

pandas, polars, pyarrow, or python for a list of rows, each a dict keyed by column name.

TYPE: Literal['pandas', 'polars', 'pyarrow', 'python'] DEFAULT: 'pandas'

saved_query

Name of a saved query to run, from list_saved_queries.

TYPE: str | None DEFAULT: None

read_cache

Whether the gateway may answer from its result cache; False always runs the query on the engine.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
pd.DataFrame | pl.DataFrame | pa.Table | list[dict[str, Any]]

The rows, one column per group-by and metric.

RAISES DESCRIPTION
ValueError

For an unknown dataframe_type, or if both metrics and saved_query are given.

ModuleNotFoundError

When dataframe_type is polars or pyarrow and that package is not installed.

hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the query, the query engine fails to run it, or the result stops before its end, in which case no rows are returned and the query can be run again.

query_history #

query_history(
    limit: int = 100,
    status: str | Sequence[str] | None = None,
    user: str | None = None,
) -> pd.DataFrame

The most recent queries run on this semantic project, newest first, one row per execution attempt.

Every query the gateway runs over REST, Arrow Flight SQL or the BI tables is recorded, failed and cancelled ones included; listings of metrics and requests that only compile SQL are not. Members see their own queries; Data Owners see every member's, and can narrow them to one with user. History is best effort and is kept for 30 days; the request, SQL and error of a query are dropped after semantic_query_strip_details_after_days (7 by default).

PARAMETER DESCRIPTION
limit

Maximum number of queries returned.

TYPE: int DEFAULT: 100

status

SUCCEEDED, FAILED or CANCELLED, or several of them.

TYPE: str | Sequence[str] | None DEFAULT: None

user

User name whose queries to return; only Data Owners can read other users' queries.

TYPE: str | None DEFAULT: None

RETURNS DESCRIPTION
pd.DataFrame

One row per query with columns execution_id, user, surface, build_id, status, error, rows, started_at, finished_at, duration_ms, cache, served_from, trino_query_id, request and sql; started_at and finished_at are UTC timestamps.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If a filter is invalid or the backend encounters an error when handling the request.

run_export #

run_export(name: str, wait: bool = False) -> Execution

Run an export now, outside its schedule, through its job.

The job runs as the semantic project's owner and records its outcome in the export's last_status; runs of one export never overlap, so starting a run while another is going is refused. Only a Data Owner of the project can start one.

PARAMETER DESCRIPTION
name

Name of the export, from exports.

TYPE: str

wait

Whether to block until the job execution ends.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
Execution

The job execution; exports says how many rows it wrote, or why it wrote none.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If there is no such export, the caller is not a Data Owner, or the backend encounters another error.

hopsworks.client.exceptions.JobExecutionException

When wait is set and the execution failed.

serving #

serving() -> SemanticServing

The build the gateway answers this project's queries from, and whether a newer compile is pending or invalid.

The gateway keeps each caller's view of the project for up to a minute, so a newly served build can take that long to show.

RETURNS DESCRIPTION
SemanticServing

The serving build.

RAISES DESCRIPTION
hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the request, for example because no build is valid yet.

sql #

sql(
    metrics: str | Sequence[str] | None = None,
    group_by: str
    | dict[str, Any]
    | Sequence[str | dict[str, Any]]
    | None = None,
    where: str | Sequence[str] | None = None,
    filters: Sequence[dict[str, Any] | tuple] | None = None,
    having: Sequence[dict[str, Any] | tuple] | None = None,
    order_by: str
    | dict[str, Any]
    | Sequence[str | dict[str, Any]]
    | None = None,
    limit: int | None = None,
    offset: int | None = None,
    time_range: tuple | dict[str, Any] | None = None,
    group_limit: dict[str, Any] | None = None,
    saved_query: str | None = None,
) -> str

The SQL a metric query compiles to, without running it.

A query names its metrics, or runs a saved query by name and takes the metrics from it. On a saved query, group_by, order_by and limit replace its own when given, and where and filters are added to its filters. An empty group_by replaces its group-bys too, asking for its totals, and an empty order_by drops its sort. Its own order-bys by a group-by that a given group_by leaves out are dropped.

Run a saved query by month instead of its own grain
sql = sales.sql(saved_query="revenue_by_country", group_by=["metric_time__month"])
PARAMETER DESCRIPTION
metrics

Metric names; leave them out with saved_query.

TYPE: str | Sequence[str] | None DEFAULT: None

group_by

Group-bys, as qualified names or dicts.

TYPE: str | dict[str, Any] | Sequence[str | dict[str, Any]] | None DEFAULT: None

where

Text filters in MetricFlow's call syntax, such as "{{ Dimension('listing__country_latest') }} = 'us'". Several filters are combined with AND.

TYPE: str | Sequence[str] | None DEFAULT: None

filters

Structured filters, each a dict {"group_by", "op", "value"} or a tuple (group_by, op, value). op is one of =, !=, <, <=, >, >=, IN, NOT IN, IS NULL, IS NOT NULL and LIKE; values are bound as literals, never parsed as SQL. A date or datetime value is sent as ISO-8601; a timezone-aware one is compared in UTC.

TYPE: Sequence[dict[str, Any] | tuple] | None DEFAULT: None

having

Filters on metric values, each a dict {"metric", "op", "value"} or a tuple (metric, op, value).

TYPE: Sequence[dict[str, Any] | tuple] | None DEFAULT: None

order_by

Metric or group-by column names; a leading -, as in "-revenue", sorts descending. NULLs sort last.

TYPE: str | dict[str, Any] | Sequence[str | dict[str, Any]] | None DEFAULT: None

limit

Maximum number of rows.

TYPE: int | None DEFAULT: None

offset

Number of rows to skip.

TYPE: int | None DEFAULT: None

time_range

A (start, end) tuple or a {"start", "end"} dict of ISO-8601 strings, dates or datetimes, either of which may be None. A timezone-aware datetime, or a string with an offset, is converted to UTC; one without is taken as UTC. It keeps metric_time from start through end, both inclusive, each truncated to the query's time grain: a monthly query ending 2026-02-01 includes all of February.

TYPE: tuple | dict[str, Any] | None DEFAULT: None

group_limit

Keep only the top groups, as a dict {"group_by", "top", "metric", "descending"}, for example the five countries with the most revenue.

TYPE: dict[str, Any] | None DEFAULT: None

saved_query

Name of a saved query to run, from list_saved_queries.

TYPE: str | None DEFAULT: None

RETURNS DESCRIPTION
str

The SQL statement.

RAISES DESCRIPTION
ValueError

If both metrics and saved_query are given.

hopsworks.client.exceptions.SemanticLayerException

If the gateway refuses the query, for example for an unknown metric, group-by or saved query.

transfer_ownership #

transfer_ownership(email: str) -> SemanticProject

Hand the semantic project over to another Data Owner of the Hopsworks project.

The export jobs run as the owner, so they run as the new owner from then on. The caller must be a Data Owner whose project role allows Semantic layer: Create & edit, and need not be the current owner, so a semantic project whose owner left the project can still be handed over. Removing the owner from the project with Project.remove_member hands their semantic projects over as part of the removal. creator keeps naming the member who registered the semantic project. This object is updated in place.

Example
sales = project.get_semantic_layer_api().get_project("sales")
sales.transfer_ownership("carol@example.com")
print(sales.owner)
PARAMETER DESCRIPTION
email

Email address of the Data Owner who becomes the owner; their project role must allow Semantic layer: Run exports.

TYPE: str

RETURNS DESCRIPTION
SemanticProject

This semantic project, with its new owner.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

If the caller may not hand the semantic project over, the new owner is not a Data Owner of the project who may run exports, in which case the message gives the reason, or the backend encounters another error.

update #

update(
    root_path: str | None = None,
    format: Literal[
        "AUTO", "DBT", "NATIVE", "MANIFEST_JSON"
    ]
    | None = None,
    deployment_mode: Literal["FOLLOW", "PINNED"]
    | None = None,
) -> SemanticProject

Change where the definitions are read from, how they are read, or which build answers queries.

A new root path or format compiles the definitions again in the background, and the git repository becomes the one the new root path is in. A setting left as None keeps its value; the name cannot change. This object is updated in place.

PARAMETER DESCRIPTION
root_path

Directory of the definitions, relative to the project, under /hopsfs/, or /Projects/<project>/....

TYPE: str | None DEFAULT: None

format

Format of the definitions; AUTO detects it from the files.

TYPE: Literal['AUTO', 'DBT', 'NATIVE', 'MANIFEST_JSON'] | None DEFAULT: None

deployment_mode

FOLLOW serves every new valid build; PINNED serves a build until another is promoted.

TYPE: Literal['FOLLOW', 'PINNED'] | None DEFAULT: None

RETURNS DESCRIPTION
SemanticProject

This semantic project, with its new settings.

RAISES DESCRIPTION
ValueError

If no setting is given.

hopsworks.client.exceptions.RestAPIError

If the path is outside the project or the backend encounters another error.

SemanticSavedQuery dataclass #

A named metric query a semantic project defines under saved_queries: in its YAML, run by name with saved_query=.

Run it with SemanticProject.query or SemanticProject.sql, which can refine it. metrics and group_by are what it queries, with group-bys as qualified names such as metric_time__month. where holds its filters in MetricFlow's call syntax, combined with AND. order_by is its sort, each entry a dict with the column name and the bool descending, and limit its row limit, None for no limit. tags are the schematised tags its definition sets in config.meta.hopsworks.tags, tag schema name to value.

SemanticServing dataclass #

The build a semantic project answers queries from.

build_id is that build. stale is set while it is older than the project's newest compile, because that compile is invalid or still running.