pgvector-haystack 6.3.0__tar.gz → 6.3.1__tar.gz

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [integrations/pgvector-v6.3.0] - 2026-03-17
+
+### 🐛 Bug Fixes
+
+- PgVectorDocumentStore `_treat_meta_field` and comparison functions now return Composed - string escaping done by `psycopg` (#2964)
+
+
 ## [integrations/pgvector-v6.2.0] - 2026-03-02
 
 ### 🐛 Bug Fixes

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgvector-haystack
-Version: 6.3.0
+Version: 6.3.1
 Summary: An integration of pgvector (vector search extension for Postgres) with Haystack
 Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/pgvector/README.md
@@ -15,10 +15,11 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.10
-Requires-Dist: haystack-ai>=2.24.0
+Requires-Dist: haystack-ai>=2.28.0
 Requires-Dist: pgvector>=0.3.0
 Requires-Dist: psycopg[binary]
 Description-Content-Type: text/markdown

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/pyproject.toml

@@ -19,11 +19,12 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
 dependencies = [
-  "haystack-ai>=2.24.0",
+  "haystack-ai>=2.28.0",
   "pgvector>=0.3.0",
   "psycopg[binary]"
 ]
@@ -67,7 +68,8 @@ dependencies = [
 unit = 'pytest -m "not integration" {args:tests}'
 integration = 'pytest -m "integration" {args:tests}'
 all = 'pytest {args:tests}'
-cov-retry = 'pytest --cov=haystack_integrations --reruns 3 --reruns-delay 30 -x {args:tests}'
+unit-cov-retry = 'pytest --cov=haystack_integrations --reruns 3 --reruns-delay 30 -x -m "not integration" {args:tests}'
+integration-cov-append-retry = 'pytest --cov=haystack_integrations --cov-append --reruns 3 --reruns-delay 30 -x -m "integration" {args:tests}'
 
 types = "mypy -p haystack_integrations.document_stores.pgvector -p haystack_integrations.components.retrievers.pgvector {args}"
 
@@ -91,9 +93,17 @@ line-length = 120
 [tool.ruff.lint]
 select = [
   "A",
+  "ANN",
   "ARG",
   "B",
   "C",
+  "D102",   # Missing docstring in public method
+  "D103",   # Missing docstring in public function
+  "D205",   # 1 blank line required between summary line and description
+  "D209",   # Closing triple quotes go to new line
+  "D213",   # summary lines must be positioned on the second physical line of the docstring
+  "D417",   # Missing argument descriptions in the docstring
+  "D419",   # Docstring is empty
   "DTZ",
   "E",
   "EM",
@@ -119,6 +129,8 @@ select = [
 ignore = [
   # Allow non-abstract empty methods in abstract base classes
   "B027",
+  # Allow Any in type annotations at dynamic boundaries
+  "ANN401",
   # Allow boolean positional values in function calls, like `dict.get(... True)`
   "FBT003",
   # Ignore checks for possible passwords
@@ -145,14 +157,15 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252"]
+"tests/**/*" = ["D", "PLR2004", "S101", "TID252", "ANN"]
 # examples can contain "print" commands
-"examples/**/*" = ["T201"]
+"examples/**/*" = ["D", "T201"]
 
 
 [tool.coverage.run]
 source = ["haystack_integrations"]
 branch = true
+relative_files = true
 parallel = false
 
 [tool.coverage.report]

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/src/haystack_integrations/components/retrievers/pgvector/embedding_retriever.py

@@ -66,8 +66,10 @@ class PgvectorEmbeddingRetriever:
         top_k: int = 10,
         vector_function: Literal["cosine_similarity", "inner_product", "l2_distance"] | None = None,
         filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
-    ):
+    ) -> None:
         """
+        Initialize the PgvectorEmbeddingRetriever.
+
         :param document_store: An instance of `PgvectorDocumentStore`.
         :param filters: Filters applied to the retrieved Documents.
         :param top_k: Maximum number of Documents to return.

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/src/haystack_integrations/components/retrievers/pgvector/keyword_retriever.py

@@ -55,8 +55,10 @@ class PgvectorKeywordRetriever:
         filters: dict[str, Any] | None = None,
         top_k: int = 10,
         filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
-    ):
+    ) -> None:
         """
+        Initialize the PgvectorKeywordRetriever.
+
         :param document_store: An instance of `PgvectorDocumentStore`.
         :param filters: Filters applied to the retrieved Documents.
         :param top_k: Maximum number of Documents to return.

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/src/haystack_integrations/document_stores/pgvector/converters.py

@@ -10,8 +10,9 @@ logger = logging.getLogger(__name__)
 
 def _from_haystack_to_pg_documents(documents: list[Document]) -> list[dict[str, Any]]:
     """
-    Internal method to convert a list of Haystack Documents to a list of dictionaries that can be used to insert
-    documents into the PgvectorDocumentStore.
+    Internal method to convert a list of Haystack Documents to a list of dictionaries.
+
+    The resulting dictionaries can be used to insert documents into the PgvectorDocumentStore.
     """
 
     db_documents = []

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/src/haystack_integrations/document_stores/pgvector/document_store.py

@@ -96,9 +96,10 @@ class PgvectorDocumentStore:
         hnsw_index_name: str = "haystack_hnsw_index",
         hnsw_ef_search: int | None = None,
         keyword_index_name: str = "haystack_keyword_index",
-    ):
+    ) -> None:
         """
         Creates a new PgvectorDocumentStore instance.
+
         It is meant to be connected to a PostgreSQL database with the pgvector extension installed.
         A specific table to store Haystack documents will be created if it doesn't exist yet.
 
@@ -223,7 +224,7 @@ class PgvectorDocumentStore:
         return default_from_dict(cls, data)
 
     @staticmethod
-    def _connection_is_valid(connection):
+    def _connection_is_valid(connection: Connection) -> bool:
         """
         Internal method to check if the connection is still valid.
         """
@@ -238,7 +239,7 @@ class PgvectorDocumentStore:
         return True
 
     @staticmethod
-    async def _connection_is_valid_async(connection):
+    async def _connection_is_valid_async(connection: AsyncConnection) -> bool:
         """
         Internal method to check if the async connection is still valid.
         """
@@ -250,18 +251,18 @@ class PgvectorDocumentStore:
 
     @overload
     def _execute_sql(
-        self, cursor: Cursor, sql_query: Composed, params: tuple | None = None, error_msg: str = ""
+        self, cursor: Cursor, sql_query: SQL | Composed, params: tuple | None = None, error_msg: str = ""
     ) -> Cursor: ...
 
     @overload
     def _execute_sql(
-        self, cursor: Cursor[DictRow], sql_query: Composed, params: tuple | None = None, error_msg: str = ""
+        self, cursor: Cursor[DictRow], sql_query: SQL | Composed, params: tuple | None = None, error_msg: str = ""
     ) -> Cursor[DictRow]: ...
 
     def _execute_sql(
         self,
         cursor: Cursor | Cursor[DictRow],
-        sql_query: Composed,
+        sql_query: SQL | Composed,
         params: tuple | None = None,
         error_msg: str = "",
     ) -> Cursor | Cursor[DictRow]:
@@ -299,18 +300,18 @@ class PgvectorDocumentStore:
 
     @overload
     async def _execute_sql_async(
-        self, cursor: AsyncCursor, sql_query: Composed, params: tuple | None = None, error_msg: str = ""
+        self, cursor: AsyncCursor, sql_query: SQL | Composed, params: tuple | None = None, error_msg: str = ""
     ) -> AsyncCursor: ...
 
     @overload
     async def _execute_sql_async(
-        self, cursor: AsyncCursor[DictRow], sql_query: Composed, params: tuple | None = None, error_msg: str = ""
+        self, cursor: AsyncCursor[DictRow], sql_query: SQL | Composed, params: tuple | None = None, error_msg: str = ""
     ) -> AsyncCursor[DictRow]: ...
 
     async def _execute_sql_async(
         self,
         cursor: AsyncCursor | AsyncCursor[DictRow],
-        sql_query: Composed,
+        sql_query: SQL | Composed,
         params: tuple | None = None,
         error_msg: str = "",
     ) -> AsyncCursor | AsyncCursor[DictRow]:
@@ -346,9 +347,10 @@ class PgvectorDocumentStore:
 
         return result
 
-    def _ensure_db_setup(self):
+    def _ensure_db_setup(self) -> None:
         """
         Ensures that the connection to the PostgreSQL database exists and is valid.
+
         If not, connection and cursors are created.
         If the table is not initialized, it will be set up.
         """
@@ -384,9 +386,10 @@ class PgvectorDocumentStore:
         if not self._table_initialized:
             self._initialize_table()
 
-    async def _ensure_db_setup_async(self):
+    async def _ensure_db_setup_async(self) -> None:
         """
         Async internal method.
+
         Ensures that the connection to the PostgreSQL database exists and is valid.
         If not, connection and cursors are created.
         If the table is not initialized, it will be set up.
@@ -426,7 +429,7 @@ class PgvectorDocumentStore:
         if not self._table_initialized:
             await self._initialize_table_async()
 
-    def _build_table_creation_queries(self):
+    def _build_table_creation_queries(self) -> tuple[SQL, Composed, SQL, Composed]:
         """
         Internal method to build the SQL queries for table creation.
         """
@@ -453,7 +456,7 @@ class PgvectorDocumentStore:
 
         return sql_table_exists, sql_create_table, sql_keyword_index_exists, sql_create_keyword_index
 
-    def _initialize_table(self):
+    def _initialize_table(self) -> None:
         """
         Internal method to initialize the table.
         """
@@ -497,7 +500,7 @@ class PgvectorDocumentStore:
 
         self._table_initialized = True
 
-    async def _initialize_table_async(self):
+    async def _initialize_table_async(self) -> None:
         """
         Internal async method to initialize the table.
         """
@@ -547,9 +550,10 @@ class PgvectorDocumentStore:
 
         self._table_initialized = True
 
-    def delete_table(self):
+    def delete_table(self) -> None:
         """
         Deletes the table used to store Haystack documents.
+
         The name of the schema (`schema_name`) and the name of the table (`table_name`)
         are defined when initializing the `PgvectorDocumentStore`.
         """
@@ -567,7 +571,7 @@ class PgvectorDocumentStore:
             error_msg=f"Could not delete table {self.schema_name}.{self.table_name} in PgvectorDocumentStore",
         )
 
-    async def delete_table_async(self):
+    async def delete_table_async(self) -> None:
         """
         Async method to delete the table used to store Haystack documents.
         """
@@ -585,7 +589,7 @@ class PgvectorDocumentStore:
             error_msg=f"Could not delete table {self.schema_name}.{self.table_name} in PgvectorDocumentStore",
         )
 
-    def _build_hnsw_queries(self):
+    def _build_hnsw_queries(self) -> tuple[Composed | None, SQL, Composed, Composed]:
         """Common method to build all HNSW-related SQL queries"""
 
         sql_set_hnsw_ef_search = (
@@ -633,9 +637,10 @@ class PgvectorDocumentStore:
 
         return sql_set_hnsw_ef_search, sql_hnsw_index_exists, sql_drop_hnsw_index, sql_create_hnsw_index
 
-    def _handle_hnsw(self):
+    def _handle_hnsw(self) -> None:
         """
         Internal method to handle the HNSW index creation.
+
         It also sets the `hnsw.ef_search` parameter for queries if it is specified.
         """
 
@@ -645,7 +650,7 @@ class PgvectorDocumentStore:
 
         assert self._cursor is not None
 
-        if self.hnsw_ef_search:
+        if sql_set_hnsw_ef_search is not None:
             self._execute_sql(
                 cursor=self._cursor, sql_query=sql_set_hnsw_ef_search, error_msg="Could not set hnsw.ef_search"
             )
@@ -671,7 +676,7 @@ class PgvectorDocumentStore:
 
         self._execute_sql(cursor=self._cursor, sql_query=sql_create_hnsw_index, error_msg="Could not create HNSW index")
 
-    async def _handle_hnsw_async(self):
+    async def _handle_hnsw_async(self) -> None:
         """
         Internal async method to handle the HNSW index creation.
         """
@@ -682,7 +687,7 @@ class PgvectorDocumentStore:
 
         assert self._async_cursor is not None
 
-        if self.hnsw_ef_search:
+        if sql_set_hnsw_ef_search is not None:
             await self._execute_sql_async(
                 cursor=self._async_cursor, sql_query=sql_set_hnsw_ef_search, error_msg="Could not set hnsw.ef_search"
             )
@@ -1346,10 +1351,13 @@ class PgvectorDocumentStore:
         # cosine_similarity and inner_product are modified from the result of the operator
         if vector_function == "cosine_similarity":
             score_definition = f"1 - (embedding <=> {query_embedding_for_postgres}) AS score"
+            order_by_definition = f"embedding <=> {query_embedding_for_postgres}"
         elif vector_function == "inner_product":
             score_definition = f"(embedding <#> {query_embedding_for_postgres}) * -1 AS score"
+            order_by_definition = f"embedding <#> {query_embedding_for_postgres}"
         elif vector_function == "l2_distance":
             score_definition = f"embedding <-> {query_embedding_for_postgres} AS score"
+            order_by_definition = f"embedding <-> {query_embedding_for_postgres}"
 
         sql_select = SQL("SELECT *, {score} FROM {schema_name}.{table_name}").format(
             schema_name=Identifier(self.schema_name),
@@ -1362,13 +1370,9 @@ class PgvectorDocumentStore:
         if filters:
             sql_where_clause, params = _convert_filters_to_where_clause_and_params(filters)
 
-        # we always want to return the most similar documents first
-        # so when using l2_distance, the sort order must be ASC
-        sort_order = "ASC" if vector_function == "l2_distance" else "DESC"
-
-        sql_sort = SQL(" ORDER BY score {sort_order} LIMIT {top_k}").format(
+        sql_sort = SQL(" ORDER BY {order_by} ASC LIMIT {top_k}").format(
             top_k=SQLLiteral(top_k),
-            sort_order=SQL(sort_order),
+            order_by=SQL(order_by_definition),
         )
 
         sql_query = sql_select + sql_where_clause + sql_sort
@@ -1418,8 +1422,9 @@ class PgvectorDocumentStore:
         vector_function: Literal["cosine_similarity", "inner_product", "l2_distance"] | None = None,
     ) -> list[Document]:
         """
-        Asynchronously retrieves documents that are most similar to the query embedding using a
-        vector similarity metric.
+        Asynchronously retrieves documents that are most similar to the query embedding.
+
+        Uses a vector similarity metric for comparison.
         """
 
         sql_query, params = self._check_and_build_embedding_retrieval_query(
@@ -1439,7 +1444,7 @@ class PgvectorDocumentStore:
         docs = _from_pg_to_haystack_documents(records)
         return docs
 
-    def _prepare_filters_count_documents(self, filters):
+    def _prepare_filters_count_documents(self, filters: dict[str, Any] | None) -> tuple[tuple[Any, ...], Composed]:
         _validate_filters(filters)
         sql_count = SQL("SELECT COUNT(*) FROM {schema_name}.{table_name}").format(
             schema_name=Identifier(self.schema_name), table_name=Identifier(self.table_name)
@@ -1571,8 +1576,9 @@ class PgvectorDocumentStore:
 
     def count_unique_metadata_by_filter(self, filters: dict[str, Any], metadata_fields: list[str]) -> dict[str, int]:
         """
-        Returns the count of unique values for each specified metadata field,
-        considering only documents that match the provided filters.
+        Returns the count of unique values for each specified metadata field.
+
+        Considers only documents that match the provided filters.
 
         :param filters: The filters to apply to select documents.
             For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
@@ -1604,8 +1610,9 @@ class PgvectorDocumentStore:
         self, filters: dict[str, Any], metadata_fields: list[str]
     ) -> dict[str, int]:
         """
-        Asynchronously returns the count of unique values for each specified metadata field,
-        considering only documents that match the provided filters.
+        Asynchronously returns the count of unique values for each specified metadata field.
+
+        Considers only documents that match the provided filters.
 
         :param filters: The filters to apply to select documents.
             For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
@@ -1661,7 +1668,7 @@ class PgvectorDocumentStore:
         :param records: List of database records containing 'meta' field.
         :returns: A dictionary mapping field names to their type information.
         """
-        fields_info: dict[str, dict[str, str]] = {"content": {"type": "text"}}
+        fields_info: dict[str, dict[str, str]] = {}
 
         # Analyze metadata from all documents
         for record in records:
@@ -1681,7 +1688,7 @@ class PgvectorDocumentStore:
 
         return fields_info
 
-    def _analyze_metadata_from_docs_query(self):
+    def _analyze_metadata_from_docs_query(self) -> Composed:
         # query all documents to analyze metadata structure
         sql_query = SQL("SELECT meta FROM {schema_name}.{table_name} WHERE meta IS NOT NULL").format(
             schema_name=Identifier(self.schema_name), table_name=Identifier(self.table_name)
@@ -1698,7 +1705,6 @@ class PgvectorDocumentStore:
         Example return:
         ```python
         {
-            'content': {'type': 'text'},
             'category': {'type': 'text'},
             'status': {'type': 'text'},
             'priority': {'type': 'integer'},
@@ -1838,15 +1844,14 @@ class PgvectorDocumentStore:
         :returns: A dictionary with 'min' and 'max' keys containing the minimum and maximum values.
             For numeric fields (integer, real), returns numeric min/max.
             For text fields, returns lexicographic min/max based on database collation.
-        :raises ValueError: If the field doesn't exist or has no values.
+            Returns `{"min": None, "max": None}` when the field has no values or the store is empty.
         """
         normalized_field = PgvectorDocumentStore._normalize_metadata_field_name(metadata_field)
 
         # Get field type information from metadata fields info
         fields_info = self.get_metadata_fields_info()
         if normalized_field not in fields_info:
-            msg = f"Metadata field '{metadata_field}' not found in document store"
-            raise ValueError(msg)
+            return {"min": None, "max": None}
 
         field_type = fields_info[normalized_field]["type"]
         sql_query = self._build_min_max_query(normalized_field, field_type)
@@ -1871,15 +1876,14 @@ class PgvectorDocumentStore:
         :returns: A dictionary with 'min' and 'max' keys containing the minimum and maximum values.
             For numeric fields (integer, real), returns numeric min/max.
             For text fields, returns lexicographic min/max based on database collation.
-        :raises ValueError: If the field doesn't exist or has no values.
+            Returns ``{"min": None, "max": None}`` when the field has no values or the store is empty.
         """
         normalized_field = PgvectorDocumentStore._normalize_metadata_field_name(metadata_field)
 
         # Get field type information from metadata fields info
         fields_info = await self.get_metadata_fields_info_async()
         if normalized_field not in fields_info:
-            msg = f"Metadata field '{metadata_field}' not found in document store"
-            raise ValueError(msg)
+            return {"min": None, "max": None}
 
         field_type = fields_info[normalized_field]["type"]
         sql_query = self._build_min_max_query(normalized_field, field_type)

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/src/haystack_integrations/document_stores/pgvector/filters.py

@@ -116,8 +116,7 @@ def _parse_comparison_condition(condition: dict[str, Any]) -> tuple[Composed, li
 
 def _treat_meta_field(field: str, value: Any) -> Composed:
     """
-    Internal method that returns a psycopg Composed object
-    to make the meta JSONB field queryable safely.
+    Internal method that returns a psycopg Composed object to make the meta JSONB field queryable safely.
 
     Uses psycopg.sql.Literal to embed the field name, preventing SQL injection
     via metadata field names without requiring regex validation.

{pgvector_haystack-6.3.0 → pgvector_haystack-6.3.1}/tests/conftest.py

@@ -1,6 +1,7 @@
-from unittest.mock import patch
+from unittest.mock import Mock, patch
 
 import pytest
+from psycopg import AsyncConnection, Connection
 
 from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
 
@@ -110,3 +111,15 @@ def mock_store(patches_for_unit_tests, monkeypatch):  # noqa: ARG001  patches ar
     )
 
     yield store
+
+
+@pytest.fixture
+def mock_store_with_mock_connection(mock_store):
+    mock_store._connection = Mock(spec=Connection)
+    return mock_store
+
+
+@pytest.fixture
+def mock_store_with_mock_async_connection(mock_store):
+    mock_store._async_connection = Mock(spec=AsyncConnection)
+    return mock_store