langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-21 11:55:23 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[PR #3203] [MERGED] fix: correct similarity score description for Supabase vector store #3271

New Issue
Closed
opened 2026-06-05 18:21:38 -04:00 by yindo · 0 comments
yindo commented 2026-06-05 18:21:38 -04:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/langchain-ai/docs/pull/3203
Author: @kvpratama
Created: 3/18/2026
Status: ✅ Merged
Merged: 3/18/2026
Merged by: @mdrxy

Base: main ← Head: patch-1

📝 Commits (1)

  • 8ff99ef fix: correct similarity score description for Supabase vector store

📊 Changes

1 file changed (+1 additions, -1 deletions)

View changed files

📝 src/oss/python/integrations/vectorstores/supabase.mdx (+1 -1)

📄 Description

Overview

Fix incorrect score description in the Supabase vector store documentation. The doc states the returned score is cosine distance (lower = better), but it is actually cosine similarity (higher = better).

Type of change

Type: Fix typo/bug/link/formatting

Related issues/PRs

  • GitHub issue: N/A
  • Feature PR: N/A

Checklist

  • I have read the contributing guidelines, including the language policy
  • I have tested my changes locally using docs dev
  • All code examples have been tested and work correctly
  • I have used root relative paths for internal links
  • I have updated navigation in src/docs.json if needed

Additional notes

The documentation under Similarity search with score states:

"The returned distance score is cosine distance. Therefore, a lower score is better."

This is incorrect. The returned score is cosine similarity, not cosine distance. Therefore, a higher score is better.

Evidence:

1. The SQL function computes cosine similarity, not cosine distance

The match_documents function defined in the docs computes:

1 - (documents.embedding <=> query_embedding) as similarity

The <=> operator in pgvector returns cosine distance. Subtracting it from 1 converts it to cosine similarity, where:

  • 1.0 = identical vectors (best match)
  • 0.0 = orthogonal vectors (no similarity)
  • -1.0 = opposite vectors (worst match)

The column is even explicitly named similarity, not distance.

2. The Python source code filters with >=

In langchain_community/vectorstores/supabase.py, the similarity_search_by_vector_with_relevance_scores method (which is called internally by similarity_search_with_relevance_scores) filters results using:

if similarity >= score_threshold

This confirms higher scores are better — if it were cosine distance, the filter would use <=.

3. The example output is consistent with cosine similarity

The example output in the same doc shows a top result score of 0.802509746274066, which is consistent with cosine similarity (closer to 1.0 = better match), not cosine distance.

Change:

Before:

The returned distance score is cosine distance. Therefore, a lower score is better.

After:

The returned score is cosine similarity. Therefore, a higher score is better.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/langchain-ai/docs/pull/3203 **Author:** [@kvpratama](https://github.com/kvpratama) **Created:** 3/18/2026 **Status:** ✅ Merged **Merged:** 3/18/2026 **Merged by:** [@mdrxy](https://github.com/mdrxy) **Base:** `main` ← **Head:** `patch-1` --- ### 📝 Commits (1) - [`8ff99ef`](https://github.com/langchain-ai/docs/commit/8ff99ef1322b90c8a49089de37f95db84f6e804a) fix: correct similarity score description for Supabase vector store ### 📊 Changes **1 file changed** (+1 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `src/oss/python/integrations/vectorstores/supabase.mdx` (+1 -1) </details> ### 📄 Description ## Overview Fix incorrect score description in the Supabase vector store documentation. The doc states the returned score is cosine distance (lower = better), but it is actually cosine similarity (higher = better). ## Type of change **Type:** Fix typo/bug/link/formatting ## Related issues/PRs - GitHub issue: N/A - Feature PR: N/A ## Checklist - [x] I have read the [contributing guidelines](README.md), including the [language policy](https://docs.langchain.com/oss/python/contributing/overview#language-policy) - [ ] I have tested my changes locally using `docs dev` - [ ] All code examples have been tested and work correctly - [x] I have used **root relative** paths for internal links - [ ] I have updated navigation in `src/docs.json` if needed ## Additional notes The documentation under **Similarity search with score** states: > "The returned distance score is cosine distance. Therefore, a lower score is better." This is incorrect. The returned score is **cosine similarity**, not cosine distance. Therefore, a **higher score is better**. **Evidence:** **1. The SQL function computes cosine similarity, not cosine distance** The `match_documents` function defined in the docs computes: ```sql 1 - (documents.embedding <=> query_embedding) as similarity ``` The `<=>` operator in pgvector returns cosine **distance**. Subtracting it from 1 converts it to cosine **similarity**, where: - `1.0` = identical vectors (best match) - `0.0` = orthogonal vectors (no similarity) - `-1.0` = opposite vectors (worst match) The column is even explicitly named `similarity`, not `distance`. **2. The Python source code filters with `>=`** In `langchain_community/vectorstores/supabase.py`, the `similarity_search_by_vector_with_relevance_scores` method (which is called internally by `similarity_search_with_relevance_scores`) filters results using: ```python if similarity >= score_threshold ``` This confirms higher scores are better — if it were cosine distance, the filter would use `<=`. **3. The example output is consistent with cosine similarity** The example output in the same doc shows a top result score of `0.802509746274066`, which is consistent with cosine similarity (closer to 1.0 = better match), not cosine distance. **Change:** Before: > The returned distance score is cosine distance. Therefore, a lower score is better. After: > The returned score is cosine similarity. Therefore, a higher score is better. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
yindo added the pull-request label 2026-06-05 18:21:38 -04:00
yindo closed this issue 2026-06-05 18:21:38 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#3271
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?