Vector Store Integration#

Dify's vector store layer is built around the BaseVector abstract class. Every backend implements a common contract: search_by_vector, search_by_full_text, create, add_texts, delete_by_ids, and delete_by_metadata_field. Backends are registered as plugins under api/providers/vdb/ and resolved at dataset-open time. As of mid-2026, 38+ backends are registered (pgvector, Milvus, Qdrant, Weaviate, Chroma, OpenSearch, Elasticsearch, MatrixOne, Tencent VectorDB, TiDB, OceanBase, and more). 1

Related KB articles: Retrieval Filtering and Scoring (pipeline above this layer) · Hybrid Search · Milvus Integration · Weaviate Vector Store · Summary Index

search_by_vector Contract#

All backends accept a consistent set of kwargs 1:

Returned Document objects carry metadata["score"] so the layer above can apply threshold filters without recomputing scores.

Note for hybrid search: RetrievalService forces score_threshold=0.0 at vector retrieval time for hybrid queries, deferring threshold enforcement to post-fusion reranking. See Retrieval Filtering and Scoring. 2

Score Computation by Backend#

Backends fall into two camps: distance-to-score conversion and native score. Because semantics differ, score_threshold values are not portable across backends. 1

Distance-to-Score (score = f(distance))#

MatrixOne uses different formulas for its two search paths — 1/(1+distance) for ANN vector search and 1−distance for full-text search — because the two paths return distances with different ranges. 1

Native Score (no conversion)#

Score Threshold Filtering#

Post-query (most backends)#

pgvector, Weaviate, Chroma, MatrixOne, OpenSearch, and Elasticsearch all fetch top_k results first, then filter in Python: if score >= score_threshold. 1

In-query + post-query (Qdrant only)#

Qdrant passes score_threshold directly to _client.search(score_threshold=...), pruning at the index level. A redundant Python check is also applied. As an edge case, score_threshold >= 1 short-circuits immediately to an empty list without a DB round-trip. 1

document_ids_filter Translation#

All backends translate document_ids_filter to backend-native filter syntax before the query — never post-hoc. 1

Tencent VectorDB bug (fixed 2025-08-07): In full-text search mode, the document_ids_filter was previously silently dropped. The fix builds Filter.In("metadata.document_id", document_ids_filter) and passes it into hybrid_search(filter=...). 4

MatrixOne-Specific Notes#

MatrixOne (matrixone_vector.py) was added 2026-07-29:

• Backed by mo_vector.MoVectorClient over a MySQL-protocol connection (mysql+pymysql://). Default metric is l2, configurable via MATRIXONE_METRIC env var.
• Client initialization is lazy and guarded by a Redis lock (vector_indexing_lock_{collection_name}), with a 1-hour cache to avoid recreating the full-text index on every call.
• See test_matrixone_vector.py for unit coverage.

Metadata Type Constraints and the Tencent VectorDB Deadlock#

Tencent VectorDB rejects boolean values in JSON metadata. Summary index vectors include is_summary: True, which caused upserts to fail. The failure path then opened a second DB session to record the error while the caller-owned session still held a row lock on the summary record — resulting in a deadlock that occupied a worker slot indefinitely. 5

Fix (PR #41916, open as of 2026-09-07):

1. In tencent_vector.py add_texts(), convert metadata["is_summary"] = True → 1 (integer) before upsert, leaving other backends unchanged.
2. In summary_index_service.py vectorize_summary(), when a caller-owned session is provided, write the error status back on that session and re-raise — do not open a new error_session that would compete for the same row lock. Standalone callers (no provided session) still get a new error session as before.

This pattern (session ownership discipline in error paths) applies to any backend where vectorization can fail after the caller has already flushed a row.

Key Files#