PgvectorEmbeddingRetriever

Retrieve documents from a PgvectorDocumentStore using dense vector embeddings.

Key Features

• Dense vector-based retrieval from PostgreSQL with the pgvector extension.
• Configurable number of results with top_k.
• Supports metadata filtering to narrow down the search space.
• Supports multiple vector similarity functions: cosine similarity, inner product, and L2 distance.
• Configurable filter policy (replace or merge) for runtime filters.

Configuration

1. Drag the PgvectorEmbeddingRetriever component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Configure the PgvectorDocumentStore with your PostgreSQL connection string.
   • Set top_k to control the maximum number of documents to retrieve.
4. Go to the Advanced tab to configure vector_function and filter_policy.

Connections

PgvectorEmbeddingRetriever receives query embeddings from a text embedder. It sends retrieved documents to downstream components such as PromptBuilder or a ranker.

Source Code

To check this component's source code, open embedding_retriever.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  PgvectorEmbeddingRetriever:
    type: haystack_integrations.components.retrievers.pgvector.embedding_retriever.PgvectorEmbeddingRetriever
    init_parameters:
      top_k: 10
      document_store:
        type: haystack_integrations.document_stores.pgvector.document_store.PgvectorDocumentStore
        init_parameters:
          connection_string:
            type: env_var
            env_vars:
            - PG_CONN_STR
            strict: false
          table_name: haystack_documents
          embedding_dimension: 768

Using the Component in a Pipeline

# haystack-pipeline
components:
  PgvectorEmbeddingRetriever:
    type: haystack_integrations.components.retrievers.pgvector.embedding_retriever.PgvectorEmbeddingRetriever
    init_parameters:
      top_k: 10
      filter_policy: replace
      document_store:
        type: haystack_integrations.document_stores.pgvector.document_store.PgvectorDocumentStore
        init_parameters:
          connection_string:
            type: env_var
            env_vars:
            - PG_CONN_STR
            strict: false
          table_name: haystack_documents
          embedding_dimension: 768
          vector_function: cosine_similarity

connections: []

max_runs_per_component: 100

metadata: {}

inputs:
  query_embedding:
  - PgvectorEmbeddingRetriever.query_embedding

outputs:
  documents: PgvectorEmbeddingRetriever.documents

Parameters

Inputs

Parameter	Type	Description
query_embedding	List[float]	The embedding of the query.
filters	Optional[Dict[str, Any]]	Filters to apply to the search results.
top_k	Optional[int]	The maximum number of documents to return.
vector_function	Optional[Literal]	The vector similarity function to use.

Outputs

Parameter	Type	Description
documents	List[Document]	The retrieved documents.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	PgvectorDocumentStore		An instance of PgvectorDocumentStore.
filters	Optional[Dict[str, Any]]	None	Default filters applied when running the retriever.
top_k	int	10	The maximum number of documents to retrieve.
vector_function	Optional[Literal["cosine_similarity", "inner_product", "l2_distance"]]	None	The vector similarity function to use. If not set, uses the function configured in the document store.
filter_policy	Union[str, FilterPolicy]	FilterPolicy.REPLACE	Policy for how runtime filters are applied relative to init-time filters.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query_embedding	List[float]		The embedding of the query.
filters	Optional[Dict[str, Any]]	None	Filters to apply at query time.
top_k	Optional[int]	None	Override the init-time top_k setting.
vector_function	Optional[Literal]	None	Override the init-time vector function.

Related Information

• Pipeline Components