feat: Make feature view versioning opt-in via registry config

franciscojavierarceo · claude · franciscojavierarceo · commit dd31cdb3da4b · 2026-03-17T13:41:50.000-04:00
Versioning was always active on every `feast apply`. This adds an
`enable_feature_view_versioning` boolean (default False) to
RegistryConfig so version history, version pins, and version-qualified
refs are only available when explicitly enabled. Existing behaviour is
fully preserved when the flag is set to true.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/getting-started/concepts/feature-retrieval.md b/docs/getting-started/concepts/feature-retrieval.md
@@ -100,7 +100,7 @@ online_features = fs.get_online_features(
 ```
 
 {% hint style="info" %}
-Version-qualified reads (`@v<N>`) are currently supported only on the SQLite online store. See the [feature view versioning docs](feature-view.md#version-qualified-feature-references) for details.
+Version-qualified reads (`@v<N>`) require `enable_feature_view_versioning: true` in your registry config and are currently supported only on the SQLite online store. See the [feature view versioning docs](feature-view.md#version-qualified-feature-references) for details.
 {% endhint %}
 
 It is possible to retrieve features from multiple feature views with a single request, and Feast is able to join features from multiple tables in order to build a training dataset. However, it is not possible to reference (or retrieve) features from multiple projects at the same time.
diff --git a/docs/getting-started/concepts/feature-view.md b/docs/getting-started/concepts/feature-view.md
@@ -164,9 +164,21 @@ Each field can have additional metadata associated with it, specified as key-val
 
 Feature views support automatic version tracking. Every time `feast apply` detects a change to a feature view, a version snapshot is saved to the registry's version history. This enables auditing what changed, reverting to a prior definition, or pinning serving to a known-good version.
 
+{% hint style="warning" %}
+Versioning is **opt-in** and disabled by default. To enable it, add `enable_feature_view_versioning: true` to your registry config in `feature_store.yaml`:
+
+```yaml
+registry:
+  path: data/registry.db
+  enable_feature_view_versioning: true
+```
+
+When disabled, `feast apply` works normally but does not create version history. Version-qualified refs (e.g., `fv@v2:feature`) and version pinning (e.g., `version="v0"`) will raise errors.
+{% endhint %}
+
 ### How it works
 
-Version tracking is fully automatic. You don't need to set any version parameter — just use `feast apply` as usual:
+Once versioning is enabled, version tracking is fully automatic. You don't need to set any version parameter — just use `feast apply` as usual:
 
 1. **First apply** — Your feature view definition is saved as **v0**.
 2. **Change something and re-apply** — Feast detects the change, saves the old definition as a snapshot, and saves the new one as **v1**. The version number auto-increments on each real change.
diff --git a/docs/how-to-guides/feast-snowflake-gcp-aws/read-features-from-the-online-store.md b/docs/how-to-guides/feast-snowflake-gcp-aws/read-features-from-the-online-store.md
@@ -22,7 +22,8 @@ Create a list of features that you would like to retrieve. This list typically c
 features = [
     "driver_hourly_stats:conv_rate",
     "driver_hourly_stats:acc_rate",
-    # Optionally, reference a specific version: "driver_hourly_stats@v2:conv_rate"
+    # Optionally, reference a specific version (requires enable_feature_view_versioning):
+    # "driver_hourly_stats@v2:conv_rate"
 ]
 ```
 
diff --git a/docs/reference/feast-cli-commands.md b/docs/reference/feast-cli-commands.md
@@ -176,7 +176,7 @@ NAME                 ENTITIES    TYPE
 driver_hourly_stats  {'driver'}  FeatureView
 ```
 
-List version history for a feature view
+List version history for a feature view (requires `enable_feature_view_versioning: true` in registry config)
 
 ```text
 feast feature-views versions FEATURE_VIEW_NAME
diff --git a/docs/reference/registries/metadata.md b/docs/reference/registries/metadata.md
@@ -20,6 +20,7 @@ The metadata info of Feast `feature_store.yaml` is:
 | registry.warehouse | N | string | snowflake warehouse name |
 | registry.database | N | string | snowflake db name |
 | registry.schema   | N | string | snowflake schema name |
+| registry.enable_feature_view_versioning | N | boolean | enable feature view version history tracking (default: false) |
 | online_store  | Y | | |
 | offline_store  | Y | NA | | |
 | offline_store.type | Y | string | storage type | 
diff --git a/sdk/python/feast/feature_view.py b/sdk/python/feast/feature_view.py
@@ -510,6 +510,8 @@ def to_proto_meta(self):
             meta.materialization_intervals.append(interval_proto)
         if self.current_version_number is not None:
             meta.current_version_number = self.current_version_number
+        else:
+            meta.current_version_number = -1
         return meta
 
     def get_ttl_duration(self):
@@ -671,18 +673,16 @@ def _from_proto_internal(
 
         # Restore version fields.
         feature_view.version = feature_view_proto.spec.version or "latest"
-        # proto3 int32 defaults to 0, so use spec.version to distinguish
-        # "actually version 0" from "no version set". An empty spec.version
-        # means the proto predates versioning, so current_version_number
-        # should be None.
-        if feature_view_proto.meta.current_version_number:
-            feature_view.current_version_number = (
-                feature_view_proto.meta.current_version_number
-            )
-        elif (
-            feature_view_proto.meta.current_version_number == 0
-            and feature_view_proto.spec.version
-        ):
+        # A sentinel of -1 means "not set" (versioning disabled).
+        # A value of 0 means explicitly version 0.
+        # For protos predating the sentinel (current_version_number == 0
+        # with no spec.version), treat as None for backward compat.
+        cvn = feature_view_proto.meta.current_version_number
+        if cvn == -1:
+            feature_view.current_version_number = None
+        elif cvn > 0:
+            feature_view.current_version_number = cvn
+        elif cvn == 0 and feature_view_proto.spec.version:
             feature_view.current_version_number = 0
         else:
             feature_view.current_version_number = None
diff --git a/sdk/python/feast/infra/registry/registry.py b/sdk/python/feast/infra/registry/registry.py
@@ -229,6 +229,12 @@ def __init__(
             else False
         )
 
+        self.enable_versioning = (
+            registry_config.enable_feature_view_versioning
+            if registry_config is not None
+            else False
+        )
+
         self.cache_mode = (
             registry_config.cache_mode if registry_config is not None else "sync"
         )
@@ -622,6 +628,11 @@ def _save_version_record(
     def list_feature_view_versions(
         self, name: str, project: str
     ) -> List[Dict[str, Any]]:
+        if not self.enable_versioning:
+            raise ValueError(
+                "Feature view versioning is not enabled. "
+                "Set 'enable_feature_view_versioning: true' under 'registry' in feature_store.yaml."
+            )
         history = self.cached_registry_proto.feature_view_version_history
         results = []
         for record in history.records:
@@ -641,6 +652,11 @@ def list_feature_view_versions(
     def get_feature_view_by_version(
         self, name: str, project: str, version_number: int, allow_cache: bool = False
     ) -> BaseFeatureView:
+        if not self.enable_versioning:
+            raise ValueError(
+                "Feature view versioning is not enabled. "
+                "Set 'enable_feature_view_versioning: true' under 'registry' in feature_store.yaml."
+            )
         record = self._get_version_record(name, project, version_number)
         if record is None:
             raise FeatureViewVersionNotFound(name, version_tag(version_number), project)
@@ -663,6 +679,13 @@ def apply_feature_view(
         fv_type_str = self._infer_fv_type_string(feature_view)
         is_latest, pin_version = parse_version(feature_view.version)
 
+        if not self.enable_versioning and not is_latest:
+            raise ValueError(
+                f"Cannot pin '{feature_view.name}' to '{feature_view.version}': "
+                f"versioning is disabled. Set 'enable_feature_view_versioning: true' "
+                f"under 'registry' in feature_store.yaml."
+            )
+
         if not is_latest:
             # Pin to a specific version
             record = self._get_version_record(feature_view.name, project, pin_version)
@@ -770,7 +793,7 @@ def apply_feature_view(
                     break
 
         # Version history tracking
-        if is_latest:
+        if self.enable_versioning and is_latest:
             if old_proto_bytes is not None:
                 # FV changed: save old as a version if first time, then save new
                 next_ver = self._next_version_number(feature_view.name, project)
diff --git a/sdk/python/feast/infra/registry/sql.py b/sdk/python/feast/infra/registry/sql.py
@@ -294,6 +294,7 @@ def __init__(
             registry_config.thread_pool_executor_worker_count
         )
         self.purge_feast_metadata = registry_config.purge_feast_metadata
+        self.enable_versioning = registry_config.enable_feature_view_versioning
         super().__init__(
             project=project,
             cache_ttl_seconds=registry_config.cache_ttl_seconds,
@@ -625,6 +626,13 @@ def apply_feature_view(
 
         is_latest, pin_version = parse_version(feature_view.version)
 
+        if not self.enable_versioning and not is_latest:
+            raise ValueError(
+                f"Cannot pin '{feature_view.name}' to '{feature_view.version}': "
+                f"versioning is disabled. Set 'enable_feature_view_versioning: true' "
+                f"under 'registry' in feature_store.yaml."
+            )
+
         if not is_latest:
             # Pin to a specific version: load snapshot and apply it
             snapshot = self._get_version_snapshot(
@@ -705,6 +713,9 @@ def apply_feature_view(
             else:
                 return  # shouldn't happen
 
+        if not self.enable_versioning:
+            return
+
         if old_proto_bytes is not None:
             # Deserialize both versions to compare schema/UDF changes
             proto_class, fv_class = self._proto_class_for_type(fv_type_str)
@@ -1100,6 +1111,11 @@ def _get_version_snapshot(
     def get_feature_view_by_version(
         self, name: str, project: str, version_number: int, allow_cache: bool = False
     ) -> BaseFeatureView:
+        if not self.enable_versioning:
+            raise ValueError(
+                "Feature view versioning is not enabled. "
+                "Set 'enable_feature_view_versioning: true' under 'registry' in feature_store.yaml."
+            )
         snapshot = self._get_version_snapshot(name, project, version_number)
         if snapshot is None:
             raise FeatureViewVersionNotFound(name, version_tag(version_number), project)
@@ -1113,6 +1129,11 @@ def get_feature_view_by_version(
     def list_feature_view_versions(
         self, name: str, project: str
     ) -> List[Dict[str, Any]]:
+        if not self.enable_versioning:
+            raise ValueError(
+                "Feature view versioning is not enabled. "
+                "Set 'enable_feature_view_versioning: true' under 'registry' in feature_store.yaml."
+            )
         with self.read_engine.begin() as conn:
             stmt = (
                 select(feature_view_version_history)
diff --git a/sdk/python/feast/on_demand_feature_view.py b/sdk/python/feast/on_demand_feature_view.py
@@ -507,6 +507,8 @@ def to_proto(self) -> OnDemandFeatureViewProto:
             meta.last_updated_timestamp.FromDatetime(self.last_updated_timestamp)
         if self.current_version_number is not None:
             meta.current_version_number = self.current_version_number
+        else:
+            meta.current_version_number = -1
         sources = {}
         for source_name, fv_projection in self.source_feature_view_projections.items():
             sources[source_name] = OnDemandSource(
@@ -600,14 +602,12 @@ def from_proto(
         on_demand_feature_view_obj.version = (
             on_demand_feature_view_proto.spec.version or "latest"
         )
-        if on_demand_feature_view_proto.meta.current_version_number:
-            on_demand_feature_view_obj.current_version_number = (
-                on_demand_feature_view_proto.meta.current_version_number
-            )
-        elif (
-            on_demand_feature_view_proto.meta.current_version_number == 0
-            and on_demand_feature_view_proto.spec.version
-        ):
+        cvn = on_demand_feature_view_proto.meta.current_version_number
+        if cvn == -1:
+            on_demand_feature_view_obj.current_version_number = None
+        elif cvn > 0:
+            on_demand_feature_view_obj.current_version_number = cvn
+        elif cvn == 0 and on_demand_feature_view_proto.spec.version:
             on_demand_feature_view_obj.current_version_number = 0
         else:
             on_demand_feature_view_obj.current_version_number = None
diff --git a/sdk/python/feast/repo_config.py b/sdk/python/feast/repo_config.py
@@ -167,6 +167,11 @@ class RegistryConfig(FeastBaseModel):
         Once this is set to True, it cannot be reverted back to False. Reverting back to False will
         only reset the project but not all the projects"""
 
+    enable_feature_view_versioning: StrictBool = False
+    """ bool: Enable feature view version history tracking. When True, schema changes
+        create version snapshots and version-qualified refs (e.g., 'fv@v2:feature') are
+        supported. Defaults to False. """
+
     @field_validator("path")
     def validate_path(cls, path: str, values: ValidationInfo) -> str:
         if values.data.get("registry_type") == "sql":
diff --git a/sdk/python/feast/stream_feature_view.py b/sdk/python/feast/stream_feature_view.py
@@ -387,11 +387,12 @@ def from_proto(cls, sfv_proto):
             stream_feature_view.stream_source = stream_source
 
         # Restore current_version_number from meta.
-        if sfv_proto.meta.current_version_number:
-            stream_feature_view.current_version_number = (
-                sfv_proto.meta.current_version_number
-            )
-        elif sfv_proto.meta.current_version_number == 0 and sfv_proto.spec.version:
+        cvn = sfv_proto.meta.current_version_number
+        if cvn == -1:
+            stream_feature_view.current_version_number = None
+        elif cvn > 0:
+            stream_feature_view.current_version_number = cvn
+        elif cvn == 0 and sfv_proto.spec.version:
             stream_feature_view.current_version_number = 0
         else:
             stream_feature_view.current_version_number = None
diff --git a/sdk/python/feast/utils.py b/sdk/python/feast/utils.py
@@ -1297,6 +1297,12 @@ def _get_feature_views_to_use(
     fvs_to_use, od_fvs_to_use = [], []
     for name, version_num, projection in feature_views:
         if version_num is not None:
+            if not getattr(registry, "enable_versioning", False):
+                raise ValueError(
+                    f"Version-qualified ref '{name}@v{version_num}' not supported: "
+                    f"versioning is disabled. Set 'enable_feature_view_versioning: true' "
+                    f"under 'registry' in feature_store.yaml."
+                )
             # Version-qualified reference: look up the specific version snapshot
             try:
                 fv = registry.get_feature_view_by_version(
diff --git a/sdk/python/tests/integration/registration/test_versioning.py b/sdk/python/tests/integration/registration/test_versioning.py
@@ -19,7 +19,19 @@
 
 @pytest.fixture
 def registry():
-    """Create a file-based Registry for testing."""
+    """Create a file-based Registry for testing with versioning enabled."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        registry_path = Path(tmpdir) / "registry.pb"
+        config = RegistryConfig(
+            path=str(registry_path), enable_feature_view_versioning=True
+        )
+        reg = Registry("test_project", config, None)
+        yield reg
+
+
+@pytest.fixture
+def registry_no_versioning():
+    """Create a file-based Registry for testing with versioning disabled (default)."""
     with tempfile.TemporaryDirectory() as tmpdir:
         registry_path = Path(tmpdir) / "registry.pb"
         config = RegistryConfig(path=str(registry_path))
@@ -800,3 +812,70 @@ def test_version_metadata_backward_compatibility(self, registry, make_fv):
         # Should work and not include version metadata
         assert len(response.metadata.feature_view_metadata) == 0
         assert len(response.metadata.feature_names.val) == 1
+
+
+class TestVersioningDisabled:
+    """Tests that versioning behavior is properly disabled by default."""
+
+    def test_apply_does_not_create_version_history(
+        self, registry_no_versioning, make_fv, entity
+    ):
+        """When versioning is disabled, current_version_number stays None."""
+        fv = make_fv(description="no versioning")
+        registry_no_versioning.apply_feature_view(fv, "test_project", commit=True)
+
+        active_fv = registry_no_versioning.get_feature_view(
+            "driver_stats", "test_project"
+        )
+        assert active_fv.current_version_number is None
+
+        # Apply a schema change — still no version history
+        fv2 = FeatureView(
+            name="driver_stats",
+            entities=[entity],
+            ttl=timedelta(days=1),
+            schema=[
+                Field(name="driver_id", dtype=Int64),
+                Field(name="trips_today", dtype=Int64),
+                Field(name="avg_rating", dtype=Float32),
+                Field(name="new_feature", dtype=Float32),
+            ],
+            description="changed schema",
+        )
+        registry_no_versioning.apply_feature_view(fv2, "test_project", commit=True)
+
+        active_fv2 = registry_no_versioning.get_feature_view(
+            "driver_stats", "test_project"
+        )
+        assert active_fv2.current_version_number is None
+
+    def test_pin_to_version_raises_when_disabled(self, registry_no_versioning, make_fv):
+        """Pinning to a version raises ValueError when versioning is disabled."""
+        fv = make_fv(description="no versioning")
+        registry_no_versioning.apply_feature_view(fv, "test_project", commit=True)
+
+        fv_pin = make_fv(version="v0")
+        with pytest.raises(ValueError, match="versioning is disabled"):
+            registry_no_versioning.apply_feature_view(
+                fv_pin, "test_project", commit=True
+            )
+
+    def test_list_versions_raises_when_disabled(self, registry_no_versioning, make_fv):
+        """list_feature_view_versions raises ValueError when versioning is disabled."""
+        fv = make_fv(description="no versioning")
+        registry_no_versioning.apply_feature_view(fv, "test_project", commit=True)
+
+        with pytest.raises(ValueError, match="versioning is not enabled"):
+            registry_no_versioning.list_feature_view_versions(
+                "driver_stats", "test_project"
+            )
+
+    def test_get_by_version_raises_when_disabled(self, registry_no_versioning, make_fv):
+        """get_feature_view_by_version raises ValueError when versioning is disabled."""
+        fv = make_fv(description="no versioning")
+        registry_no_versioning.apply_feature_view(fv, "test_project", commit=True)
+
+        with pytest.raises(ValueError, match="versioning is not enabled"):
+            registry_no_versioning.get_feature_view_by_version(
+                "driver_stats", "test_project", 0
+            )

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,8 @@ Create a list of features that you would like to retrieve. This list typically c`
`22`	`22`	`features = [`
`23`	`23`	`"driver_hourly_stats:conv_rate",`
`24`	`24`	`"driver_hourly_stats:acc_rate",`
`25`		`- # Optionally, reference a specific version: "driver_hourly_stats@v2:conv_rate"`
	`25`	`+ # Optionally, reference a specific version (requires enable_feature_view_versioning):`
	`26`	`+ # "driver_hourly_stats@v2:conv_rate"`
`26`	`27`	`]`
`27`	`28`	```
`28`	`29`