feat: Add version-aware materialization support

franciscojavierarceo · claude · franciscojavierarceo · commit 280daf65dabc · 2026-03-20T18:58:27.000-04:00
Add --version flag to feast materialize/materialize-incremental CLI commands
and corresponding Python SDK support. Gate versioned table IDs behind
enable_online_feature_view_versioning config flag in SQLite online store.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/rfcs/feature-view-versioning.md b/docs/rfcs/feature-view-versioning.md
@@ -239,6 +239,47 @@ Versioning works on all three feature view types:
 
 Version-qualified reads (`@v<N>`) are currently implemented for the **SQLite** online store. Other online stores will raise a clear error. Expanding to additional stores is follow-up work.
 
+### Materialization
+
+Each version's data lives in its own online store table (e.g., `project_fv_v1`, `project_fv_v2`). By default, `feast materialize` and `feast materialize-incremental` populate the **active (latest)** version's table. To populate a specific version's table, pass the `--version` flag along with a single `--views` target:
+
+```bash
+# Materialize v1 of driver_stats
+feast materialize --views driver_stats --version v1 2024-01-01T00:00:00 2024-01-15T00:00:00
+
+# Incrementally materialize v2 of driver_stats
+feast materialize-incremental --views driver_stats --version v2 2024-01-15T00:00:00
+```
+
+Python SDK equivalent:
+
+```python
+store.materialize(
+    feature_views=["driver_stats"],
+    version="v2",
+    start_date=start,
+    end_date=end,
+)
+```
+
+**Requirements:**
+- `enable_online_feature_view_versioning: true` must be set in `feature_store.yaml`
+- `--version` requires `--views` with exactly one feature view name
+- The specified version must exist in the registry (created by a prior `feast apply`)
+- Without `--version`, materialization targets the active version's table (existing behavior)
+
+**Multi-version workflow example:**
+
+```bash
+# Model A uses v1, Model B uses v2 — populate both tables
+feast materialize --views driver_stats --version v1 2024-01-01T00:00:00 2024-02-01T00:00:00
+feast materialize --views driver_stats --version v2 2024-01-01T00:00:00 2024-02-01T00:00:00
+
+# Models can now query their respective versions online
+# Model A: store.get_online_features(features=["driver_stats@v1:trips_today"], ...)
+# Model B: store.get_online_features(features=["driver_stats@v2:trips_today"], ...)
+```
+
 ## API Surface
 
 ### Python SDK
@@ -256,6 +297,10 @@ FeatureView(name="driver_stats", ..., version="v2")
 
 # Version-qualified online read (requires enable_online_feature_view_versioning)
 store.get_online_features(features=["driver_stats@v2:trips_today"], ...)
+
+# Materialize a specific version
+store.materialize(feature_views=["driver_stats"], version="v2", start_date=start, end_date=end)
+store.materialize_incremental(feature_views=["driver_stats"], version="v2", end_date=end)
 ```
 
 ### CLI
@@ -268,6 +313,10 @@ feast feature-views list-versions driver_stats
 # VERSION  TYPE          CREATED              VERSION_ID
 # v0       feature_view  2024-01-15 10:30:00  a1b2c3d4-...
 # v1       feature_view  2024-01-16 14:22:00  e5f6g7h8-...
+
+# Materialize a specific version
+feast materialize --views driver_stats --version v2 2024-01-01T00:00:00 2024-02-01T00:00:00
+feast materialize-incremental --views driver_stats --version v2 2024-02-01T00:00:00
 ```
 
 ### Configuration
diff --git a/sdk/python/feast/cli/cli.py b/sdk/python/feast/cli/cli.py
@@ -351,13 +351,20 @@ def registry_dump_command(ctx: click.Context):
     is_flag=True,
     help="Materialize all available data using current datetime as event timestamp (useful when source data lacks event timestamps)",
 )
+@click.option(
+    "--version",
+    "feature_view_version",
+    default=None,
+    help="Version to materialize (e.g., 'v2'). Requires --views with exactly one feature view.",
+)
 @click.pass_context
 def materialize_command(
     ctx: click.Context,
     start_ts: Optional[str],
     end_ts: Optional[str],
     views: List[str],
     disable_event_timestamp: bool,
+    feature_view_version: Optional[str],
 ):
     """
     Run a (non-incremental) materialization job to ingest data into the online store. Feast
@@ -395,6 +402,7 @@ def materialize_command(
         start_date=start_date,
         end_date=end_date,
         disable_event_timestamp=disable_event_timestamp,
+        version=feature_view_version,
     )
 
 
@@ -406,8 +414,19 @@ def materialize_command(
     help="Feature views to incrementally materialize",
     multiple=True,
 )
+@click.option(
+    "--version",
+    "feature_view_version",
+    default=None,
+    help="Version to materialize (e.g., 'v2'). Requires --views with exactly one feature view.",
+)
 @click.pass_context
-def materialize_incremental_command(ctx: click.Context, end_ts: str, views: List[str]):
+def materialize_incremental_command(
+    ctx: click.Context,
+    end_ts: str,
+    views: List[str],
+    feature_view_version: Optional[str],
+):
     """
     Run an incremental materialization job to ingest new data into the online store. Feast will read
     all data from the previously ingested point to END_TS from the offline store and write it to the
@@ -420,6 +439,7 @@ def materialize_incremental_command(ctx: click.Context, end_ts: str, views: List
     store.materialize_incremental(
         feature_views=None if not views else views,
         end_date=utils.make_tzaware(datetime.fromisoformat(end_ts)),
+        version=feature_view_version,
     )
 
 
diff --git a/sdk/python/feast/feature_store.py b/sdk/python/feast/feature_store.py
@@ -100,6 +100,7 @@
 from feast.transformation.pandas_transformation import PandasTransformation
 from feast.transformation.python_transformation import PythonTransformation
 from feast.utils import _get_feature_view_vector_field_metadata, _utc_now
+from feast.version_utils import parse_version
 
 _track_materialization = None  # Lazy-loaded on first materialization call
 _track_materialization_loaded = False
@@ -772,9 +773,39 @@ def _make_inferences(
         for feature_service in feature_services_to_update:
             feature_service.infer_features(fvs_to_update=fvs_to_update_map)
 
+    def _validate_materialize_version(
+        self,
+        version: Optional[str],
+        feature_views: Optional[List[str]],
+    ) -> Optional[int]:
+        """Validate and parse the version parameter for materialize calls.
+
+        Returns the parsed version number, or None if no version was specified.
+        """
+        if version is None:
+            return None
+
+        if not feature_views or len(feature_views) != 1:
+            raise ValueError(
+                "--version requires --views with exactly one feature view."
+            )
+
+        if not self.config.registry.enable_online_feature_view_versioning:
+            raise ValueError(
+                "Version-aware materialization requires "
+                "'enable_online_feature_view_versioning: true' under 'registry' "
+                "in feature_store.yaml."
+            )
+
+        is_latest, version_number = parse_version(version)
+        if is_latest:
+            return None
+        return version_number
+
     def _get_feature_views_to_materialize(
         self,
         feature_views: Optional[List[str]],
+        version: Optional[int] = None,
     ) -> List[Union[FeatureView, OnDemandFeatureView]]:
         """
         Returns the list of feature views that should be materialized.
@@ -783,6 +814,8 @@ def _get_feature_views_to_materialize(
 
         Args:
             feature_views: List of names of feature views to materialize.
+            version: If set, load this specific version number from the registry
+                instead of the active definition. Requires exactly one feature view name.
 
         Raises:
             FeatureViewNotFoundException: One of the specified feature views could not be found.
@@ -814,15 +847,25 @@ def _get_feature_views_to_materialize(
         else:
             for name in feature_views:
                 feature_view: Union[FeatureView, OnDemandFeatureView]
-                try:
-                    feature_view = self._get_feature_view(name, hide_dummy_entity=False)
-                except FeatureViewNotFoundException:
+                if version is not None:
+                    feature_view = cast(
+                        Union[FeatureView, OnDemandFeatureView],
+                        self.registry.get_feature_view_by_version(
+                            name, self.project, version
+                        ),
+                    )
+                else:
                     try:
-                        feature_view = self._get_stream_feature_view(
+                        feature_view = self._get_feature_view(
                             name, hide_dummy_entity=False
                         )
                     except FeatureViewNotFoundException:
-                        feature_view = self.get_on_demand_feature_view(name)
+                        try:
+                            feature_view = self._get_stream_feature_view(
+                                name, hide_dummy_entity=False
+                            )
+                        except FeatureViewNotFoundException:
+                            feature_view = self.get_on_demand_feature_view(name)
 
                 if hasattr(feature_view, "online") and not feature_view.online:
                     raise ValueError(
@@ -1152,38 +1195,6 @@ def apply(
         for ent in entities_to_update:
             self.registry.apply_entity(ent, project=self.project, commit=False)
 
-        # Gate: feature services must not reference versioned FVs when online versioning is off
-        if not self.config.registry.enable_online_feature_view_versioning:
-            fvs_in_batch = {
-                fv.name: fv
-                for fv in itertools.chain(
-                    views_to_update, odfvs_to_update, sfvs_to_update
-                )
-            }
-            for feature_service in services_to_update:
-                for projection in feature_service.feature_view_projections:
-                    ref_fv: Optional[BaseFeatureView] = fvs_in_batch.get(
-                        projection.name
-                    )
-                    if ref_fv is None:
-                        try:
-                            ref_fv = self.registry.get_any_feature_view(
-                                projection.name, self.project
-                            )
-                        except FeatureViewNotFoundException:
-                            continue
-                    cur_ver: Optional[int] = getattr(
-                        ref_fv, "current_version_number", None
-                    )
-                    if cur_ver is not None and cur_ver > 0:
-                        raise ValueError(
-                            f"Feature service '{feature_service.name}' references feature view "
-                            f"'{projection.name}' which is at version v{cur_ver}. "
-                            f"To use versioned feature views in feature services, set "
-                            f"'enable_online_feature_view_versioning: true' under 'registry' "
-                            f"in feature_store.yaml."
-                        )
-
         for feature_service in services_to_update:
             self.registry.apply_feature_service(
                 feature_service, project=self.project, commit=False
@@ -1678,6 +1689,7 @@ def materialize_incremental(
         end_date: datetime,
         feature_views: Optional[List[str]] = None,
         full_feature_names: bool = False,
+        version: Optional[str] = None,
     ) -> None:
         """
         Materialize incremental new data from the offline store into the online store.
@@ -1694,6 +1706,8 @@ def materialize_incremental(
                 materialization for the specified feature views.
             full_feature_names (bool): If True, feature names will be prefixed with the corresponding
                 feature view name.
+            version (str): Optional version to materialize (e.g., 'v2'). Requires feature_views
+                with exactly one entry and enable_online_feature_view_versioning to be enabled.
 
         Raises:
             Exception: A feature view being materialized does not have a TTL set.
@@ -1709,8 +1723,9 @@ def materialize_incremental(
             <BLANKLINE>
             ...
         """
+        parsed_version = self._validate_materialize_version(version, feature_views)
         feature_views_to_materialize = self._get_feature_views_to_materialize(
-            feature_views
+            feature_views, version=parsed_version
         )
         _print_materialization_log(
             None,
@@ -1831,6 +1846,7 @@ def materialize(
         feature_views: Optional[List[str]] = None,
         disable_event_timestamp: bool = False,
         full_feature_names: bool = False,
+        version: Optional[str] = None,
     ) -> None:
         """
         Materialize data from the offline store into the online store.
@@ -1847,6 +1863,8 @@ def materialize(
             disable_event_timestamp (bool): If True, materializes all available data using current datetime as event timestamp instead of source event timestamps
             full_feature_names (bool): If True, feature names will be prefixed with the corresponding
                 feature view name.
+            version (str): Optional version to materialize (e.g., 'v2'). Requires feature_views
+                with exactly one entry and enable_online_feature_view_versioning to be enabled.
 
         Examples:
             Materialize all features into the online store over the interval
@@ -1866,8 +1884,9 @@ def materialize(
                 f"The given start_date {start_date} is greater than the given end_date {end_date}."
             )
 
+        parsed_version = self._validate_materialize_version(version, feature_views)
         feature_views_to_materialize = self._get_feature_views_to_materialize(
-            feature_views
+            feature_views, version=parsed_version
         )
         _print_materialization_log(
             start_date,
diff --git a/sdk/python/feast/infra/online_stores/sqlite.py b/sdk/python/feast/infra/online_stores/sqlite.py
