/feast-architecture

name: feast-architecture
description: Internals of the Feast codebase — how each component works, where the key abstractions live, and the data flow through the system. Use when asked how feast apply works, how the registry stores data, how materialization moves data, how get_online_features retrieves features, how the feature server works, how the Kubernetes operator manages deployments, or when navigating the codebase to understand where to make a change.
license: Apache-2.0
compatibility: Works with Claude Code, OpenAI Codex, and any Agent Skills compatible tool.
metadata:
  author: feast-dev
  version: "1.0"

Feast Architecture Internals

Full Component Map

┌─────────────────────────────────────────────────────────────────┐
│                     Feast Deployment Modes                       │
│                                                                   │
│  Local / Python SDK          Kubernetes (feast-operator)          │
│  ─────────────────           ─────────────────────────────────   │
│  feature_store.yaml    ←──   FeatureStore CR (CRD)               │
│        │                            │                             │
│        ▼                            ▼                             │
│  FeatureStore (Python)      Operator deploys services:            │
│    ├── Registry               - feature-server (Go or Python)     │
│    ├── Provider               - offline-store-server              │
│    │   ├── OnlineStore        - registry-server                   │
│    │   └── OfflineStore     + manages feature_store.yaml config   │
│    └── FeatureServer                                              │
│        (Python FastAPI or                                         │
│         Go gRPC/HTTP)                                             │
└─────────────────────────────────────────────────────────────────┘

---

Python SDK Core

FeatureStore — the orchestrator

**File**: `sdk/python/feast/feature_store.py`

`FeatureStore` is the single entry point for all operations. It never reads/writes data directly — it delegates to the registry (for metadata) and the provider (for infrastructure and data movement).

FeatureStore(repo_path=".")   # loads feature_store.yaml
store.apply(objects)           # register feature definitions
store.materialize(...)         # offline → online
store.get_online_features(...) # serve
store.get_historical_features(...) # training data

**File**: `sdk/python/feast/repo_config.py` — parses `feature_store.yaml` into typed `RepoConfig`. All component classes (online store, offline store, registry) are loaded dynamically from the `type:` string via `repo_config.ONLINE_STORE_TYPE_MAP` / `OFFLINE_STORE_TYPE_MAP`.

---

Registry

**Purpose**: Metadata store — persists definitions of entities, feature views, data sources, feature services, permissions.

**Backends and their files:**

| Backend | File | Notes | |---|---|---| | File/GCS/S3 (default) | `infra/registry/registry.py` | Single proto blob, cached in memory | | SQL | `infra/registry/sql.py` | Per-object tables via SQLAlchemy | | Snowflake | `infra/registry/snowflake.py` | Snowflake tables | | Remote | `infra/registry/remote.py` | Delegates to a remote registry server over gRPC |

**How the proto/file backend works:** 1. All metadata is serialized into one `Registry` protobuf (`protos/feast/core/Registry.proto`) 2. The proto blob is stored at the configured `registry:` path 3. In-memory `cached_registry_proto` is refreshed on a TTL (default 10s) 4. Writes re-serialize and overwrite the full blob — no partial updates

**Key pattern — apply:**

# Python object → proto → stored in registry blob
registry.apply_feature_view(feature_view, project)
# → feature_view.to_proto()
# → upserts into cached_registry_proto.feature_views
# → registry_store.update_registry_proto(proto)

**How the SQL backend works:**

• Per-object tables, each storing that object's serialized proto in a binary column.
• **Binary proto columns must use `ProtoBytes`, not `LargeBinary` directly** (defined at the top of `infra/registry/sql.py`). `ProtoBytes` emits `LONGBLOB` on MySQL and MariaDB and falls back to `LargeBinary`'s default on every other dialect (`BLOB` on SQLite, `BYTEA` on PostgreSQL). Plain `LargeBinary` maps to MySQL `BLOB` (64 KB cap), which silently truncates large protos (e.g. a `FeatureView`) and later fails to deserialize. Any new serialized-proto/blob-metadata column reintroduces that bug if it uses `LargeBinary`.
• All tables are declared on the module-level `metadata` object in `sql.py` (the source of truth). `metadata.create_all` only creates missing tables — it never widens existing columns, so schema changes to existing registries require a manual migration (see `docs/reference/registries/sql.md`). On MySQL/MariaDB, `SqlRegistry._warn_if_narrow_blob_columns` logs an error at startup for any registry proto column still typed as the narrow `BLOB` — a new column is covered automatically as long as it's typed `ProtoBytes` (the diagnostic selects columns by `column.type is ProtoBytes`); a column typed as plain `LargeBinary` would be silently missed.

**Supporting files:**

• `infra/registry/base_registry.py` — abstract interface
• `infra/registry/proto_registry_utils.py` — proto serialization helpers
• `infra/registry/caching_registry.py` — adds TTL caching on top of any backend

---

Provider

**Purpose**: Infrastructure lifecycle — creates/updates/tears down online store tables. Also dispatches `online_write_batch` and `get_historical_features`.

**File**: `sdk/python/feast/infra/provider.py`

Built-in providers (set via `provider:` in `feature_store.yaml`):

• `local` — SQLite online store, file offline (dev default)
• `gcp` — Datastore/Bigtable online, BigQuery offline
• `aws` — DynamoDB online, Redshift offline

Custom providers extend `Provider` and override `update_infra` / `teardown_infra`.

---

Online Store

**Purpose**: Low-latency feature s