Skip to content

fix(vector-store): rank Euclidean results by distance in Qdrant and Pinecone - #2116

Merged
pkupt merged 3 commits into
semantica-agi:mainfrom
kartsan03:fix/distance-metric-score-direction
Oct 26, 2026
Merged

pkupt merged 3 commits into
semantica-agi:mainfrom
kartsan03:fix/distance-metric-score-direction

Conversation

@kartsan03

Copy link
Copy Markdown
Contributor

Description

For Euclidean, Qdrant and Pinecone return a distance: lower means closer. Both stores passed it through (x / (1 + |x|) + 1) / 2, the squash added for unbounded Dot scores, and that grows with x. So the exact match got the lowest score and the farthest vector the highest, against the "higher is better" contract in vector_store.py.

Both stores now read the metric of the collection or index and turn a distance d into 1 / (1 + d), as sqlite_vec_store.py does. With the example from #2115, the scores go from [0.5, 0.75, 0.875] to [1.0, 0.5, 0.25]. Cosine and Dot scores don't change.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Performance improvement
  • Code refactoring

Related Issues

Fixes #2115

Changes Made

  • semantica/vector_store/qdrant_store.py: QdrantCollection.search_points() reads the collection's vector config once (get_collection), so it also works for a collection it attached to or reopened from disk. For named vectors it uses the config of the vector in using. Euclid and Manhattan distances become 1 / (1 + d).
  • semantica/vector_store/pinecone_store.py: PineconeIndex takes the index metric, which PineconeStore reads with describe_index when it creates or attaches an index. euclidean scores become 1 / (1 + d). create_index(metric="euclidean") now sends "euclidean" instead of "euclidean_distance", which isn't one of Pinecone's metrics (cosine, euclidean, dotproduct), so a Euclidean index couldn't be created at all.
  • When the metric can't be read, scores are computed as before.
  • Tests: tests/vector_store/test_qdrant_score_direction.py runs real Qdrant local mode, for a created and a reopened collection, a collection created outside Semantica (Euclid and Manhattan, plain and named vectors), and pins the current Cosine and Dot scores. tests/vector_store/test_pinecone_score_direction.py does the same with a fake Pinecone client, plus the metric name sent on create.

Testing

  • Tested locally
  • Added tests for new functionality
  • Package builds successfully (python -m build)

The Euclidean, Manhattan and metric-name cases fail on main and pass with this change. The Cosine and Dot cases pass on both. pytest tests/vector_store passes (without test_performance_benchmarks.py, which needs psutil). black, isort and flake8 at the pre-commit versions are clean on the changed lines and the new tests. I haven't run it against a live Pinecone index.

Documentation

  • Updated relevant documentation
  • Added code examples if applicable
  • Updated API reference if adding new APIs
  • Updated cookbook if adding new examples
  • No documentation changes needed

Breaking Changes

Breaking Changes: No for Cosine and Dot. Euclidean and Manhattan scores change from the old increasing values to 1 / (1 + d), so a threshold someone tuned on the old scores needs a new value.

Checklist

  • My code follows the project's style guidelines
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • My changes generate no new warnings

…inecone

Qdrant and Pinecone return a distance for Euclidean (and Qdrant's
Manhattan): lower means closer. Both stores passed it through the
x/(1+|x|) squash meant for unbounded Dot scores, which grows with the
value, so the exact match got the lowest score and the farthest vector
the highest.

Read the collection or index metric and turn a distance d into
1 / (1 + d), as the SQLite store does. Cosine and Dot scores are
unchanged, and so is any search where the metric can't be read.

PineconeClient.create_index also sent metric "euclidean_distance",
which Pinecone doesn't accept; it now sends "euclidean".
@qodo-code-review

Copy link
Copy Markdown

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

@qodo-free-for-open-source-projects

Copy link
Copy Markdown

PR Summary by Qodo

Fix distance-based score direction in Qdrant and Pinecone

🐞 Bug fix 🧪 Tests 🕐 20-40 Minutes

Grey Divider

AI Description

• Convert Euclidean and Manhattan distances into higher-is-better similarity scores.
Diagram

graph TD
  Q["Qdrant search"] --> M{"Distance metric?"} -->|Yes| D["Invert distance"] --> R["Similarity scores"]
  P["Pinecone search"] --> M -->|No or unknown| L["Existing squash"] --> R
Loading
High-Level Assessment

Keep normalization metric-aware within each provider: Qdrant can select a metric per named vector, while Pinecone describes it per index. A shared normalizer would add abstraction without removing that provider-specific discovery. Reviewers should note that existing distance-score thresholds may need retuning.

Files changed (4) +226 / -22

Bug fix (2) +51 / -22
pinecone_store.pyNormalize Euclidean scores using the index metric +32/-14

Normalize Euclidean scores using the index metric

• Sends Pinecone's accepted 'euclidean' metric on index creation and reads the metric when creating or attaching an index. Euclidean distances become inverse-distance similarity scores; other or unavailable metrics retain the previous normalization.

semantica/vector_store/pinecone_store.py

qdrant_store.pyNormalize Qdrant distance scores using collection configuration +19/-8

Normalize Qdrant distance scores using collection configuration

• Caches the collection's vector configuration on first search and selects the configured named vector when requested. Euclid and Manhattan scores use inverse-distance normalization, while other or unavailable metrics retain the previous behavior.

semantica/vector_store/qdrant_store.py

Tests (2) +175 / -0
test_pinecone_score_direction.pyCover Pinecone metric discovery and score direction +82/-0

Cover Pinecone metric discovery and score direction

• Fake-client tests cover created and attached indexes, dictionary and object index descriptions, Euclidean ranking, unchanged Cosine and Dot scores, and the metric sent on creation. They also verify fallback behavior when the metric is unavailable.

tests/vector_store/test_pinecone_score_direction.py

test_qdrant_score_direction.pyCover Qdrant score direction with local collections +93/-0

Cover Qdrant score direction with local collections

• Local-backend tests cover created and reopened collections, externally created plain and named vectors, and Euclid and Manhattan distances. They pin existing Cosine and Dot scores and test fallback when collection metadata cannot be read.

tests/vector_store/test_qdrant_score_direction.py

@qodo-free-for-open-source-projects

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@pkupt pkupt left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

Ran #2115 against a real local Qdrant: main returns [0.5, 0.75, 0.875], this branch returns [1.0, 0.5, 0.25]. The inversion was real, and 1/(1+d) matches what the sqlite backend already does, so the contract holds across backends now.

Also confirmed the metric reaches scoring — PineconeStore.search_vectors goes through PineconeSearch to PineconeIndex.search_vectors, and Distance.EUCLID == "Euclid" is true for the enum, so the Qdrant branch isn't dead code.

Reverting both files to main takes 10 tests down. Separately, euclidean_distance -> euclidean fixes an index that could never have been created, worth one line in the description so it shows up in the changelog. Two more notes in the comment below, neither blocking.

@pkupt

pkupt commented Oct 26, 2026

Copy link
Copy Markdown
Collaborator

Two small things from my side, neither blocking:

self.metric == "euclidean" in search_vectors is an exact match. describe_index returns lowercase today, but a .lower() would keep this working if that ever changes shape.

Related: when the metric read fails we fall back to the old formula. On a euclidean index that flips the ranking back, and only the log line says so. Might be worth making that louder than a warning.

Also euclidean_distance -> euclidean in metric_map is a fix on its own. A line in the description would help whoever reads the changelog and wonders where the score change came from.

@pkupt
pkupt merged commit ba38aa2 into semantica-agi:main Oct 26, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Qdrant and Pinecone Euclidean searches give the farthest match the highest score

2 participants