feat: Add version tracking to FeatureView

[franciscojavierarceo]

Summary

• Adds version tracking to FeatureView, StreamFeatureView, and OnDemandFeatureView
• Every feast apply creates a version snapshot in a separate history store (new SQL table / proto field)
• Users can pin a feature view to a specific historical version declaratively: FeatureView(name="driver_stats", version="v2")
• By default (version="latest" or omitted), the latest version is always served — fully backward compatible

Changes

Proto layer:

• New FeatureViewVersion.proto with FeatureViewVersionRecord / FeatureViewVersionHistory
• Added version field to FeatureViewSpec, StreamFeatureViewSpec, OnDemandFeatureViewSpec
• Added current_version_number / version_id to meta messages
• Added feature_view_version_history to Registry proto

Python SDK:

• New version_utils.py — parses "latest", "v2", "version2" (case-insensitive)
• New FeatureViewVersionNotFound error class
• version parameter on FeatureView, StreamFeatureView, OnDemandFeatureView
• Version-aware apply_feature_view in both SQL registry and file/proto registry
• list_feature_view_versions(name, project) on registries and FeatureStore
• CLI: feast feature-views versions <name> subcommand
• Updated 14 templates with explicit version="latest"

Backward compatibility:

• version is fully optional — omitting it is identical to version="latest"
• All new proto fields are additive; old protos deserialize correctly
• SQL: metadata.create_all(checkfirst=True) auto-creates the new history table
• Existing idempotency behavior preserved

Test plan

• 28 unit tests: version parsing, normalization, proto roundtrip, equality, copy
• 7 integration tests: apply/version creation, idempotency, pinning, error cases
• Pre-commit hooks pass (format, lint, detect-secrets)
• CI: existing unit tests pass (no regressions)

🤖 Generated with Claude Code

Resolves #2728

---

[devin-ai-integration]

Devin Review found 1 new potential issue.

🐛 1 issue in files not directly in the diff

🐛 BatchFeatureView missing version parameter — incomplete transformation (sdk/python/feast/batch_feature_view.py:80-102)

FeatureView, StreamFeatureView, and OnDemandFeatureView all accept a version parameter in their constructors, but BatchFeatureView.__init__ (sdk/python/feast/batch_feature_view.py:80-102) does not. Furthermore, BatchFeatureView.__init__ does not pass version to super().__init__() at sdk/python/feast/batch_feature_view.py:144-158. This means users cannot construct a BatchFeatureView with a pinned version (e.g., BatchFeatureView(..., version="v2") raises TypeError), and any BatchFeatureView created directly always defaults to version="latest". The proto round-trip path works because FeatureView.from_proto sets feature_view.version after construction, but the constructor API is inconsistent with the other feature view types.

View 19 additional findings in Devin Review.

[devin-ai-integration]

Devin Review found 1 new potential issue.

🐛 1 issue in files not directly in the diff

🐛 BatchFeatureView missing version parameter — incomplete transformation (sdk/python/feast/batch_feature_view.py:80-102)

FeatureView, StreamFeatureView, and OnDemandFeatureView all accept a version parameter in their constructors, but BatchFeatureView.__init__ (sdk/python/feast/batch_feature_view.py:80-102) does not. Furthermore, BatchFeatureView.__init__ does not pass version to super().__init__() at sdk/python/feast/batch_feature_view.py:144-158. This means users cannot construct a BatchFeatureView with a pinned version (e.g., BatchFeatureView(..., version="v2") raises TypeError), and any BatchFeatureView created directly always defaults to version="latest". The proto round-trip path works because FeatureView.from_proto sets feature_view.version after construction, but the constructor API is inconsistent with the other feature view types.

View 23 additional findings in Devin Review.

[devin-ai-integration]

Devin Review found 5 new potential issues.

View 23 additional findings in Devin Review.

[devin-ai-integration]

🟡 Version-qualified online reads with full_feature_names=True produce response columns containing @v<N> that get dropped

When using versioned feature references like driver_stats@v2:trips_today with full_feature_names=True, the requested_result_row_names set at sdk/python/feast/utils.py:1379-1381 is built by replacing : with __, producing driver_stats@v2__trips_today. However, the _populate_response_from_feature_data function at sdk/python/feast/utils.py:1112-1114 also uses table.projection.name_to_use() which includes @v2 in the name. So both sides contain @v2, and the match succeeds.

However, the @ character in column names like driver_stats@v2__trips_today is unusual and may break downstream consumers (e.g., pandas DataFrames using attribute access, or other systems expecting simple alphanumeric column names). This is a design concern rather than a runtime crash.

(Refers to lines 1379-1381)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 SqlRegistry apply_feature_view version snapshot stores proto with stale current_version_number

In SqlRegistry.apply_feature_view at lines 721-728, new_proto_bytes is read from the database before current_version_number is updated. The new_proto_bytes was written by _apply_object which serialized the FV without the correct current_version_number (since it hadn't been assigned yet). This stale proto is then saved as the version snapshot via _save_version_snapshot. Later at lines 730-743, current_version_number is set and the active proto is updated, but the snapshot in the version history table still contains the wrong current_version_number. When someone later retrieves this version via get_feature_view_by_version, the snapshot's current_version_number in the proto meta will be incorrect (it will have whatever value was there before the update).

Prompt for agents

In sdk/python/feast/infra/registry/sql.py, in the apply_feature_view method around lines 721-743, the version snapshot is saved using new_proto_bytes that was read from the DB before current_version_number was assigned. The snapshot should instead be created after updating feature_view.current_version_number so it contains the correct version metadata. Move the _save_version_snapshot call for the new version to after line 730 (where current_version_number is set), and use the re-serialized proto bytes (feature_view.to_proto().SerializeToString()) instead of the stale new_proto_bytes. The same issue exists in the 'new FV' branch at lines 745-752 where new_proto_bytes is used before current_version_number=0 is assigned.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 File Registry apply_feature_view saves new version snapshot with stale proto bytes (before current_version_number is set)

In Registry.apply_feature_view at sdk/python/feast/infra/registry/registry.py:700-722, the new version snapshot is saved using new_proto_bytes obtained at line 700 which is serialized before current_version_number is updated at line 712. The snapshot saved at line 709-711 for the new version thus contains a stale current_version_number in its proto metadata. This means that retrieving the version snapshot later via get_feature_view_by_version will return a FV whose proto metadata has the wrong version number. The same issue exists in the 'new FV' branch at lines 715-722 where the snapshot is saved from new_proto_bytes before current_version_number = 0 is assigned at line 720.

Prompt for agents

In sdk/python/feast/infra/registry/registry.py in the apply_feature_view method, the version snapshots saved at lines 709-711 and 717-719 use new_proto_bytes that was serialized before current_version_number was assigned. Fix both branches: (1) For the 'FV changed' branch (lines 701-714), move the _save_version_record call for new_proto_bytes to after line 712 where current_version_number is set, and re-serialize the proto. (2) For the 'New FV' branch (lines 715-722), set current_version_number = 0 before calling _save_version_record, and re-serialize the proto. This ensures version snapshots contain accurate current_version_number metadata.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[tokoko]

I haven't been able to go through the whole thing yet, but iiuc the expectation is that online stores would be expected to handle this by essentially treating fv1@v1 and fv1@v2 as two different feature views, right? (sqlite example infers table name from the version). Just wondering, maybe that's to high a bat for online store implementations. for example, if you have fv1@v1 and fv1@v2 both containing 100 features that differ by a single feature only, the online store would have to keep redundant copies of the other 99 features or do some complicated logic to diff values and deduplicate.

wdyt about concentrating on introducing versioning on feature level instead? tbh, that makes more intuitive sense to me. there's a feature called income that one found a fault with. we enable them to introduce income@v2 and somehow deprecate income@v1. online store can handle income@v1 and income@v2 as separate features, but all the rest of the features are unaffected.

[franciscojavierarceo]

I haven't been able to go through the whole thing yet, but iiuc the expectation is that online stores would be expected to handle this by essentially treating fv1@v1 and fv1@v2 as two different feature views, right? (sqlite example infers table name from the version). Just wondering, maybe that's to high a bat for online store implementations. for example, if you have fv1@v1 and fv1@v2 both containing 100 features that differ by a single feature only, the online store would have to keep redundant copies of the other 99 features or do some complicated logic to diff values and deduplicate.

wdyt about concentrating on introducing versioning on feature level instead? tbh, that makes more intuitive sense to me. there's a feature called income that one found a fault with. we enable them to introduce income@v2 and somehow deprecate income@v1. online store can handle income@v1 and income@v2 as separate features, but all the rest of the features are unaffected.

I spent some time reasoning about feature-level versioning with Claude. My initial reaction was that it's too large of a change and it only works today in a broken sense.

By "in a broken sense" I mean that today we don't really version feature views or features, if someone changes the feature view or the feature, we just overwrite it and lose history. Moreover, we essentially force the materialization to be out of sync. Today, that just ignores the behavior silently.

I like how we've implemented it here (i.e., creating a new table and storing the history of the metadata but allowing for callers to specify exact versions and defaulting to the existing behavior) because it is far more explicit about the challenges of materialization consistency issues when you change feature versions.

So, I don't recommend we do feature-level versioning as I worry it makes materialization very unreliable. We can, in fact, declare feature view level versioning because transformations are a collection of features mapped one-to-one with a table.