---
title: "Pinecone Vector Configuration Guide"
---

# Pinecone Vector Configuration Guide

:::caution[Planned: not in the current release]
Pinecone API compatibility for HeliosDB Full is planned. Today, the HTTP gateway answers `/pinecone/` paths with `501 Not Implemented`. Reach
the same data over the PostgreSQL listener or `POST /api/v1/query` today. This page
describes the planned interface.
:::

Comprehensive configuration reference for HeliosDB's Pinecone vector protocol support.

## Connection Configuration

### Basic Connection

```python
from pinecone import Pinecone

# Connect to HeliosDB (Pinecone-compatible)
pc = Pinecone(
    api_key="your-api-key",
    host="http://localhost:8080"
)

# Access index
index = pc.Index("my-vectors")
```

### Connection Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | string | Required | API authentication key |
| `host` | string | Required | HeliosDB vector endpoint |
| `index` | string | Required | Index name |
| `namespace` | string | "" | Optional namespace |

## REST API Configuration

### Base URL

```
http://localhost:8080/vectors/v1
```

### Authentication Headers

```bash
curl -X POST "http://localhost:8080/vectors/v1/upsert" \
  -H "Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

### Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Api-Key` | Yes | API authentication key |
| `Content-Type` | Yes | application/json |
| `Accept` | No | Response format |

## Index Configuration

### Creating an Index

```python
# Create index with configuration
pc.create_index(
    name="my-vectors",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
        cloud="heliosdb",
        region="default"
    )
)
```

### Index Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string | Required | Index name |
| `dimension` | int | Required | Vector dimension |
| `metric` | string | cosine | Similarity metric |
| `pods` | int | 1 | Number of pods |
| `replicas` | int | 1 | Number of replicas |
| `pod_type` | string | p1.x1 | Pod type |

### Similarity Metrics

| Metric | Description | Use Case |
|--------|-------------|----------|
| `cosine` | Cosine similarity | Text embeddings |
| `euclidean` | Euclidean distance | Dense vectors |
| `dotproduct` | Dot product | Normalized vectors |

## Vector Operations Configuration

### Upsert Configuration

```python
# Upsert with options
index.upsert(
    vectors=[
        {
            "id": "vec1",
            "values": [0.1, 0.2, ...],
            "metadata": {"category": "A"}
        }
    ],
    namespace="production",
    show_progress=True
)
```

### Query Configuration

```python
# Query with options
results = index.query(
    vector=[0.1, 0.2, ...],
    top_k=10,
    filter={"category": {"$eq": "A"}},
    include_values=True,
    include_metadata=True,
    namespace="production"
)
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `vector` | list | Required | Query vector |
| `top_k` | int | 10 | Number of results |
| `filter` | dict | None | Metadata filter |
| `include_values` | bool | False | Include vectors |
| `include_metadata` | bool | False | Include metadata |
| `namespace` | string | "" | Namespace |

## Filtering Configuration

### Filter Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `$eq` | Equal | `{"field": {"$eq": "value"}}` |
| `$ne` | Not equal | `{"field": {"$ne": "value"}}` |
| `$gt` | Greater than | `{"field": {"$gt": 10}}` |
| `$gte` | Greater or equal | `{"field": {"$gte": 10}}` |
| `$lt` | Less than | `{"field": {"$lt": 10}}` |
| `$lte` | Less or equal | `{"field": {"$lte": 10}}` |
| `$in` | In list | `{"field": {"$in": ["a", "b"]}}` |
| `$nin` | Not in list | `{"field": {"$nin": ["a", "b"]}}` |

### Compound Filters

```python
# AND filter
filter = {
    "$and": [
        {"category": {"$eq": "A"}},
        {"price": {"$lt": 100}}
    ]
}

# OR filter
filter = {
    "$or": [
        {"category": {"$eq": "A"}},
        {"category": {"$eq": "B"}}
    ]
}
```

## Batch Configuration

### Batch Upsert

```python
# Batch configuration
index.upsert(
    vectors=large_vector_list,
    batch_size=100,  # Vectors per batch
    show_progress=True
)
```

### Batch Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `batch_size` | 100 | Vectors per batch |
| `pool_threads` | 1 | Parallel threads |
| `show_progress` | False | Progress bar |

## Namespace Configuration

### Working with Namespaces

```python
# Upsert to specific namespace
index.upsert(
    vectors=[...],
    namespace="production"
)

# Query specific namespace
results = index.query(
    vector=[...],
    namespace="production"
)

# Delete from namespace
index.delete(
    ids=["vec1", "vec2"],
    namespace="production"
)

# List namespaces
stats = index.describe_index_stats()
namespaces = stats.namespaces
```

## Hybrid Search Configuration

### Dense + Sparse Vectors

```python
# Upsert with sparse vectors
index.upsert(
    vectors=[
        {
            "id": "vec1",
            "values": [0.1, 0.2, ...],  # Dense vector
            "sparse_values": {
                "indices": [1, 5, 100],
                "values": [0.5, 0.3, 0.1]
            },
            "metadata": {"category": "A"}
        }
    ]
)

# Hybrid query
results = index.query(
    vector=[0.1, 0.2, ...],
    sparse_vector={
        "indices": [1, 5],
        "values": [0.5, 0.3]
    },
    top_k=10
)
```

## HeliosDB-Specific Settings

### Server Configuration

```toml
# heliosdb.toml
[pinecone]
enabled = true
port = 8080
bind = "0.0.0.0"
max_connections = 10000

[pinecone.auth]
api_key = "your-secure-api-key"

[pinecone.index]
default_dimension = 1536
default_metric = "cosine"
max_vectors = 10000000
max_metadata_size = 40960

[pinecone.performance]
batch_size = 1000
query_threads = 8
index_threads = 4
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `HELIOSDB_PINECONE_PORT` | Vector API port |
| `HELIOSDB_PINECONE_API_KEY` | API authentication key |
| `HELIOSDB_PINECONE_MAX_DIMENSION` | Max vector dimension |
| `HELIOSDB_PINECONE_MAX_VECTORS` | Max vectors per index |

## Performance Tuning

### Query Optimization

```python
# Optimize for speed
results = index.query(
    vector=[...],
    top_k=10,
    include_values=False,  # Don't return vectors
    include_metadata=False  # Don't return metadata
)

# Optimize for accuracy
results = index.query(
    vector=[...],
    top_k=100,  # Fetch more, filter client-side
    include_metadata=True
)
```

### Batch Insert Optimization

```python
# Optimal batch size
BATCH_SIZE = 100  # Recommended for most cases

# Insert in batches
for i in range(0, len(vectors), BATCH_SIZE):
    batch = vectors[i:i+BATCH_SIZE]
    index.upsert(vectors=batch)
```

## Rate Limiting

### Default Limits

| Operation | Limit | Notes |
|-----------|-------|-------|
| Upsert | 100 vectors/request | Configurable |
| Query | 10 top_k | Default |
| Fetch | 100 IDs/request | Maximum |
| Delete | 1000 IDs/request | Maximum |

---

**Related**: [README.md](https://www.heliosdb.com/docs/full/reference/protocols/pinecone/readme/) | [COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/pinecone/compatibility/) | [EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/pinecone/examples/)