---
title: "Pinecone Vector Protocol Documentation"
---

# Pinecone Vector Protocol Documentation

:::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.
:::

This directory contains consolidated documentation for HeliosDB's Pinecone vector database protocol support.

## Quick Start

Connect to HeliosDB using the Pinecone client:

```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")

# Upsert vectors
index.upsert(vectors=[
    {"id": "vec1", "values": [0.1, 0.2, 0.3, ...], "metadata": {"category": "A"}},
    {"id": "vec2", "values": [0.4, 0.5, 0.6, ...], "metadata": {"category": "B"}}
])

# Query similar vectors
results = index.query(vector=[0.1, 0.2, 0.3, ...], top_k=10)
```

## Contents

| File | Description |
|------|-------------|
| **README.md** | Overview and quick start (this file) |
| **CONFIGURATION.md** | Connection and API configuration |
| **COMPATIBILITY.md** | Pinecone API compatibility |
| **EXAMPLES.md** | Vector search examples |

## Feature Overview

### API Compatibility

| Operation | Result | Notes |
|-----------|--------|-------|
| Upsert | Supported | Batch operations |
| Query | Supported | Top-K search |
| Fetch | Supported | By ID |
| Delete | Supported | By ID or filter |
| Update | Supported | Metadata update |
| List | Supported | Pagination |
| Describe Index | Supported | Index stats |

### Vector Search Features

- **Similarity Metrics**: Cosine, Euclidean, Dot product
- **Filtering**: Metadata-based filtering
- **Namespaces**: Logical partitioning
- **Sparse Vectors**: Hybrid search support
- **Batching**: Bulk operations

## Connection Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `host` | localhost | Server hostname |
| `port` | 8080 | Vector API port |
| `api_key` | - | API authentication |
| `index` | - | Index name |

## Use Cases

- **Semantic Search**: Natural language queries
- **Recommendations**: Similar item lookup
- **Image Search**: Visual similarity
- **RAG Applications**: Retrieval-augmented generation
- **Anomaly Detection**: Outlier identification

## Related Documentation

- **[CONFIGURATION.md](https://www.heliosdb.com/docs/full/reference/protocols/pinecone/configuration/)** - API configuration
- **[COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/pinecone/compatibility/)** - API compatibility
- **[EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/pinecone/examples/)** - Usage examples
- **[Parent Directory](https://www.heliosdb.com/docs/full/reference/protocols/readme/)** - Protocol overview