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

# Migrate from Pinecone

> Move from single-vector search to multi-stage warehouse retrieval

Pinecone is a vector database built for single-embedding KNN search. Mixpeek is a multimodal warehouse that decomposes files into searchable features, stores them across cost tiers, and reassembles answers through multi-stage retrieval pipelines.

This guide walks you through migrating your search workload from Pinecone to Mixpeek.

## Why Migrate

> [!NOTE]
>
> Pinecone stores and queries individual vectors. Mixpeek processes raw files end-to-end: extracting features, storing documents across tiered storage, and executing multi-stage retrieval pipelines. You stop managing embeddings and start working with content.

| Pinecone | Mixpeek |
| - | - |
| You generate embeddings externally | Feature extractors generate embeddings automatically |
| Single-vector KNN per query | Multi-stage pipelines: search, filter, rerank, enrich |
| Flat storage pricing | Tiered storage: hot (active), warm (cold), archive, up to 90% savings |
| Metadata filtering on vector results | Attribute filters, boolean logic, and cross-modal joins as pipeline stages |
| One index per embedding model | One namespace handles multiple modalities and models simultaneously |

## Concept Mapping

| Pinecone | Mixpeek | Notes |
| - | - | - |
| Index | Namespace | Top-level container for your data |
| Namespace | Namespace (via `X-Namespace` header) | Tenant or environment isolation within a namespace |
| Vector | Document (with features) | Documents contain extracted features, metadata, and lineage back to the source file |
| Upsert | Object upload + Collection processing | Data flows through the pipeline: upload to bucket, collection triggers extraction |
| Query (top-k KNN) | Retriever execution (multi-stage) | Retrievers chain stages: semantic search, filters, reranking, enrichment |
| Metadata filter | Attribute filter stage | Filters are composable stages in a retrieval pipeline |

## Migration Steps

**1. Create a Namespace**

Set up a namespace to hold your data. This replaces your Pinecone index.

```bash theme={null}
curl -X POST https://api.mixpeek.com/v1/namespaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_name": "product-catalog"
  }'
```

**2. Create a Collection with Feature Extractors**

Define what features to extract from your data. This replaces the external embedding step you had with Pinecone.

```bash theme={null}
curl -X POST https://api.mixpeek.com/v1/collections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: product-catalog" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "products",
    "source": { "type": "bucket", "bucket_ids": ["'$BUCKET_ID'"] },
    "feature_extractor": {
      "feature_extractor_name": "multimodal",
      "version": "v1"
    }
  }'
```

**3. Re-ingest Your Data Through the Pipeline**

Upload your source files to a bucket and let the collection process them. Do not try to import your existing Pinecone vectors directly. Mixpeek extracts richer, multi-modal features from your raw content.

> [!WARNING]
>
> Never insert vectors directly into the storage layer. All data must flow through the ingestion pipeline: bucket upload, collection trigger, feature extraction. This ensures proper lineage, validation, and multi-modal indexing.

```bash theme={null}
# Upload objects to a bucket
curl -X POST https://api.mixpeek.com/v1/buckets/{bucket_id}/objects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: product-catalog" \
  -H "Content-Type: application/json" \
  -d '{
    "key_prefix": "/products",
    "blobs": [
      { "property": "image", "type": "image", "data": "s3://your-bucket/product-001.jpg" },
      { "property": "description", "type": "text", "data": "s3://your-bucket/product-001.txt" }
    ]
  }'
```

**4. Create a Retriever with Multi-Stage Pipelines**

Build a retriever that goes beyond single-vector KNN. Chain semantic search with filters, reranking, and enrichment.

```bash theme={null}
curl -X POST https://api.mixpeek.com/v1/retrievers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: product-catalog" \
  -H "Content-Type: application/json" \
  -d '{
    "retriever_name": "product-search",
    "stages": [
      {
        "stage_name": "search",
        "stage_type": "filter",
        "config": {
          "stage_id": "feature_search",
          "parameters": {
            "final_top_k": 50,
            "searches": [
              {
                "feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
                "query": { "input_mode": "text", "value": "{{INPUT.query}}" },
                "top_k": 50
              }
            ]
          }
        }
      },
      {
        "stage_name": "filter_category",
        "stage_type": "filter",
        "config": {
          "stage_id": "attribute_filter",
          "parameters": {
            "field": "category",
            "operator": "eq",
            "value": "{{INPUT.category}}"
          }
        }
      },
      {
        "stage_name": "rerank",
        "stage_type": "sort",
        "config": {
          "stage_id": "rerank",
          "parameters": {
            "top_k": 10
          }
        }
      }
    ]
  }'
```

**5. Test and Verify**

Execute your retriever and compare results against your Pinecone baseline.

```bash theme={null}
curl -X POST https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Namespace: product-catalog" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query": "red running shoes",
      "category": "footwear"
    },
    "limit": 10
  }'
```

## Side-by-Side Comparison

> [!TIP]
>
> The Mixpeek retriever does in one API call what requires multiple steps with Pinecone: embedding generation, vector search, and post-processing.

```python Pinecone theme={null}
import pinecone
from sentence_transformers import SentenceTransformer

# You manage the embedding model
model = SentenceTransformer("all-MiniLM-L6-v2")

# You generate the embedding
query_embedding = model.encode("red running shoes").tolist()

# Single-vector KNN search
pinecone.init(api_key="PINECONE_KEY", environment="us-east-1")
index = pinecone.Index("product-catalog")

results = index.query(
    vector=query_embedding,
    top_k=10,
    filter={"category": "footwear"},
    include_metadata=True
)

for match in results["matches"]:
    print(match["id"], match["score"], match["metadata"])
```

```python Mixpeek theme={null}
from mixpeek import Mixpeek

client = Mixpeek(api_key="YOUR_API_KEY")

# One call: embedding, search, filter, rerank - all handled
results = client.retrievers.execute(
    retriever_id="product-search",
    inputs={
        "query": "red running shoes",
        "category": "footwear"
    },
    limit=10,
    namespace="product-catalog"
)

for doc in results:
    print(doc["document_id"], doc["score"], doc["metadata"])
```

## What You Gain

| Capability | Pinecone | Mixpeek |
| - | - | - |
| **Multi-stage retrieval** | Single KNN query; post-processing is your problem | Chain search, filter, rerank, and enrich stages in one pipeline |
| **Automatic feature extraction** | You build and maintain embedding pipelines | Feature extractors handle it: CLIP, Whisper, LayoutLM, and more |
| **Tiered storage** | All vectors at one price tier | Hot, cold, and archive tiers, up to 90% savings on infrequently accessed data |
| **Multimodal search** | One embedding model per index | Search across text, images, video, and audio in the same namespace |
| **No per-query vector fees** | Per-read pricing on every query | Flat API pricing, no per-vector-read charges |
| **Complete lineage** | Vectors disconnected from source files | Trace any result back through document, object, and source file |

## Next Steps

> [card] [Quickstart](https://docs.mixpeek.com/docs/overview/quickstart.md)
>
> Get Mixpeek running in 10 minutes

> [card] [Feature Extractors](https://docs.mixpeek.com/docs/processing/feature-extractors.md)
>
> Learn about automatic feature extraction

> [card] [Retrievers](https://docs.mixpeek.com/docs/retrieval/retrievers.md)
>
> Build multi-stage retrieval pipelines

> [card] [Core Concepts](https://docs.mixpeek.com/docs/overview/concepts.md)
>
> Understand the data model


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