Migration Tooling

Zipline Enterprise provides a structured migration program for moving feature workloads from legacy feature platforms and bespoke pipelines to Zipline. The program is designed to reduce migration risk in stages: first prove that the feature contracts are equivalent, then compare historical values, and finally validate live serving behavior before shifting production traffic.

Enterprise availability: Migration tooling is delivered as part of a Zipline Enterprise migration engagement. The workflow below describes the target experience; the exact integrations and level of automation depend on the legacy platform and the customer's Zipline deployment.

Migration at a glance

Phase Question answered Primary operation Exit gate
1. Semantic migration Did we translate the feature contract correctly? Metadata-only validation Every expected feature has a compatible output name and type
2. Offline data comparison Does Zipline reproduce historical feature values? Bounded backfill and type-aware comparison Agreed value-level thresholds pass on a representative date range
3. Online data comparison Does Zipline behave correctly on production requests? Shadow fetching and log comparison Live feature vectors pass the same comparison policy at production scale

Each phase produces a reviewable report and an explicit go/no-go decision. Teams can migrate one feature service or domain at a time rather than coordinating a single cutover for the entire feature estate.

Phase 1: Semantic migration

Phase 1 translates the existing feature definitions into Zipline configuration and proves that the resulting output contract matches the legacy system. It intentionally does not run a backfill, scan historical feature data, or write to an online store.

The migration input can include:

  • Legacy feature definitions, repositories, and feature service manifests
  • Platform documentation and team-specific conventions
  • Source table and stream metadata
  • Existing feature names, keys, types, windows, and ownership metadata

The Zipline Enterprise migration agent uses an LLM to interpret those inputs and generate version-controlled Zipline Source, GroupBy, Join, and StagingQuery definitions. Generated code is intended to be reviewed like any other production change; the source definitions and documentation remain the system of record for why each translation was made.

Zipline Validator

The Zipline Validator extends the lightweight configuration analysis exposed by zipline hub eval. It resolves dependencies, compiles SQL expressions, infers the complete Zipline output schema, and aligns that schema with the contract currently produced by the legacy system.

Because this phase compares metadata rather than values, it can find translation errors early without paying for a large data operation. Typical findings include a renamed feature, an incompatible numeric width, a missing key, an incorrect aggregation window, or a list translated as a scalar.

The following is illustrative CLI output from a migration validation:

 
OUTPUT SCHEMA ALIGNMENT
 
  FEATURE                         LEGACY TYPE          ZIPLINE TYPE         STATUS
  ──────────────────────────────  ───────────────────  ───────────────────  ──────
  user_id                         string               string               MATCH
  event_timestamp                long                 long                 MATCH
  total_spend_30d                 double               double               MATCH
  transaction_count_7d            long                 long                 MATCH
  recent_merchant_ids             array<string>        array<string>        MATCH
  risk_band                       string               string               MATCH
 
  Keys                            [user_id]             [user_id]            MATCH
  Features                        4                     4                    MATCH
 

Phase 1 is complete when every expected output is accounted for, all types are compatible, and the owning team has reviewed any translation assumptions. Passing semantic validation is necessary, but it does not claim that the two systems produce identical values; that is the purpose of Phase 2.

Phase 2: Offline data comparison

Phase 2 runs the migrated Zipline definitions over a bounded historical interval and compares the result with legacy output for the same entities and observation times.

The usual workflow is:

  1. Select a representative interval that covers normal traffic, sparse keys, and important calendar boundaries.
  2. Run a Zipline backfill for that interval.
  3. Align legacy and Zipline rows by entity keys and observation time.
  4. Apply type-aware comparison metrics to every feature.
  5. Review mismatches, adjust the migration if necessary, and repeat until the agreed gates pass.

The data comparison tool shares the same core semantics as Zipline's online/offline consistency framework. Every feature receives coverage and null-asymmetry metrics; additional metrics are selected from the feature's data type.

Comparison metrics by feature type

Feature type Comparisons What the report reveals
All supported types Total aligned rows, both-null count, legacy-only nulls, Zipline-only nulls, and non-null mismatch rate Missing keys, coverage regressions, default-value differences, and exact-match rate
Numeric scalars SMAPE, Zipline - legacy delta distribution, and quantiles/distributions for both systems Relative error, systematic bias, scale differences, and outliers
Boolean, string, and enum-like scalars Exact mismatch rate, null asymmetry, and representative mismatched pairs Encoding, normalization, casing, and category-mapping errors
Lists and sequences Length distributions, length-mismatch rate, and edit-distance insert/delete distributions Ordering differences and missing or extra sequence elements
Maps and structs Key-set differences and recursive comparison of supported child values; normalized equality where field-level comparison is unavailable Missing or extra keys and localized nested-value mismatches

Example comparison report

The following illustrative report summarizes 1,250,000 aligned rows from a seven-day backfill. Match and mismatch rates use exact equality; type-specific metrics determine whether an inexact feature is still within its migration tolerance.

Feature Type Match rate Mismatch rate Null asymmetry Type-specific result Acceptance policy Status
transaction_count_7d long 99.999% 0.001% 0.000% Mean SMAPE: 0.002% Mismatch ≤ 0.01% PASS
total_spend_30d double 98.740% 1.260% 0.020% Mean SMAPE: 0.08%; p95 absolute delta: $0.03 Mean SMAPE ≤ 0.10% PASS
risk_band string 99.920% 0.080% 0.010% Top mismatch: LOW → MEDIUM (612 rows) Mismatch ≤ 0.05% FAIL
is_verified boolean 100.000% 0.000% 0.000% No mismatched pairs Exact match required PASS
recent_merchant_ids array<string> 99.600% 0.400% 0.030% Length mismatch: 0.12%; p95 edit distance: 1 Length mismatch ≤ 0.20% PASS

Result: 4 of 5 features pass. The failed risk_band mapping must be investigated and the comparison rerun before Phase 2 can complete.

Comparison policies are set per feature or feature class. Exact counters and categorical features may require zero mismatches, while floating-point features can use tolerances appropriate to their source data and aggregation semantics. The Phase 2 report records the policy, the observed metrics, sample mismatches, and the final pass/fail decision.

Phase 2 is complete when the backfill covers an agreed representative interval and all blocking comparison policies pass. The accepted policy becomes the baseline for live validation in Phase 3.

Phase 3: Online data comparison

Phase 3 validates the new Zipline serving path against production requests without making Zipline authoritative for the response. In shadow mode, the serving integration assigns a correlation ID before sending the authoritative request to the legacy feature service and a sampled, asynchronous copy to the Zipline Fetcher. Each system writes its own feature-vector log with that correlation ID, the observation timestamp, and the feature-service version.

ONLINE REQUEST PATH
 
                            ┌──────────────────────────┐
Production request ────────▶│ Serving integration      │
                            │ assigns correlation ID   │
                            └────────────┬─────────────┘
                                         │
                       ┌─────────────────┴─────────────────┐
                       │ synchronous                       │ sampled + async
                       ▼                                   ▼
             ┌───────────────────┐               ┌───────────────────┐
             │ Legacy feature    │               │ Zipline Fetcher   │
             │ service           │               │ shadow request    │
             │ authoritative     │               └─────────┬─────────┘
             └────────┬──────────┘                         │
                      │                                    └──▶ shadow vector log
                      ├──▶ response used by application
                      └──▶ production vector log
 
 
OFFLINE COMPARISON PATH
 
┌────────────────────────┐
│ Production vector logs │──┐
└────────────────────────┘  │    ┌──────────────────────────┐
                            ├───▶│ Full outer join          │
┌────────────────────────┐  │    │                          │
│ Zipline shadow logs    │──┘    │ • correlation ID         │
└────────────────────────┘       │ • service version        │
                                 │ • observation time       │
                                 └────────────┬─────────────┘
                                              ▼
                                 ┌──────────────────────────┐
                                 │ Aligned vector pairs     │
                                 │ + one-sided requests     │
                                 └────────────┬─────────────┘
                                              ▼
                                 ┌──────────────────────────┐
                                 │ Data comparison tool     │
                                 │ Phase 2 policies         │
                                 └────────────┬─────────────┘
                                              ▼
                                 ┌──────────────────────────┐
                                 │ Live validation report   │
                                 └──────────────────────────┘

The legacy response remains on the production serving path throughout shadowing. Sampling, timeouts, and error isolation keep the shadow request from affecting the application response. An offline full join aligns the production and shadow logs and explicitly classifies unmatched records as production-only or shadow-only; these coverage gaps are reported rather than silently discarded. Matched vectors are passed through the same type-aware comparison tool used in Phase 2.

Keeping the two logs independent is the preferred default because it preserves failure isolation and works even when the legacy service and Zipline Fetcher run in different processes or networks. When one Fetcher owns both calls, it may write the two vectors side-by-side in a single log envelope as an optimization. That removes the physical join, but it preserves the same correlation fields, one-sided outcome classification, and downstream comparison semantics.

Reusing the Phase 2 policies makes the two reports directly comparable. It also exposes issues that historical validation cannot reproduce, including live source lag, serialization differences, online-store freshness, request-time derivations, and behavior for newly observed keys.

Phase 3 is complete after the comparison policy passes for the agreed traffic sample and observation window, with no unacceptable latency or error-rate regression in the shadow path. Teams can then move traffic gradually, retain the shadow comparison during rollout, and roll back without changing feature definitions if a production issue appears.

What Zipline Enterprise delivers

A migration engagement typically produces:

  • A source inventory and mapping from legacy concepts to Zipline constructs
  • Reviewable Zipline definitions with documented translation assumptions
  • A Phase 1 schema-contract report
  • Phase 2 historical comparison reports and agreed acceptance policies
  • Phase 3 shadow comparison reports and cutover recommendations
  • A migration scorecard showing the owner and status of every feature service

The result is an evidence-based migration path: schema compatibility before computation, value compatibility before live traffic, and production compatibility before cutover.

Edit this page