Back to blog
Architecture

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.

Abhilash B10 min read
#qdrant#pinecone#migration#vector search#architecture

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

PineconeQdrantNotes
Index (serverless)CollectionThe tool's list path only works on serverless indexes
NamespaceTenant value in one collection, or a separate collectionThe 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 valuesUnnamed default vectorWritten under the vector name ""
sparse_valuesNamed sparse vector sparse_vectorName set by --qdrant.sparse-vector
Metadata (flat JSON)PayloadPinecone stores integers as 64-bit floats, so they land as 2024.0
Metadata indexPayload indexNot created by the tool; create them yourself
cosine / dotproduct / euclideanCosine / Dot / EuclidEuclidean scores differ, see below
Client-side alpha hybridQuery API prefetch with RRF or DBSF fusionRebuild 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 -c on a dense index, the tool creates no sparse vector. Records that also carry sparse_values then 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:

MetricPointPinecone formula (NumPy)Qdrant raw score
cosine1400.5493110.549311
dotproduct14010.18599510.185995
euclidean14016.7257564.089714
euclidean7717.1295494.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, latency

For 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 settingMean overlap@10Worst queryQueries below 0.9
Default HNSW1.0001.00
"exact": true1.0001.00
"hnsw_ef": 100.9700.74

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.

StepCheck before moving on
InventoryMetric, dimension, namespaces, ID overlap across namespaces, sparse values present, every score threshold in code
Pre-create collectionUnnamed dense vector, sparse_vector if needed, tenant_id with is_tenant, __id__ keyword index
MigrateOne namespace per run; finish or --migration.restart an interrupted run before the next namespace
CountsQdrant count per tenant_id equals Pinecone's record count per namespace
ThresholdsEuclidean: sqrt of the Pinecone value; cosine and dot unchanged
Dual writesEvery upsert and delete goes to both engines, keyed by the original ID
Shadow readsOverlap@10 logged per query; worst queries reviewed
Shift readsPercentage flag in the application, raised in steps
RollbackFlag back to Pinecone; it stays current while dual writes run
RetireStop 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.

Advisor, Query Quotient

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.

Keep reading

Building something similar?

Tell us what you are working on. In a free 30-minute call we will give you an honest view of the approach, the effort and how to measure success.