pgvector-haystack 8.1.1__tar.gz → 8.2.0__tar.gz

{pgvector_haystack-8.1.1 → pgvector_haystack-8.2.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [integrations/pgvector-v8.1.2] - 2026-10-21
+
+### 🚀 Features
+
+- *(pgvector)* Ensure safe SQL handling for HNSW index creation and embedding queries (#4139)
+
+
+## [integrations/pgvector-v8.1.1] - 2026-10-21
+
+### 🐛 Bug Fixes
+
+- *(pgvector)* Pass document ids as a bound parameter in delete_docum… (#4135)
+
+
 ## [integrations/pgvector-v8.1.0] - 2026-10-20
 
 ### 🚀 Features

{pgvector_haystack-8.1.1 → pgvector_haystack-8.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgvector-haystack
-Version: 8.1.1
+Version: 8.2.0
 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

{pgvector_haystack-8.1.1 → pgvector_haystack-8.2.0}/src/haystack_integrations/document_stores/pgvector/document_store.py

@@ -22,6 +22,7 @@ from pgvector.psycopg import register_vector, register_vector_async
 
 from .converters import _from_haystack_to_pg_documents, _from_pg_to_haystack_documents
 from .filters import _convert_filters_to_where_clause_and_params, _validate_filters
+from .table_replacement import replace_table, replace_table_async
 
 logger = logging.getLogger(__name__)
 
@@ -635,6 +636,176 @@ class PgvectorDocumentStore:
             error_msg=f"Could not delete table {self.schema_name}.{self.table_name} in PgvectorDocumentStore",
         )
 
+    def replace_table(
+        self,
+        staging_store: "PgvectorDocumentStore",
+        *,
+        backup_table_name: str | None = None,
+        lock_timeout_ms: int = 5000,
+    ) -> str:
+        """
+        Atomically replace this store's table with the table of a populated staging store.
+
+        Use this to rebuild a document store without downtime: write the new documents into a staging store, then
+        swap it in. Queries see either the old or the new documents, never a partially filled table. The former
+        table is kept as a backup until you drop it.
+
+        Requirements:
+        - `staging_store` must connect to the same PostgreSQL database and use the same `schema_name`,
+          `embedding_dimension`, `vector_type`, `vector_function`, `language`, and `search_strategy`, plus the same
+          `hnsw_index_creation_kwargs` with the `hnsw` search strategy.
+        - Index names are unique per schema, so `staging_store` needs its own `keyword_index_name` and, with the
+          `hnsw` search strategy, its own `hnsw_index_name`. A staging store with the default index names fails
+          when it creates its table.
+        - The staging table must already exist. This method never creates it.
+        - Pause writes to this store during the swap. A write that is in flight when the swap starts lands in the
+          backup table, not in the promoted one.
+
+        Locking: the swap takes an `ACCESS EXCLUSIVE` lock on both tables, so it first waits for running queries on
+        them to finish. While it waits, new reads and writes on both tables wait too. If the locks are not acquired
+        within `lock_timeout_ms`, nothing is changed. The renames themselves are fast.
+
+        After a successful swap, this store serves the promoted documents under its own table and index names, and
+        `staging_store` is repointed to the backup: its `table_name`, `keyword_index_name`, and, with the `hnsw`
+        search strategy, `hnsw_index_name` are set to the backup names. Call `staging_store.delete_table()` to
+        drop the former documents once you no longer need them. Because these attributes change,
+        `staging_store.to_dict()` also returns the backup names after the swap.
+
+        Don't create stores that serve queries with `recreate_table=True`. Any new instance with that setting, for
+        example in another process or a pipeline loaded from YAML, drops the live table when it first connects.
+
+        ### Usage example
+
+        ```python
+        from haystack import Document
+        from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+
+        live_store = PgvectorDocumentStore(table_name="docs", embedding_dimension=768)
+        live_store.write_documents([Document(content="The current corpus")])  # already serving queries
+
+        # The staging store can reuse the same names on every rebuild: after a swap they are free again.
+        staging_store = PgvectorDocumentStore(
+            table_name="docs_staging",
+            embedding_dimension=768,
+            keyword_index_name="docs_staging_keyword_index",
+        )
+        staging_store.write_documents([Document(content="The rebuilt corpus")])
+
+        # Pause writes to live_store, then swap.
+        backup_table_name = live_store.replace_table(staging_store)
+
+        # live_store now serves the rebuilt corpus. staging_store points at the backup table.
+        staging_store.delete_table()
+        ```
+
+        :param staging_store: A populated store whose table replaces this store's table. Must meet the
+            requirements above.
+        :param backup_table_name: Name to keep the former table under. Must not exist yet. If not set, a unique
+            name of the form `<table_name>_backup_<suffix>` is generated.
+        :param lock_timeout_ms: How long to wait for the table locks, in milliseconds, before giving up. Reads and
+            writes on both tables also wait during this time. Must be a positive integer.
+        :returns: The name of the backup table that now holds the former documents.
+        :raises TypeError: If `lock_timeout_ms` is not an `int`.
+        :raises ValueError: If `staging_store` is configured incompatibly with this store as described in the
+            requirements above, connects to a different database, or if `backup_table_name` is invalid or
+            `lock_timeout_ms` is not positive.
+        :raises DocumentStoreError: If either table doesn't exist, the tables have different columns or
+            constraints, an expected index is missing, `backup_table_name` or a generated backup index name is
+            already taken, the locks are not acquired within `lock_timeout_ms`, or the database reports another
+            error. In every case the swap is rolled back and nothing is changed.
+        """
+        return replace_table(
+            self,
+            staging_store,
+            backup_table_name=backup_table_name,
+            lock_timeout_ms=lock_timeout_ms,
+        )
+
+    async def replace_table_async(
+        self,
+        staging_store: "PgvectorDocumentStore",
+        *,
+        backup_table_name: str | None = None,
+        lock_timeout_ms: int = 5000,
+    ) -> str:
+        """
+        Asynchronously and atomically replace this store's table with the table of a populated staging store.
+
+        Use this to rebuild a document store without downtime: write the new documents into a staging store, then
+        swap it in. Queries see either the old or the new documents, never a partially filled table. The former
+        table is kept as a backup until you drop it.
+
+        Requirements:
+        - `staging_store` must connect to the same PostgreSQL database and use the same `schema_name`,
+          `embedding_dimension`, `vector_type`, `vector_function`, `language`, and `search_strategy`, plus the same
+          `hnsw_index_creation_kwargs` with the `hnsw` search strategy.
+        - Index names are unique per schema, so `staging_store` needs its own `keyword_index_name` and, with the
+          `hnsw` search strategy, its own `hnsw_index_name`. A staging store with the default index names fails
+          when it creates its table.
+        - The staging table must already exist. This method never creates it.
+        - Pause writes to this store during the swap. A write that is in flight when the swap starts lands in the
+          backup table, not in the promoted one.
+
+        Locking: the swap takes an `ACCESS EXCLUSIVE` lock on both tables, so it first waits for running queries on
+        them to finish. While it waits, new reads and writes on both tables wait too. If the locks are not acquired
+        within `lock_timeout_ms`, nothing is changed. The renames themselves are fast.
+
+        After a successful swap, this store serves the promoted documents under its own table and index names, and
+        `staging_store` is repointed to the backup: its `table_name`, `keyword_index_name`, and, with the `hnsw`
+        search strategy, `hnsw_index_name` are set to the backup names. Call `staging_store.delete_table_async()` to
+        drop the former documents once you no longer need them. Because these attributes change,
+        `staging_store.to_dict()` also returns the backup names after the swap.
+
+        Don't create stores that serve queries with `recreate_table=True`. Any new instance with that setting, for
+        example in another process or a pipeline loaded from YAML, drops the live table when it first connects.
+
+        ### Usage example
+
+        ```python
+        from haystack import Document
+        from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore
+
+        live_store = PgvectorDocumentStore(table_name="docs", embedding_dimension=768)
+        await live_store.write_documents_async([Document(content="The current corpus")])  # already serving queries
+
+        # The staging store can reuse the same names on every rebuild: after a swap they are free again.
+        staging_store = PgvectorDocumentStore(
+            table_name="docs_staging",
+            embedding_dimension=768,
+            keyword_index_name="docs_staging_keyword_index",
+        )
+        await staging_store.write_documents_async([Document(content="The rebuilt corpus")])
+
+        # Pause writes to live_store, then swap.
+        backup_table_name = await live_store.replace_table_async(staging_store)
+
+        # live_store now serves the rebuilt corpus. staging_store points at the backup table.
+        await staging_store.delete_table_async()
+        ```
+
+        :param staging_store: A populated store whose table replaces this store's table. Must meet the
+            requirements above.
+        :param backup_table_name: Name to keep the former table under. Must not exist yet. If not set, a unique
+            name of the form `<table_name>_backup_<suffix>` is generated.
+        :param lock_timeout_ms: How long to wait for the table locks, in milliseconds, before giving up. Reads and
+            writes on both tables also wait during this time. Must be a positive integer.
+        :returns: The name of the backup table that now holds the former documents.
+        :raises TypeError: If `lock_timeout_ms` is not an `int`.
+        :raises ValueError: If `staging_store` is configured incompatibly with this store as described in the
+            requirements above, connects to a different database, or if `backup_table_name` is invalid or
+            `lock_timeout_ms` is not positive.
+        :raises DocumentStoreError: If either table doesn't exist, the tables have different columns or
+            constraints, an expected index is missing, `backup_table_name` or a generated backup index name is
+            already taken, the locks are not acquired within `lock_timeout_ms`, or the database reports another
+            error. In every case the swap is rolled back and nothing is changed.
+        """
+        return await replace_table_async(
+            self,
+            staging_store,
+            backup_table_name=backup_table_name,
+            lock_timeout_ms=lock_timeout_ms,
+        )
+
     def _build_hnsw_queries(self) -> tuple[Composed | None, SQL, Composed, Composed]:
         """Common method to build all HNSW-related SQL queries"""
 
@@ -678,8 +849,10 @@ class PgvectorDocumentStore:
             k: v for k, v in self.hnsw_index_creation_kwargs.items() if k in HNSW_INDEX_CREATION_VALID_KWARGS
         }
         if valid_kwargs:
-            kwargs_str = ", ".join(f"{k} = {v}" for k, v in valid_kwargs.items())
-            sql_create_hnsw_index += SQL(" WITH ({})").format(SQL(kwargs_str))
+            # the names are allowlisted; pass the values as literals, so they are never interpreted as SQL
+            sql_create_hnsw_index += SQL(" WITH ({})").format(
+                SQL(", ").join(SQL("{} = {}").format(SQL(k), SQLLiteral(v)) for k, v in valid_kwargs.items())
+            )
 
         return sql_set_hnsw_ef_search, sql_hnsw_index_exists, sql_drop_hnsw_index, sql_create_hnsw_index
 
@@ -1403,26 +1576,31 @@ class PgvectorDocumentStore:
             msg = f"vector_function must be one of {VALID_VECTOR_FUNCTIONS}, but got {vector_function}"
             raise ValueError(msg)
 
-        # the vector must be a string with this format: "'[3,1,2]'"
-        query_embedding_for_postgres = f"'[{','.join(str(el) for el in query_embedding)}]'"
+        # the vector must be a string with this format: "'[3.0,1.0,2.0]'"; the elements are converted to floats
+        # and the string is passed as a literal, so it is never interpreted as SQL
+        try:
+            query_embedding_for_postgres = SQLLiteral(f"[{','.join(str(float(el)) for el in query_embedding)}]")
+        except (TypeError, ValueError) as e:
+            msg = "query_embedding must be a list of floats"
+            raise TypeError(msg) from e
 
         # to compute the scores, we use the approach described in pgvector README:
         # https://github.com/pgvector/pgvector?tab=readme-ov-file#distances
         # 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}"
+            score_definition = SQL("1 - (embedding <=> {}) AS score").format(query_embedding_for_postgres)
+            order_by_definition = SQL("embedding <=> {}").format(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}"
+            score_definition = SQL("(embedding <#> {}) * -1 AS score").format(query_embedding_for_postgres)
+            order_by_definition = SQL("embedding <#> {}").format(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}"
+            score_definition = SQL("embedding <-> {} AS score").format(query_embedding_for_postgres)
+            order_by_definition = SQL("embedding <-> {}").format(query_embedding_for_postgres)
 
         sql_select = SQL("SELECT *, {score} FROM {schema_name}.{table_name}").format(
             schema_name=Identifier(self.schema_name),
             table_name=Identifier(self.table_name),
-            score=SQL(score_definition),
+            score=score_definition,
         )
 
         sql_where_clause: Composed | SQL = SQL("")
@@ -1432,7 +1610,7 @@ class PgvectorDocumentStore:
 
         sql_sort = SQL(" ORDER BY {order_by} ASC LIMIT {top_k}").format(
             top_k=SQLLiteral(top_k),
-            order_by=SQL(order_by_definition),
+            order_by=order_by_definition,
         )
 
         sql_query = sql_select + sql_where_clause + sql_sort