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.
Returned by
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.
Returned by
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.
Returned by
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.
Returned by
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,
)
Returned by
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 #
Names of the mandatory semantic project tags the project lacks, empty when it has them all or on a community cluster.
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 #
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.
| PARAMETER | DESCRIPTION |
|---|---|
name | Name of the tag schema. TYPE: |
value | Value of the tag. TYPE: |
| 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 #
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. |
| 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 TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
SemanticBuild | The build, in a final status when |
| RAISES | DESCRIPTION |
|---|---|
hopsworks.client.exceptions.SemanticBuildException | When |
hopsworks.client.exceptions.SemanticLayerException | When |
hopsworks.client.exceptions.RestAPIError | If the backend encounters an error when handling the request. |
connection_info #
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 TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A dict with |
| 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 |
group_by | Dimensions for the breakdown table and the native filters, such as |
title | Title of the dashboard; without one, TYPE: |
saved_query | Name of a saved query whose metrics and group-bys the dashboard shows, instead of TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | The dashboard's Superset |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If neither |
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 |
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: |
| 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. |
metrics | Metric names whose semantic models restrict the values, or |
limit | Maximum number of values returned. TYPE: |
| 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 |
| 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 |
| 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 #
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: |
| RETURNS | DESCRIPTION |
|---|---|
str | The URL, through Hopsworks. |
| RAISES | DESCRIPTION |
|---|---|
hopsworks.client.exceptions.SemanticLayerException | For the same causes as |
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: |
| RETURNS | DESCRIPTION |
|---|---|
SemanticBuild | The build, with |
| 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 #
The value of one tag attached to the semantic project.
| PARAMETER | DESCRIPTION |
|---|---|
name | Name of the tag schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Any | None | The tag value, or |
| RAISES | DESCRIPTION |
|---|---|
hopsworks.client.exceptions.RestAPIError | If the backend encounters an error when handling the request. |
get_tags #
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 |
| 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. |
| 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 TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
SemanticProject | This semantic project, with its new |
| 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
| PARAMETER | DESCRIPTION |
|---|---|
metrics | Metric names; leave them out with |
group_by | Group-bys, as qualified names or dicts. TYPE: |
where | Text filters in MetricFlow's call syntax. |
filters | Structured filters, each a dict |
having | Filters on metric values, each a dict |
order_by | Metric or group-by column names; a leading TYPE: |
limit | Maximum number of rows. TYPE: |
offset | Number of rows to skip. TYPE: |
time_range | A |
group_limit | Keep only the top groups, as a dict |
dataframe_type |
TYPE: |
saved_query | Name of a saved query to run, from TYPE: |
read_cache | Whether the gateway may answer from its result cache; TYPE: |
| 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 |
ModuleNotFoundError | When |
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: |
status |
|
user | User name whose queries to return; only Data Owners can read other users' queries. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
pd.DataFrame | One row per query with columns |
| RAISES | DESCRIPTION |
|---|---|
hopsworks.client.exceptions.RestAPIError | If a filter is invalid or the backend encounters an error when handling the request. |
run_export #
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 TYPE: |
wait | Whether to block until the job execution ends. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Execution | The job execution; |
| 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 |
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
| PARAMETER | DESCRIPTION |
|---|---|
metrics | Metric names; leave them out with |
group_by | Group-bys, as qualified names or dicts. TYPE: |
where | Text filters in MetricFlow's call syntax, such as |
filters | Structured filters, each a dict |
having | Filters on metric values, each a dict |
order_by | Metric or group-by column names; a leading TYPE: |
limit | Maximum number of rows. TYPE: |
offset | Number of rows to skip. TYPE: |
time_range | A |
group_limit | Keep only the top groups, as a dict |
saved_query | Name of a saved query to run, from TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
str | The SQL statement. |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If both |
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
| PARAMETER | DESCRIPTION |
|---|---|
email | Email address of the Data Owner who becomes the owner; their project role must allow Semantic layer: Run exports. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
SemanticProject | This semantic project, with its new |
| 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 TYPE: |
format | Format of the definitions; TYPE: |
deployment_mode |
TYPE: |
| 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.
Returned by
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.