Pinecone Vector Database Quick Start Guide

Get started with HeliosDB’s Pinecone-compatible vector API. Connect using your existing Pinecone client libraries with 100% REST API compatibility.

Prerequisites

HeliosDB server running (default vector API port: 8080)
Pinecone client library (Python, JavaScript, or Go)
Basic familiarity with vector embeddings and similarity search

Connection Details

Parameter	Default Value
Host	`localhost`
Port	`8080`
Protocol	REST/HTTP
Authentication	API Key (Header: `Api-Key`)

5-Minute Getting Started

Step 1: Connect with Python Client

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key", host="http://localhost:8080")
index = pc.Index("my-vectors")

Step 2: Upsert Vectors

index.upsert(vectors=[
    {"id": "vec1", "values": [0.1, 0.2, 0.3, 0.4, 0.5], "metadata": {"category": "electronics"}},
    {"id": "vec2", "values": [0.5, 0.4, 0.3, 0.2, 0.1], "metadata": {"category": "books"}}
])

Step 3: Query Similar Vectors

results = index.query(vector=[0.1, 0.2, 0.3, 0.4, 0.5], top_k=10, include_metadata=True)
for match in results.matches:
    print(f"ID: {match.id}, Score: {match.score}")

Client Library Examples

Python SDK

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key", host="http://localhost:8080")
index = pc.Index("embeddings")

# Check index statistics
stats = index.describe_index_stats()
print(f"Total vectors: {stats.total_vector_count}")

JavaScript/Node.js SDK

const { Pinecone } = require('@pinecone-database/pinecone');

const pc = new Pinecone({ apiKey: 'your-api-key', environment: 'localhost:8080' });
const index = pc.index('embeddings');

// Upsert and query
await index.upsert([
    { id: 'vec1', values: [0.1, 0.2, 0.3, 0.4, 0.5], metadata: { category: 'A' } }
]);
const results = await index.query({ vector: [0.1, 0.2, 0.3, 0.4, 0.5], topK: 10 });

REST API (cURL)

# Upsert vectors
curl -X POST "http://localhost:8080/vectors/v1/upsert" \
  -H "Api-Key: your-api-key" -H "Content-Type: application/json" \
  -d '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"category": "A"}}]}'

# Query vectors
curl -X POST "http://localhost:8080/vectors/v1/query" \
  -H "Api-Key: your-api-key" -H "Content-Type: application/json" \
  -d '{"vector": [0.1, 0.2, 0.3], "topK": 10, "includeMetadata": true}'

Creating Indexes (Namespaces)

# Create a new index
pc.create_index(name="my-vectors", dimension=1536, metric="cosine")  # cosine, euclidean, dotproduct

# List and delete indexes
indexes = pc.list_indexes()
pc.delete_index("old-index")

Working with Namespaces

# Upsert to specific namespace
index.upsert(vectors=[{"id": "prod_1", "values": [...]}], namespace="production")

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

# Delete namespace
index.delete(delete_all=True, namespace="testing")

Upserting Vectors

Single and Batch Upsert

# Single vector with metadata
index.upsert(vectors=[{
    "id": "vec1",
    "values": [0.1, 0.2, 0.3, 0.4, 0.5],
    "metadata": {"category": "electronics", "price": 99.99, "in_stock": True}
}])

# Batch upsert (max 100 per request)
vectors = [{"id": f"vec_{i}", "values": [...], "metadata": {...}} for i in range(1000)]
index.upsert(vectors=vectors, batch_size=100)

Fetch and Delete

# Fetch by ID
result = index.fetch(ids=["vec_1", "vec_2", "vec_3"])

# Delete by ID or filter
index.delete(ids=["vec_1", "vec_2"])
index.delete(filter={"category": {"$eq": "deprecated"}})

Querying Vectors (Similarity Search)

Basic Query

results = index.query(
    vector=[0.1, 0.2, 0.3, ...],
    top_k=10,
    include_metadata=True,
    include_values=True
)

for match in results.matches:
    print(f"ID: {match.id}, Score: {match.score}, Metadata: {match.metadata}")

Query with Filters

results = index.query(
    vector=[...],
    top_k=10,
    filter={"category": {"$eq": "electronics"}, "price": {"$lt": 100}}
)

Metadata Filtering

Filter Operators

Operator	Description	Example
`$eq`	Equal	`{"status": {"$eq": "active"}}`
`$ne`	Not equal	`{"status": {"$ne": "deleted"}}`
`$gt` / `$gte`	Greater than (or equal)	`{"price": {"$gt": 50}}`
`$lt` / `$lte`	Less than (or equal)	`{"price": {"$lt": 100}}`
`$in` / `$nin`	In / not in array	`{"category": {"$in": ["A", "B"]}}`
`$exists`	Field exists	`{"discount": {"$exists": true}}`

Complex Filters (AND/OR)

# AND filter
results = index.query(vector=[...], filter={
    "$and": [
        {"category": {"$eq": "electronics"}},
        {"price": {"$gte": 50}},
        {"in_stock": {"$eq": True}}
    ]
})

# OR filter
results = index.query(vector=[...], filter={
    "$or": [
        {"category": {"$eq": "electronics"}},
        {"category": {"$eq": "computers"}}
    ]
})

Hybrid Search (Sparse + Dense)

# Upsert with sparse vectors
index.upsert(vectors=[{
    "id": "doc1",
    "values": [0.1, 0.2, ...],  # Dense embedding
    "sparse_values": {"indices": [15, 42, 156], "values": [0.8, 0.5, 0.3]},
    "metadata": {"title": "ML Guide"}
}])

# Query with both dense and sparse
results = index.query(
    vector=[0.1, 0.2, ...],
    sparse_vector={"indices": [15, 42], "values": [0.9, 0.5]},
    top_k=10
)

Migration from Pinecone to HeliosDB

Step 1: Export from Pinecone

from pinecone import Pinecone

pinecone_client = Pinecone(api_key="pinecone-api-key")
source_index = pinecone_client.Index("source-index")

# Fetch all IDs and vectors
all_ids = list(source_index.list())
all_vectors = []
for i in range(0, len(all_ids), 100):
    result = source_index.fetch(ids=all_ids[i:i+100])
    for id, vec in result.vectors.items():
        all_vectors.append({"id": id, "values": vec.values, "metadata": vec.metadata})

Step 2: Import to HeliosDB

helios_client = Pinecone(api_key="heliosdb-api-key", host="http://localhost:8080")
target_index = helios_client.Index("target-index")
target_index.upsert(vectors=all_vectors, batch_size=100)

Migration Notes

Aspect	Notes
Index Configuration	Recreate with same dimension and metric
Namespaces	Migrate each namespace separately
Metadata	Fully supported (up to 40KB per vector)

Troubleshooting

Common Errors

Error	Cause	Solution
`401 Unauthorized`	Invalid API key	Verify API key in header
`404 Not Found`	Index does not exist	Create index first
`400 Bad Request`	Dimension mismatch	Ensure vector dimension matches index
`413 Payload Too Large`	Batch too large	Reduce batch size (max 100)

Test Connection

try:
    stats = index.describe_index_stats()
    print(f"Connected! Vectors: {stats.total_vector_count}, Dimension: {stats.dimension}")
except Exception as e:
    print(f"Connection failed: {e}")

Retry with Backoff

import time

def upsert_with_retry(index, vectors, max_retries=3):
    for attempt in range(max_retries):
        try:
            index.upsert(vectors=vectors)
            return True
        except Exception as e:
            if "429" in str(e):
                time.sleep(2 ** attempt)
            else:
                raise
    return False

API Compatibility Summary

Operation	Status	Notes
Upsert	100%	Batch operations supported
Query	100%	Top-K with filtering
Fetch	100%	By ID
Delete	100%	By ID or filter
Update	100%	Metadata and values
Namespaces	100%	Full support
Sparse Vectors	100%	Hybrid search

Next Steps

Pinecone Configuration - Connection settings
Pinecone Compatibility - Full API matrix
Pinecone Examples - Advanced patterns
Protocol Compatibility Matrix - Cross-protocol comparison

Last Updated: January 2026