feast-dev · franciscojavierarceo · Mar 26, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 13, 2026
@@ -160,6 +160,103 @@ Feature names must be unique within a [feature view](feature-view.md#feature-vie
 
 Each field can have additional metadata associated with it, specified as key-value [tags](https://rtd.feast.dev/en/master/feast.html#feast.field.Field).
 
+## Versioning
+
+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.
+
+### How it works
+
+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.
+3. **Re-apply without changes** — Nothing happens. Feast compares the new definition against the active one and skips creating a version if they're identical (idempotent).
+4. **Another change** — Creates **v2**, and so on.
+
+```
+feast apply                  # First apply → v0
+# ... edit schema ...
+feast apply                  # Detects change → v1
+feast apply                  # No change detected → still v1 (no new version)
+# ... edit source ...
+feast apply                  # Detects change → v2
+```
+
+**Key details:**
+
+* **Automatic snapshots**: Versions are created only when Feast detects an actual change to the feature view definition. No new version is created for identical re-applies.
+* **Separate history storage**: Version history is stored separately from the active feature view definition, keeping the main registry lightweight.
+* **Backward compatible**: The `version` parameter is fully optional. Omitting it (or setting `version="latest"`) preserves existing behavior — you get automatic versioning with zero changes to your code.
+
+### Pinning to a specific version
+
+You can pin a feature view to a specific historical version by setting the `version` parameter. When pinned, `feast apply` replaces the active feature view with the snapshot from that version. This is useful for reverting to a known-good definition.
+
+```python
+from feast import FeatureView
+
+# Default behavior: always use the latest version (auto-increments on changes)
+driver_stats = FeatureView(
+    name="driver_stats",
+    entities=[driver],
+    schema=[...],
+    source=my_source,
+)
+
+# Pin to a specific version (reverts the active definition to v2's snapshot)
+driver_stats = FeatureView(
+    name="driver_stats",
+    entities=[driver],
+    schema=[...],
+    source=my_source,
+    version="v2",  # also accepts "version2"
+)
+```
+
+When pinning, the other constructor parameters (schema, source, etc.) are ignored — the snapshot's content is used instead. Version history is not modified by a pin; the existing v0, v1, v2, etc. snapshots remain intact.
+
+After reverting with a pin, you can go back to normal auto-incrementing behavior by removing the `version` parameter (or setting it to `"latest"`) and running `feast apply` again. If the restored definition differs from the pinned snapshot, a new version will be created.
+
+### Version string formats
+
+| Format | Meaning |
+|--------|---------|
+| `"latest"` (or omitted) | Always use the latest version (auto-increments on changes) |
+| `"v0"`, `"v1"`, `"v2"`, ... | Pin to a specific version number |
+| `"version0"`, `"version1"`, ... | Equivalent long form (case-insensitive) |
+
+### Listing version history
+
+Use the CLI to inspect version history:
+
+```bash
+feast feature-views versions driver_stats
+```
+
+```text
+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-...
+v2       feature_view  2024-01-20 09:15:00  i9j0k1l2-...
+```
+
+Or programmatically via the Python SDK:
+
+```python
+store = FeatureStore(repo_path=".")
+versions = store.list_feature_view_versions("driver_stats")
+for v in versions:
+    print(f"{v['version']} created at {v['created_timestamp']}")
+```
+
+### Supported feature view types
+
+Versioning is supported on all three feature view types:
+
+* `FeatureView` (and `BatchFeatureView`)
+* `StreamFeatureView`
+* `OnDemandFeatureView`
+
 ## Schema Validation
 
 Feature views support an optional `enable_validation` parameter that enables schema validation during materialization and historical feature retrieval. When enabled, Feast verifies that:

@@ -176,6 +176,18 @@ NAME                 ENTITIES    TYPE
 driver_hourly_stats  {'driver'}  FeatureView
 ```
 
+List version history for a feature view
+
+```text
+feast feature-views versions FEATURE_VIEW_NAME
+```
+
+```text
+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-...
+```
+
 ## Init
 
 Creates a new feature repository

@@ -36,7 +36,7 @@ message FeatureView {
     FeatureViewMeta meta = 2;
 }
 
-// Next available id: 18
+// Next available id: 19
 // TODO(adchia): refactor common fields from this and ODFV into separate metadata proto
 message FeatureViewSpec {
     // Name of the feature view. Must be unique. Not updated.
@@ -94,6 +94,9 @@ message FeatureViewSpec {
 
     // Whether schema validation is enabled during materialization
     bool enable_validation = 17;
+
+    // User-specified version pin (e.g. "latest", "v2", "version2")
+    string version = 18;
 }
 
 message FeatureViewMeta {
@@ -105,6 +108,12 @@ message FeatureViewMeta {
 
     // List of pairs (start_time, end_time) for which this feature view has been materialized.
     repeated MaterializationInterval materialization_intervals = 3;
+
+    // The current version number of this feature view in the version history.
+    int32 current_version_number = 4;
+
+    // Auto-generated UUID identifying this specific version.
+    string version_id = 5;
 }
 
 message MaterializationInterval {

@@ -0,0 +1,42 @@
+//
+// Copyright 2024 The Feast Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+syntax = "proto3";
+package feast.core;
+
+option go_package = "github.com/feast-dev/feast/go/protos/feast/core";
+option java_outer_classname = "FeatureViewVersionProto";
+option java_package = "feast.proto.core";
+
+import "google/protobuf/timestamp.proto";
+
+message FeatureViewVersionRecord {
+    string feature_view_name = 1;
+    string project_id = 2;
+    int32 version_number = 3;
+    // "feature_view" | "stream_feature_view" | "on_demand_feature_view"
+    string feature_view_type = 4;
+    // serialized FV proto snapshot
+    bytes feature_view_proto = 5;
+    google.protobuf.Timestamp created_timestamp = 6;
+    string description = 7;
+    // auto-generated UUID for unique identification
+    string version_id = 8;
+}
+
+message FeatureViewVersionHistory {
+    repeated FeatureViewVersionRecord records = 1;
+}
@@ -36,7 +36,7 @@ message OnDemandFeatureView {
     OnDemandFeatureViewMeta meta = 2;
 }
 
-// Next available id: 9
+// Next available id: 18
 message OnDemandFeatureViewSpec {
     // Name of the feature view. Must be unique. Not updated.
     string name = 1;
@@ -75,6 +75,8 @@ message OnDemandFeatureViewSpec {
     // Aggregation definitions
     repeated Aggregation aggregations = 16;
 
+    // User-specified version pin (e.g. "latest", "v2", "version2")
+    string version = 17;
 }
 
 message OnDemandFeatureViewMeta {
@@ -83,6 +85,12 @@ message OnDemandFeatureViewMeta {
 
     // Time where this Feature View is last updated
     google.protobuf.Timestamp last_updated_timestamp = 2;
+
+    // The current version number of this feature view in the version history.
+    int32 current_version_number = 3;
+
+    // Auto-generated UUID identifying this specific version.
+    string version_id = 4;
 }
 
 message OnDemandSource {

@@ -1,63 +1,65 @@
-//
-// * Copyright 2020 The Feast Authors
-// *
-// * Licensed under the Apache License, Version 2.0 (the "License");
-// * you may not use this file except in compliance with the License.
-// * You may obtain a copy of the License at
-// *
-// *     https://www.apache.org/licenses/LICENSE-2.0
-// *
-// * Unless required by applicable law or agreed to in writing, software
-// * distributed under the License is distributed on an "AS IS" BASIS,
-// * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// * See the License for the specific language governing permissions and
-// * limitations under the License.
-//
-
-syntax = "proto3";
-
-package feast.core;
-option java_package = "feast.proto.core";
-option java_outer_classname = "RegistryProto";
-option go_package = "github.com/feast-dev/feast/go/protos/feast/core";
-
-import "feast/core/Entity.proto";
-import "feast/core/FeatureService.proto";
-import "feast/core/FeatureTable.proto";
-import "feast/core/FeatureView.proto";
-import "feast/core/InfraObject.proto";
-import "feast/core/OnDemandFeatureView.proto";
-import "feast/core/StreamFeatureView.proto";
-import "feast/core/DataSource.proto";
-import "feast/core/SavedDataset.proto";
-import "feast/core/ValidationProfile.proto";
-import "google/protobuf/timestamp.proto";
-import "feast/core/Permission.proto";
-import "feast/core/Project.proto";
-
-// Next id: 18
-message Registry {
-    repeated Entity entities = 1;
-    repeated FeatureTable feature_tables = 2;
-    repeated FeatureView feature_views = 6;
-    repeated DataSource data_sources = 12;
-    repeated OnDemandFeatureView on_demand_feature_views = 8;
-    repeated StreamFeatureView stream_feature_views = 14;
-    repeated FeatureService feature_services = 7;
-    repeated SavedDataset saved_datasets = 11;
-    repeated ValidationReference validation_references = 13;
-    Infra infra = 10;
-    // Tracking metadata of Feast by project
-    repeated ProjectMetadata project_metadata = 15 [deprecated = true];
-
-    string registry_schema_version = 3; // to support migrations; incremented when schema is changed
-    string version_id = 4; // version id, random string generated on each update of the data; now used only for debugging purposes
-    google.protobuf.Timestamp last_updated = 5;
-    repeated Permission permissions = 16;
-    repeated Project projects = 17;
-}
-
-message ProjectMetadata {
-    string project = 1;
-    string project_uuid = 2;
-}
+//
+// * Copyright 2020 The Feast Authors
+// *
+// * Licensed under the Apache License, Version 2.0 (the "License");
+// * you may not use this file except in compliance with the License.
+// * You may obtain a copy of the License at
+// *
+// *     https://www.apache.org/licenses/LICENSE-2.0
+// *
+// * Unless required by applicable law or agreed to in writing, software
+// * distributed under the License is distributed on an "AS IS" BASIS,
+// * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// * See the License for the specific language governing permissions and
+// * limitations under the License.
+//
+
+syntax = "proto3";
+
+package feast.core;
+option java_package = "feast.proto.core";
+option java_outer_classname = "RegistryProto";
+option go_package = "github.com/feast-dev/feast/go/protos/feast/core";
+
+import "feast/core/Entity.proto";
+import "feast/core/FeatureService.proto";
+import "feast/core/FeatureTable.proto";
+import "feast/core/FeatureView.proto";
+import "feast/core/InfraObject.proto";
+import "feast/core/OnDemandFeatureView.proto";
+import "feast/core/StreamFeatureView.proto";
+import "feast/core/DataSource.proto";
+import "feast/core/SavedDataset.proto";
+import "feast/core/ValidationProfile.proto";
+import "google/protobuf/timestamp.proto";
+import "feast/core/Permission.proto";
+import "feast/core/Project.proto";
+import "feast/core/FeatureViewVersion.proto";
+
+// Next id: 19
+message Registry {
+    repeated Entity entities = 1;
+    repeated FeatureTable feature_tables = 2;
+    repeated FeatureView feature_views = 6;
+    repeated DataSource data_sources = 12;
+    repeated OnDemandFeatureView on_demand_feature_views = 8;
+    repeated StreamFeatureView stream_feature_views = 14;
+    repeated FeatureService feature_services = 7;
+    repeated SavedDataset saved_datasets = 11;
+    repeated ValidationReference validation_references = 13;
+    Infra infra = 10;
+    // Tracking metadata of Feast by project
+    repeated ProjectMetadata project_metadata = 15 [deprecated = true];
+
+    string registry_schema_version = 3; // to support migrations; incremented when schema is changed
+    string version_id = 4; // version id, random string generated on each update of the data; now used only for debugging purposes
+    google.protobuf.Timestamp last_updated = 5;
+    repeated Permission permissions = 16;
+    repeated Project projects = 17;
+    FeatureViewVersionHistory feature_view_version_history = 18;
+}
+
+message ProjectMetadata {
+    string project = 1;
+    string project_uuid = 2;
+}
@@ -37,7 +37,7 @@ message StreamFeatureView {
     FeatureViewMeta meta = 2;
 }
 
-// Next available id: 21
+// Next available id: 22
 message StreamFeatureViewSpec {
     // Name of the feature view. Must be unique. Not updated.
     string name = 1;
@@ -102,5 +102,8 @@ message StreamFeatureViewSpec {
 
     // Whether schema validation is enabled during materialization
     bool enable_validation = 20;
+
+    // User-specified version pin (e.g. "latest", "v2", "version2")
+    string version = 21;
 }
 
@@ -56,6 +56,8 @@ class BaseFeatureView(ABC):
     projection: FeatureViewProjection
     created_timestamp: Optional[datetime]
     last_updated_timestamp: Optional[datetime]
+    version: str
+    current_version_number: Optional[int]
 
     @abstractmethod
     def __init__(
@@ -92,6 +94,10 @@ def __init__(
         self.projection = FeatureViewProjection.from_definition(self)
         self.created_timestamp = None
         self.last_updated_timestamp = None
+        if not hasattr(self, "version"):
+            self.version = "latest"
+        if not hasattr(self, "current_version_number"):
+            self.current_version_number = None
 
         self.source = source