Migrating from Pinecone to Qdrant: the migration tool, score scales and cutover
How to migrate Pinecone to Qdrant with the official migration tool: what it copies, what it skips, how namespaces and score thresholds map, and a top-k parity check before cutover. Tested on Qdrant 1.20.0.
To migrate Pinecone to Qdrant, create the target collection yourself with its sparse vector and tenant index, then run Qdrant's qdrant-migration pinecone command once per namespace. It copies vectors, sparse values and metadata, and keeps each Pinecone ID in a __id__ payload field. Before any traffic moves, check top-k overlap against Pinecone on real queries. Cosine and dot product thresholds carry over unchanged. Euclidean thresholds do not: Pinecone returns squared distance and Qdrant returns the distance itself.
What we ran: everything on the Qdrant side, on 31 October 2026, with qdrant/qdrant:v1.20.0 (the current release) and the migration image registry.cloud.qdrant.io/library/qdrant-migration at v0.6.15 (build 90405ce), both in Docker. We had no Pinecone account. So every Pinecone statement below is docs-verified, not run, checked against docs.pinecone.io on the same day. The Pinecone side of the parity check is NumPy exact search over the same vectors, using the score formulas Pinecone documents. The corpus is illustrative: 20,000 random clustered 128-dimensional vectors split across two namespaces. It shows behaviour. It is not a benchmark.
How to migrate Pinecone to Qdrant, in order
Our recommendation is to move the data as it is, prove parity, cut over, and only then change anything about retrieval. Quantization and hybrid fusion are both worth revisiting on Qdrant, but if you change them during the move, a parity gap could be the migration or the new config, and you cannot tell which.
flowchart TD
A["Inventory Pinecone:<br/>indexes, namespaces, metric,<br/>sparse values, score thresholds"] --> B["Pre-create the Qdrant collection:<br/>vectors, sparse_vector,<br/>payload indexes"]
B --> C["Run qdrant-migration pinecone<br/>once per namespace"]
C --> D["Stamp tenant_id,<br/>check point counts"]
D --> E["Convert score thresholds"]
E --> F["Shadow reads:<br/>top-k overlap per query"]
F --> G{"Overlap acceptable?"}
G -- no --> H["Check vectors, filters,<br/>hnsw_ef, IDs"]
H --> F
G -- yes --> I["Shift reads by percentage,<br/>keep dual writes"]
I --> J["Retire Pinecone after<br/>the rollback window"]
J --> K["Then tune: quantization,<br/>hybrid fusion"]Pinecone to Qdrant concept map
| Pinecone | Qdrant | Notes |
|---|---|---|
| Index (serverless) | Collection | The tool's list path only works on serverless indexes |
| Namespace | Tenant value in one collection, or a separate collection | The tool reads one namespace per run |
| Record ID (any string) | Point ID (UUID or unsigned integer) | The tool derives a UUIDv5 and stores the original in __id__ |
Dense values | Unnamed default vector | Written under the vector name "" |
sparse_values | Named sparse vector sparse_vector | Name set by --qdrant.sparse-vector |
| Metadata (flat JSON) | Payload | Pinecone stores integers as 64-bit floats, so they land as 2024.0 |
| Metadata index | Payload index | Not created by the tool; create them yourself |
cosine / dotproduct / euclidean | Cosine / Dot / Euclid | Euclidean scores differ, see below |
Client-side alpha hybrid | Query API prefetch with RRF or DBSF fusion | Rebuild the query; the data carries over |
What the Pinecone to Qdrant migration tool copies
Here is the real help output of the pinecone subcommand, trimmed to the flags that matter:
$ docker run --rm registry.cloud.qdrant.io/library/qdrant-migration pinecone --help
Usage: qdrant-migration pinecone --pinecone.index-name=STRING --pinecone.index-host=STRING --pinecone.api-key=STRING --qdrant.collection=STRING [flags]
Migrate data from a Pinecone database to Qdrant.
--pinecone.index-name=STRING Pinecone index name
--pinecone.index-host=STRING Pinecone index host URL
--pinecone.api-key=STRING Pinecone API key for authentication
--pinecone.namespace=STRING Namespace of the partition to migrate
--pinecone.service-host=STRING Pinecone service host URL. Optional.
--qdrant.collection=STRING Collection name
--qdrant.url="http://localhost:6334" Qdrant gRPC URL
--qdrant.api-key=STRING API key for authentication
-b, --migration.batch-size=50 Batch size
--migration.restart Restart the migration and do not continue from last offset
-c, --migration.create-collection Create the collection if it does not exist
--migration.offsets-collection="_migration_offsets"
--migration.batch-delay=0 Delay between batches in milliseconds
--qdrant.id-field="__id__" Field storing Pinecone IDs in Qdrant.
--qdrant.sparse-vector="sparse_vector" Name of the sparse vector in Qdrant
A run for one namespace looks like this. Note the gRPC port 6334:
docker run --net=host --rm -it registry.cloud.qdrant.io/library/qdrant-migration pinecone \
--pinecone.index-host 'https://your-index-host.pinecone.io' \
--pinecone.index-name 'your-index' \
--pinecone.api-key "$PINECONE_API_KEY" \
--pinecone.namespace 'acme' \
--qdrant.url 'https://your-cluster.cloud.qdrant.io:6334' \
--qdrant.api-key "$QDRANT_API_KEY" \
--qdrant.collection 'docs'
We read the tool's source at the image's commit (cmd/migrate_from_pinecone.go) to see exactly what happens. It pages through IDs with Pinecone's list and fetches each page, then upserts the batch with wait=true. Dense values go to the unnamed vector and sparse values to sparse_vector. Metadata becomes payload, and the original ID goes into __id__. After each batch it stores the pagination token in _migration_offsets, so a rerun resumes. That store is keyed by index host alone, with no namespace in the key. If a run for one namespace dies, finish it (or pass --migration.restart) before starting the next namespace. It deletes the offsets collection when the run succeeds.
Pinecone's own docs explain the serverless restriction: "The list endpoint is supported only for serverless indexes" (List IDs). Qdrant's Pinecone migration page says pod-based indexes "may require additional steps" and does not list them.
The tool leaves these to you:
- Payload indexes. No keyword, integer or tenant indexes are created. Filters still work without them, but filtered HNSW search needs them.
- Collection tuning. With
-c, the collection gets the dimension and distance and nothing else, so HNSW and quantization stay at their defaults. - Sparse config on a dense index. With
-con a dense index, the tool creates no sparse vector. Records that also carrysparse_valuesthen fail. - Document-schema indexes. Pinecone's Documents API indexes (API version
2026-07) are read differently from vector indexes. The v0.6.15 source only handles the Vectors API. We could not test this, so check it before you plan around the tool.
This is what a sparse upsert does against the collection that -c creates for a dense cosine index:
{"status":{"error":"Wrong input: Not existing vector name error: sparse_vector"},"time":0.000891875}
So pre-create the collection. The tool sees that it exists and skips creation. The default vector must stay unnamed, because that is where the tool writes:
PUT /collections/docs
{
"vectors": { "size": 128, "distance": "Cosine" },
"sparse_vectors": { "sparse_vector": {} },
"hnsw_config": { "payload_m": 16, "m": 0 }
}
Pinecone namespace to Qdrant tenants
Point IDs do not include the namespace. The tool computes uuid.NewSHA1(uuid.NameSpaceURL, id), which is Python's uuid.uuid5(uuid.NAMESPACE_URL, id). ID doc1 maps to 75d4622e-94ed-5766-af3f-741bfc37fe71 in every namespace. Qdrant's page says to migrate namespaces with overlapping IDs into separate collections. If your namespaces are tenants, that gives you a collection per tenant, which our Qdrant multitenancy post argues against.
When IDs are unique across namespaces (Pinecone's docs suggest structured IDs such as doc1#chunk1), use one collection. Create the tenant index first, run each namespace, and stamp the new points before the next run:
PUT /collections/docs/index
{ "field_name": "tenant_id", "field_schema": { "type": "keyword", "is_tenant": true } }
POST /collections/docs/points/payload?wait=true
{
"payload": { "tenant_id": "acme" },
"filter": { "must": [ { "is_empty": { "key": "tenant_id" } } ] }
}
After both namespaces, the collection reported this payload schema:
{
"tenant_id": { "data_type": "keyword", "params": { "type": "keyword", "is_tenant": true }, "points": 20000 },
"__id__": { "data_type": "keyword", "points": 20000 },
"year": { "data_type": "integer", "points": 20000 }
}
The year values arrived as doubles (2024.0), because Pinecone stores integers as 64-bit floats and the tool writes them as doubles. An integer index still indexed all 20,000 points, and both match and range filters on 2024 matched. Index __id__ as a keyword: your application still knows records by their Pinecone IDs, and it is the join key for the parity check. If IDs do overlap, run your own copy script that hashes namespace + id instead.
Qdrant cosine score range vs Pinecone, and score thresholds
A common claim is that Pinecone rescales cosine to [0, 1] while Qdrant returns [-1, 1]. Pinecone's current index configuration docs say otherwise. For cosine, "the scores are normalized to [-1,1] range", which is plain cosine similarity, the same quantity Qdrant returns. Dot product is the raw dot product on both. Euclidean is where they differ. Pinecone's docs say a query "returns a similarity score equal to the squared Euclidean distance". Qdrant's Euclid returns the distance itself, and its search docs say score_threshold excludes higher Euclidean scores.
We loaded 200 random 16-dimensional vectors into one collection per metric. Then we compared Qdrant's exact-search scores with each metric computed in NumPy the way Pinecone documents it:
| Metric | Point | Pinecone formula (NumPy) | Qdrant raw score |
|---|---|---|---|
| cosine | 140 | 0.549311 | 0.549311 |
| dotproduct | 140 | 10.185995 | 10.185995 |
| euclidean | 140 | 16.725756 | 4.089714 |
| euclidean | 77 | 17.129549 | 4.138786 |
Qdrant's cosine scores in that collection ran from -0.549311 to 0.691605, so negative scores do come back. The conversion fits in a few lines. Our run asserted it on every hit:
import math
def to_qdrant_threshold(metric: str, pinecone_threshold: float) -> float:
"""Map a score threshold tuned on Pinecone to Qdrant's scale."""
if metric in ("cosine", "dotproduct"):
return pinecone_threshold # same quantity on both sides
if metric == "euclidean":
return math.sqrt(pinecone_threshold) # Pinecone: d^2, Qdrant: d
raise ValueError(metric)
def from_unit_interval(s: float) -> float:
"""If your own code stored thresholds as (1 + cos) / 2, recover cosine."""
return 2 * s - 1
assert abs(to_qdrant_threshold("euclidean", 16.725756) - 4.089714) < 1e-5
With Euclid, "score_threshold": 4.15 returned points 140 and 77 (4.0897 and 4.1388). The same threshold applied to Pinecone's squared scale would be 17.2225. If a wrapper library or your own code rescaled cosine to [0, 1], that rescale lives in your code, and from_unit_interval undoes it.
One more difference shows up in verification scripts. For Cosine, Qdrant normalizes each vector on upload. A stored vector came back from with_vector with norm 1.0, while the original had norm 14.0259. Compare vectors by direction, or the check will fail every record.
Re-adding hybrid search
The sparse values migrate, but Pinecone's hybrid query does not. Pinecone's hybrid search guide describes a single dotproduct index holding both vectors, where you scale the query vectors client-side with an alpha weight. Qdrant runs each vector in a prefetch and fuses the results with RRF or DBSF. Our Qdrant hybrid search post covers that query and when each fusion wins.
Two practical points. If Pinecone's hosted sparse model produced your sparse vectors, you still need that model to encode queries after the move. And alpha-weighted scores do not map onto RRF ranks, so treat hybrid as a relevance change and evaluate it after cutover. Until then, query the dense vector alone on both sides for parity.
Dual-run parity: top-k overlap
sequenceDiagram
participant App
participant Pinecone as Pinecone primary
participant Qdrant as Qdrant shadow
participant Log as Parity log
App->>Pinecone: query, top_k=10
Pinecone-->>App: results served to the user
App->>Qdrant: same vector, filter, limit=10
Qdrant-->>App: points with __id__
App->>Log: overlap@10, score deltas, latencyFor each query, take Pinecone's top 10 IDs and Qdrant's top 10 __id__ values and record the size of the intersection divided by 10. On our corpus, the "Pinecone" side was exact cosine top-10 in NumPy. The Qdrant side was the filtered query on the migrated collection, with HNSW forced by a low full_scan_threshold (100 queries, 50 per tenant):
| Qdrant search setting | Mean overlap@10 | Worst query | Queries below 0.9 |
|---|---|---|---|
| Default HNSW | 1.000 | 1.0 | 0 |
"exact": true | 1.000 | 1.0 | 0 |
"hnsw_ef": 10 | 0.970 | 0.7 | 4 |
The exact-search scores matched NumPy to within 2.43e-07. Our clustered toy data is easy for HNSW, so do not expect 1.000 on real embeddings. Pinecone's side is also approximate, so an overlap below 1.0 on production queries can come from either engine. The hnsw_ef: 10 row shows why to keep the per-query log. The mean barely moved, while four queries dropped to 0.7 or 0.8. Sort by overlap and read the worst queries. Wrong filters and missing tenant stamps show up there first. If you have labelled queries, compute recall or nDCG on both engines too, since overlap only measures agreement.
Cutover and rollback
Point the application at a Qdrant alias (POST /collections/aliases with create_alias). A later reindex into a new collection is then an alias swap, the same pattern as in our zero-downtime Elasticsearch deployments post. Keep writing to Pinecone until the rollback window closes, so falling back means flipping a config flag.
| Step | Check before moving on |
|---|---|
| Inventory | Metric, dimension, namespaces, ID overlap across namespaces, sparse values present, every score threshold in code |
| Pre-create collection | Unnamed dense vector, sparse_vector if needed, tenant_id with is_tenant, __id__ keyword index |
| Migrate | One namespace per run; finish or --migration.restart an interrupted run before the next namespace |
| Counts | Qdrant count per tenant_id equals Pinecone's record count per namespace |
| Thresholds | Euclidean: sqrt of the Pinecone value; cosine and dot unchanged |
| Dual writes | Every upsert and delete goes to both engines, keyed by the original ID |
| Shadow reads | Overlap@10 logged per query; worst queries reviewed |
| Shift reads | Percentage flag in the application, raised in steps |
| Rollback | Flag back to Pinecone; it stays current while dual writes run |
| Retire | Stop dual writes, then tune quantization and hybrid on Qdrant |
Once Pinecone is retired, the first tuning step is usually quantization. Our Qdrant TurboQuant guide compares the options, and the vector sizing calculator estimates memory for each. If you are still choosing a destination, see turbopuffer vs Pinecone and Elasticsearch vs Qdrant.
Where we can help
We run Pinecone to Qdrant migrations parity-first: we pre-create the collection, migrate per namespace, convert thresholds and log overlap on your query traffic before any reads move. See our Qdrant consulting service.
Abhilash B is an advisor at Query Quotient and an information retrieval and AI expert who holds patents in the field. Abhilash brings that retrieval depth to the search, RAG and agent systems Query Quotient builds for clients.
