Skip to main content

​
Parameters

ParameterTypeDefaultDescription
configConfigRequiredA validated and immutable Config object containing all necessary parameters for the provider’s operation

​
Functions

​
connect

Establishes a connection to the Pinecone service. This method initializes the Pinecone client and connects to existing indexes if they exist. Raises:
  • VectorDBConnectionError: If the connection fails.

​
disconnect

Performs a logical disconnection from the Pinecone service. The client library manages connection pools, so this simply clears local state.

​
is_ready

Performs a health check on the configured Pinecone indexes. Returns True if all required indexes exist and are in a ready state. Returns:
  • bool: True if all configured indexes are ready, False otherwise.

​
create_collection

Creates a new collection (index) in Pinecone according to the configuration. This method handles recreate_if_exists logic and waits for the index to be fully ready. The physical index created is a unified container, capable of storing dense, sparse, or hybrid vectors based on the logic enforced in the upsert phase. Raises:
  • VectorDBConnectionError: If not connected to Pinecone to create a collection.
  • VectorDBError: If the collection creation fails.

​
delete_collection

Permanently deletes the collections specified in the config from Pinecone. This method will wait until indexes are no longer listed before returning. Raises:
  • VectorDBConnectionError: If not connected to Pinecone to delete collections.
  • VectorDBError: If the collection deletion fails.

​
collection_exists

Checks if the collection (index) specified in the config already exists in Pinecone. Returns:
  • bool: True if the collection exists, False otherwise.
Raises:
  • VectorDBConnectionError: If not connected to Pinecone to check if a collection exists.

​
upsert

Adds new data or updates existing data in the collection. This method validates the presence of required vector types based on the collection’s schema and uploads data in batches. Parameters:
  • vectors (List[List[float]]): A list of dense vector embeddings.
  • payloads (List[Dict[str, Any]]): A list of corresponding metadata objects.
  • ids (List[Union[str, int]]): A list of unique identifiers for each record.
  • chunks (Optional[List[str]]): A list of text chunks.
  • sparse_vectors (Optional[List[Dict[str, Any]]]): Optional sparse vectors.
  • **kwargs: Provider-specific options.
Raises:
  • VectorDBConnectionError: If not connected to Pinecone.
  • UpsertError: If the data ingestion fails or if the required vector types are missing or have mismatched lengths.

​
delete

Removes data from collections by their unique identifiers. Parameters:
  • ids (List[Union[str, int]]): A list of specific IDs to remove.
  • **kwargs: Provider-specific options.
Raises:
  • VectorDBConnectionError: If not connected to Pinecone.

​
fetch

Fetch records from appropriate indexes. Parameters:
  • ids (List[Union[str, int]]): A list of IDs to retrieve the full records for.
  • **kwargs: Provider-specific options.
Returns:
  • List[VectorSearchResult]: A list of VectorSearchResult objects containing the fetched data.
A master search method that validates the user’s intent against the collection’s configuration and dispatches to the appropriate specialized search function. Parameters:
  • top_k (Optional[int]): The number of results to return. If None, falls back to the default in the Config.
  • query_vector (Optional[List[float]]): The vector for dense or hybrid search.
  • query_text (Optional[str]): The text for full-text or hybrid search.
  • filter (Optional[Dict[str, Any]]): An optional metadata filter.
  • alpha (Optional[float]): The weighting factor for hybrid search. If None, falls back to the default in the Config.
  • fusion_method (Optional[Literal[‘rrf’, ‘weighted’]]): The algorithm to use for hybrid search (‘rrf’ or ‘weighted’).
  • similarity_threshold (Optional[float]): The minimum similarity score for results. If None, falls back to the default in the Config.
  • **kwargs: Additional provider-specific options.
Returns:
  • List[VectorSearchResult]: A list of VectorSearchResult objects.
Raises:
  • ConfigurationError: If the requested search is disabled or the wrong combination of arguments is provided.
  • SearchError: If any underlying search operation fails.
Performs a pure vector similarity search. Parameters:
  • query_vector (List[float]): The vector embedding to search for.
  • top_k (int): The number of top results to return.
  • filter (Optional[Dict[str, Any]]): A metadata filter to apply. Defaults to None.
  • similarity_threshold (Optional[float]): The minimum similarity score for results. Defaults to None.
  • **kwargs: Additional provider-specific options.
Returns:
  • List[VectorSearchResult]: A list of the most similar results.
Raises:
  • VectorDBConnectionError: If not connected to a Pinecone index.
  • SearchError: If the search operation fails.

​
full_text_search

Performs a sparse-vector-only lexical search. Parameters:
  • query_text (str): The text string to search for.
  • top_k (int): The number of top results to return.
  • filter (Optional[Dict[str, Any]]): A metadata filter to apply. Defaults to None.
  • similarity_threshold (Optional[float]): The minimum similarity score for results. Defaults to None.
  • **kwargs: Additional provider-specific options.
Returns:
  • List[VectorSearchResult]: A list of matching results.
Raises:
  • VectorDBConnectionError: If not connected to a Pinecone index.
  • SearchError: If the search operation fails.
Performs advanced hybrid search combining dense and sparse vectors with multiple fusion strategies. This implementation follows Pinecone’s recommended approach for separate dense and sparse indexes, combining results with sophisticated ranking and deduplication strategies. Parameters:
  • query_vector (List[float]): The dense vector for the semantic part of the search.
  • query_text (str): The raw text for the keyword/sparse part of the search.
  • top_k (int): The number of final results to return.
  • filter (Optional[Dict[str, Any]]): An optional metadata filter.
  • alpha (Optional[float]): The weight for combining scores. If None, falls back to the default in the Config.
  • fusion_method (Optional[Literal[‘rrf’, ‘weighted’]]): The algorithm to use for fusing results (‘rrf’ or ‘weighted’).
  • similarity_threshold (Optional[float]): The minimum similarity score for results. If None, falls back to the default in the Config.
  • **kwargs: Additional provider-specific options.
Returns:
  • List[VectorSearchResult]: A list of VectorSearchResult objects, ordered by the combined hybrid score.
Raises:
  • VectorDBConnectionError: If both dense and sparse indexes are required for hybrid search.
  • SearchError: If the search operation fails.
⌘I