> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinecone

> Using Pinecone as a vector database provider

## Overview

Pinecone is a managed vector database service designed for production-scale similarity search. It's cloud-only and supports both dense and sparse vectors with automatic scaling.

**Provider Class:** `PineconeProvider`\
**Config Class:** `PineconeConfig`

## Install

<Note>
  Install the Pinecone optional dependency group:

  ```bash theme={null}
  uv pip install "upsonic[pinecone]"
  ```
</Note>

## Examples

```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.vectordb import PineconeProvider, PineconeConfig
from pydantic import SecretStr

# Setup embedding provider
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())

# Create Pinecone configuration
config = PineconeConfig(
    collection_name="my_collection",
    vector_size=1536,
    api_key=SecretStr("your-pinecone-api-key"),
    environment="us-east-1-aws",
    namespace="production"
)
vectordb = PineconeProvider(config)

# Create knowledge base
kb = KnowledgeBase(
    sources="document.pdf",
    embedding_provider=embedding,
    vectordb=vectordb
)

# Use with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task(
    description="Query the knowledge base",
    context=[kb]
)
result = agent.do(task)
```

## Parameters

### Base Parameters (from BaseVectorDBConfig)

| Parameter | Type | Description | Default | Required |
| - | - | - | - | - |
| `collection_name` | `str` | Name of the collection | `"default_collection"` | No |
| `vector_size` | `int` | Dimension of vectors | - | **Yes** |
| `distance_metric` | `DistanceMetric` | Similarity metric (`COSINE`, `EUCLIDEAN`, `DOT_PRODUCT`) | `COSINE` | No |
| `recreate_if_exists` | `bool` | Recreate collection if it exists | `False` | No |
| `default_top_k` | `int` | Default number of results | `10` | No |
| `default_similarity_threshold` | `Optional[float]` | Minimum similarity score (0.0-1.0) | `None` | No |
| `dense_search_enabled` | `bool` | Enable dense vector search | `True` | No |
| `full_text_search_enabled` | `bool` | Enable full-text search | `True` | No |
| `hybrid_search_enabled` | `bool` | Enable hybrid search | `True` | No |
| `default_hybrid_alpha` | `float` | Default alpha for hybrid search (0.0-1.0) | `0.5` | No |
| `default_fusion_method` | `Literal['rrf', 'weighted']` | Default fusion method for hybrid search | `'weighted'` | No |
| `provider_name` | `Optional[str]` | Provider name | `None` | No |
| `provider_description` | `Optional[str]` | Provider description | `None` | No |
| `provider_id` | `Optional[str]` | Provider ID | `None` | No |
| `default_metadata` | `Optional[Dict[str, Any]]` | Default metadata for all records | `None` | No |
| `indexed_fields` | `Optional[List[Union[str, Dict[str, Any]]]]` | Fields to index for filtering | `None` | No |

### Pinecone-Specific Parameters

| Parameter | Type | Description | Default | Required |
| - | - | - | - | - |
| `api_key` | `SecretStr` | Pinecone API key | - | **Yes** |
| `spec` | `Optional[Union[Dict[str, Any], ServerlessSpec, PodSpec]]` | Index specification (ServerlessSpec or PodSpec) | `None` | No |
| `environment` | `Optional[str]` | Environment/region for backward compatibility (e.g., "aws-us-east-1") | `None` | No |
| `namespace` | `Optional[str]` | Namespace for data isolation | `None` | No |
| `metric` | `Literal['cosine', 'euclidean', 'dotproduct']` | Distance metric (auto-mapped from `distance_metric`) | `'cosine'` | No |
| `pods` | `Optional[int]` | Number of pods (for PodSpec) | `None` | No |
| `pod_type` | `Optional[str]` | Pod type specification (for PodSpec) | `None` | No |
| `replicas` | `Optional[int]` | Number of replicas (for PodSpec) | `None` | No |
| `shards` | `Optional[int]` | Number of shards (for PodSpec) | `None` | No |
| `host` | `Optional[str]` | Custom Pinecone host | `None` | No |
| `additional_headers` | `Optional[Dict[str, str]]` | Additional HTTP headers | `None` | No |
| `pool_threads` | `Optional[int]` | Thread pool size | `1` | No |
| `index_api` | `Optional[Any]` | Custom index API instance | `None` | No |
| `use_sparse_vectors` | `bool` | Enable sparse vector support (requires `hybrid_search_enabled=True`, sets metric to `dotproduct`) | `False` | No |
| `sparse_encoder_model` | `str` | Model for sparse vector generation | `"pinecone-sparse-english-v0"` | No |
| `batch_size` | `int` | Batch size for upsert operations | `100` | No |
| `show_progress` | `bool` | Show progress during batch operations | `False` | No |
| `timeout` | `Optional[int]` | Request timeout in seconds | `None` | No |
| `reranker` | `Optional[Any]` | Reranker instance for post-processing results | `None` | No |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.