Time Spine#
A time spine is a feature group with one row per period, one per day by default. Cumulative metrics, offsets, join_to_timespine and custom granularities join to it, so a period without rows still has a place in the result, and a window or an offset counts periods rather than rows. Create the feature group once per Hopsworks project, then declare it in each semantic project that needs it. Metric types lists the metrics that need one.
Create the time spine#
It writes the rows, waits until they are in the offline store, and ends with:
The spine is the offline feature group time_spine_<grain>, version 1, with one row per period from the start through the end. Its primary key date_<grain> holds the start of each period: a date for a day or a coarser grain, a timestamp for an hour, a minute or a second.
| Option | Meaning |
|---|---|
--start | The first day of the spine, ISO-8601; it moves back to the start of its period. |
--end | The last day of the spine, included. |
--grain | day (default), second, minute, hour, week, month, quarter or year; weeks start on Monday. |
--custom NAME=FREQ | A custom granularity column, repeatable, see Custom granularities. |
Running it again inserts the rows into the existing feature group, so a wider range extends the spine; the custom granularities must be the ones the spine already has. The spine holds one row per period: ten years are 3,653 days, or 315 million seconds. Cover the time of every row the metrics read, since a cumulative or offset metric has rows only for the periods the spine has.
Declare the time spine#
A semantic project declares its time spine as a dbt time spine model, in any YAML file under model-paths, such as models/time_spine.yml:
models:
- name: time_spine_day
description: One row per day, written by hops semantic time-spine create.
time_spine:
standard_granularity_column: date_day
columns:
- name: date_day
granularity: day
time_spine.standard_granularity_column names the column with one row per period, and its granularity in columns is the grain of the spine. The compile reads YAML only, so the model needs no SQL file.
The model binds the feature group time_spine_<grain> of the project's feature store, at its latest version, whatever the model's name. config.meta.hopsworks binds another, with the keys of a semantic model:
models:
- name: time_spine_day
time_spine:
standard_granularity_column: date_day
columns:
- name: date_day
granularity: day
config:
meta:
hopsworks:
feature_group: calendar_days
version: 2
In the NATIVE format, project_configuration.time_spines declares the spine, each with a primary_column of a name and a time_granularity, and its node_relation names the feature store of the feature group time_spine_<grain>. Without a name, the spine reads the event time of its feature group.
A semantic project can declare one spine per grain. A metric reads the spine at the grain of its measures' agg time dimension, or a finer one, so measures aggregated by hour need an hourly spine. A spine binds when its feature group exists, its standard granularity column, or else the feature group's event time, is a date or a timestamp, and it has a column for each custom granularity; otherwise the build has a TIME_SPINE warning that says why, at the time spine model.
Custom granularities#
A custom granularity is a column of the spine that maps each period to a period of its own, such as a fiscal quarter:
FREQ is a pandas period frequency, and each row holds the start of its period at that frequency, typed like date_<grain>. Q-JAN is the quarters of a fiscal year that ends in January, which start on the first of February, May, August and November. In Python, a callable takes each row's date_<grain> and returns the row's value of the column, such as FY2027.
The time spine model lists the custom granularities:
models:
- name: time_spine_day
time_spine:
standard_granularity_column: date_day
custom_granularities:
- name: fiscal_quarter
columns:
- name: date_day
granularity: day
Each entry takes a name, and a column_name when the spine's column has another name. A query groups by a custom granularity as by a grain:
hops semantic query sales --metrics revenue --group-by metric_time__fiscal_quarter \
--order-by metric_time__fiscal_quarter -o csv
The orders of January fall in the fiscal quarter that starts on November 1, 2025, and those of February and March in the one that starts on February 1, 2026. An offset window can count custom granularity periods, such as offset_window: 1 fiscal_quarter. A query that names a granularity no time spine of the semantic project defines is refused with 400 SEMANTIC_LAYER_INVALID_QUERY. Metric types lists the queries with custom granularities that are refused.
Without a time spine#
A metric that needs a spine at its grain when none is bound is a TIME_SPINE error at the metric, so the build is INVALID, and the last valid build keeps answering queries. With models/cumulative.yml:
metrics:
- name: revenue_7d
type: cumulative
type_params:
measure: revenue
cumulative_type_params:
window: 7 days
and no time spine model, the compile reports:
Build 4: INVALID (1 errors, 0 warnings)
LEVEL RULE LOCATION ELEMENT MESSAGE
----- ---------- ------------------------- ----------------- -----------------------------------------------------------------------------------------------------
ERROR TIME_SPINE models/cumulative.yml:2:5 metric:revenue_7d metric revenue_7d needs a time spine at day grain or finer for a cumulative window, and none is bound
The message names what reads the spine: a cumulative window, the offset of input <metric>, join_to_timespine, or a custom granularity. A spine declared with no feature group to bind adds a TIME_SPINE warning at the time spine model, such as the day time spine is not bound: no feature group time_spine_day in sales_featurestore; metrics that need it cannot be queried. Create the spine and compile again.