migrate2vespa
Plan an Elasticsearch or OpenSearch migration to Vespa from the artifacts you already have.
Give it a mapping, and optionally settings, sample documents and representative queries.
migrate2vespa turns that evidence into a reviewable migration manifest and, where the plan is safe, a starter Vespa application package.
validation:
analysis: COMPLETE
summary:
fields:
direct: 9
adapt: 3
# output from the real quickstart fixture
A mapping is not a migration plan.
A field type tells you how Elasticsearch stores a field. It does not tell you everything the application expects from it.
A keyword field might be used for exact filtering, sorting, aggregations, or simply returned with the document. A field declared as scalar may arrive as an array. A query builder may contain matching rules, ranking choices and product logic that are not obvious from the mapping.
The goal is not to reproduce Elasticsearch syntax in Vespa. It is to make the required behavior explicit before choosing the Vespa representation.
Evidence in. Migration decisions out.
The migration manifest is the main artifact. It keeps the source evidence, required capabilities, target plan and unresolved work in one inspectable record.
Source artifacts
mapping.json *
settings.json
documents.jsonl
queries/
Planner
migrate2vespa
account · infer · classify
Reviewable output
migration-manifest.yaml
when safe
vespa-app/
Every supplied field, document and query is accounted for rather than silently ignored.
A migration needs decisions, not just target syntax.
The requirement is clear and has a straightforward Vespa representation.
The requirement is clear, but the representation or data shape needs to change.
The available evidence is not enough to choose safely. An engineer needs to inspect it.
The behavior is understood, but carrying the source architecture into Vespa would be the wrong approach.
Unknown constructs are recorded, not guessed.
The source type is only one piece of evidence.
The important step is turning source evidence into required behavior before choosing the Vespa field plan.
Source
tags: keyword
Observed
arrays in sample documents
Query usage
exact filtering + aggregation
Required
Decision
ADAPT
Vespa plan
array<string>
Configure the field for the exact matching, filtering and grouping operations the evidence requires.
Elasticsearch and OpenSearch today.
The website summarizes the current release. The repository remains the source of truth as the project evolves.
A starter package is not a completed migration.
migrate2vespa handles assessment and safe starter-package generation. It does not claim to prove that a production migration is complete.
- No connection to your Elasticsearch or OpenSearch cluster
- No automatic translation of representative queries into Vespa YQL
- No claim of relevance parity or production readiness
Deploy the generated application, feed data, run queries, compare behavior, benchmark the target system and make the remaining engineering decisions explicitly.
Try it on an exported mapping.
Only mapping.json is required. Settings, representative documents and queries give the planner more evidence.
$ python3 -m pip install migrate2vespa
$ migrate2vespa ./es-app
es-app/
├── mapping.json *
├── settings.json
├── documents.jsonl
└── queries/
out/
├── migration-manifest.yaml
└── vespa-app/
The engineering judgment stayed hard. The first pass became repetitive.
Searchplex works on production search migrations to Vespa.
Across migration work, the same questions kept recurring: What are fields actually used for? What do documents reveal that the mapping does not? Which query constructs represent required behavior, and which need review or redesign?
migrate2vespa packages that repeatable first pass into an open-source tool. It does not replace migration engineering. It gives engineers a more explicit, reviewable place to start.
Searchplex is an official Vespa.ai partner.
A distributed team of search and retrieval practitioners working on production systems.
09 SEP 2026
LONDON, UK
From Elasticsearch and OpenSearch to Vespa: Patterns from Shipped Migrations
migrate2vespa grew out of recurring patterns in production migrations: recovering requirements from source implementations, separating application logic from engine syntax, making decisions explicit and validating the target independently.
View event detailsTry migrate2vespa
The project is open source under Apache 2.0. Issues, feedback and contributions are welcome.
Planning a production Elasticsearch or OpenSearch migration to Vespa?
See Searchplex's migration work →