migrate2vespa: plan an Elasticsearch or OpenSearch migration to Vespa
migrate2vespa is an open-source Python CLI developed by Searchplex for planning Elasticsearch and OpenSearch migrations to Vespa.ai. Give it a mapping, and it creates a reviewable migration manifest and generates a starter Vespa application for the parts it can convert safely.
What it needs from you
A mapping is enough to start. Settings, sample documents, and representative queries add evidence: analyzers and normalizers, value shapes, and which fields are searched, filtered, sorted, aggregated, or used for nearest-neighbor search. Queries inform the manifest; the CLI does not translate them to YQL.
es-app/ ├── mapping.jsonrequired ├── settings.jsonoptional ├── documents.jsonlrecommended └── queries/recommended
The tool works from these local files only. It does not connect to your Elasticsearch or OpenSearch cluster.
For a worked example, read From an Elasticsearch Mapping to a Running Vespa Application.
$ python3 -m pip install migrate2vespa $ migrate2vespa ./es-app
Two stages, in order
The tool writes the manifest first and generates from the plan recorded there. Run both stages with one command, or use --analyze-only to review the manifest before generating the Vespa application.
Build the migration manifest
migrate2vespa records the source field, observed usage, required behavior, proposed Vespa field, and anything that still needs attention.
Every supplied field, query, and document line is accounted for — so unsupported or unfamiliar constructs are recorded, not silently dropped.
Each field or query finding receives one of four decisions:
DIRECT
Maps cleanly to a Vespa field.
ADAPT
Needs a known conversion.
REVIEW
Needs a person to confirm the plan.
REDESIGN
Needs a different design in Vespa.
# quickstart: PARTIAL (11 of 12 fields generated)
fields:
sku:
source: keyword
decision: DIRECT
price:
source: double
decision: DIRECT
title.raw:
source: multi-field on title
decision: ADAPT
embedding:
source: dense_vector, dims: 8
decision: ADAPT
Generate what's safe
migrate2vespa uses the manifest to build the fields it can convert safely. Anything left out remains listed in the manifest.
READYall planned fields generatedPARTIALsafe omissions recordedBLOCKEDno application producedGenerated packages include the Vespa schema and service configuration. When sample documents are supplied,feed/documents.jsonl contains converted samples; otherwise, that file is empty.
Deploy the generated application
When generation succeeds, migrate2vespa prints the Vespa CLI command for the package it just built.
# printed at the end of a successful run $ vespa deploy --wait 600 ./es-app/out/vespa-app
migrate2vespa does not deploy or feed the application. Validate the generated package with representative data and queries before using it in production.
Local and deterministic, by design
Nothing leaves your machine
Same inputs, same plan
No hidden guesses
The talk Patterns from Shipped Migrations explains why the repeatable inventory and translation work is worth automating, while Vespa-native schema, ranking, and production design still require engineering judgment.
What it converts today
The current release supports a focused set of common Elasticsearch and OpenSearch constructs.
Fields
Query evidence
Text analysis
Compatibility is based on the constructs listed above, not a blanket Elasticsearch or OpenSearch version claim. Unknown constructs remain visible in the manifest.
The rule set is intended to expand. Source parsing is also separate from Vespa package generation, so support for other source engines can be added without replacing the generator. Contributions are welcome. Follow the project on GitHub for new releases and expanded migration coverage.
migrate2vespa — common questions
Answers about query evidence, CI use, AI-assisted review, and what remains before production deployment.
Need help taking the plan to production?
migrate2vespa produces a reviewable starter. Workload validation, ranking design, and cutover still need engineering judgment — Searchplex can help with that.