Vector Store - Mixpeek

Bring your own embeddings, upsert them directly, and query with dense, sparse, BM25, or hybrid search. No collections or extractors required.

Create a vector namespace

Upsert your own embeddings and run a search in minutes, with no extractors or schema to declare. Creating a namespace needs a plan; see Billing for what each one covers.

Quickstart

Create a namespace

No schema needed. MVS infers vector dimensions on first write.

Pick a vector name of your own, like my_text_v1. A few short generic names (text_embedding among them) collide with legacy pre-namespace keys in the store, and a namespace that uses one accepts your writes with a 200 and then refuses every search with a 409 (a cross-namespace index refusal). Prefixing with your project or model version avoids it.

curl -X POST "https://api.mixpeek.com/v1/namespaces/standalone" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"namespace_id": "product-search"}'

from mixpeek import Mixpeek

client = Mixpeek(api_key="mxp_sk_...")

client.namespaces.create(
    namespace_id="product-search",
    mode="standalone",
)

const res = await fetch("https://api.mixpeek.com/v1/namespaces/standalone", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MIXPEEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ namespace_id: "product-search" }),
});
const data = await res.json();

You can optionally pre-declare vector configs if you want to set a specific distance metric:

curl -X POST "https://api.mixpeek.com/v1/namespaces/standalone" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_id": "product-search",
    "vector_configs": [
      {"name": "my_text_v1", "dimension": 1536, "metric": "dot"}
    ]
  }'

client.namespaces.create(
    namespace_id="product-search",
    mode="standalone",
    vector_configs=[
        {"name": "my_text_v1", "dimension": 1536, "metric": "dot"}
    ],
)

const res = await fetch("https://api.mixpeek.com/v1/namespaces/standalone", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MIXPEEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    namespace_id: "product-search",
    vector_configs: [
      { name: "my_text_v1", dimension: 1536, metric: "dot" },
    ],
  }),
});
const data = await res.json();

Upsert documents with your vectors

curl -X POST "https://api.mixpeek.com/v1/namespaces/product-search/documents/upsert" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "document_id": "prod-001",
      "vectors": {"my_text_v1": [0.12, -0.34, 0.56, "...1536 floats"]},
      "payload": {"title": "Wireless Headphones", "category": "audio", "price": 79.99}
    }]
  }'

client.namespaces.documents.upsert(
    namespace_id="product-search",
    documents=[{
        "document_id": "prod-001",
        "vectors": {"my_text_v1": [0.12, -0.34, 0.56]},  # 1536 floats
        "payload": {"title": "Wireless Headphones", "category": "audio", "price": 79.99},
    }],
)

const res = await fetch("https://api.mixpeek.com/v1/namespaces/product-search/documents/upsert", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MIXPEEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    documents: [{
      document_id: "prod-001",
      vectors: { my_text_v1: [0.12, -0.34, 0.56] }, // 1536 floats
      payload: { title: "Wireless Headphones", category: "audio", price: 79.99 },
    }],
  }),
});
const data = await res.json();

Create a retriever (one-time)

Querying is unified on retrievers: one query concept whether you bring your own vectors or promote to managed embedding. Create a retriever once; for a standalone namespace it takes the query vector you computed (input_mode: vector). All requests are scoped to the namespace via the X-Namespace header.

curl -X POST "https://api.mixpeek.com/v1/retrievers" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id" \
  -H "Content-Type: application/json" \
  -d '{
    "retriever_name": "product_search",
    "input_schema": {"query_vector": {"type": "array", "required": true}},
    "stages": [{
      "stage_name": "search",
      "stage_type": "filter",
      "config": {
        "stage_id": "feature_search",
        "pre_filters": {"AND": [{"field": "category", "operator": "eq", "value": "audio"}]},
        "parameters": {
          "searches": [{
            "feature_uri": "my_text_v1",
            "query": {"input_mode": "vector", "value": "{{INPUT.query_vector}}"},
            "top_k": 10
          }],
          "final_top_k": 10
        }
      }
    }]
  }'

retriever = client.retrievers.create(
    namespace_id="product-search",
    retriever_name="product_search",
    input_schema={"query_vector": {"type": "array", "required": True}},
    stages=[{
        "stage_name": "search",
        "stage_type": "filter",
        "pre_filters": {"AND": [{"field": "category", "operator": "eq", "value": "audio"}]},
        "config": {
            "stage_id": "feature_search",
            "parameters": {
                "searches": [{
                    "feature_uri": "my_text_v1",
                    "query": {"input_mode": "vector", "value": "{{INPUT.query_vector}}"},
                    "top_k": 10,
                }],
                "final_top_k": 10,
            },
        },
    }],
)

const res = await fetch("https://api.mixpeek.com/v1/retrievers", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MIXPEEK_API_KEY}`,
    "X-Namespace": "ns_your_namespace_id",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    retriever_name: "product_search",
    input_schema: { query_vector: { type: "array", required: true } },
    stages: [{
      stage_name: "search",
      stage_type: "filter",
      config: {
        stage_id: "feature_search",
        pre_filters: { AND: [{ field: "category", operator: "eq", value: "audio" }] },
        parameters: {
          searches: [{
            feature_uri: "my_text_v1",
            query: { input_mode: "vector", value: "{{INPUT.query_vector}}" },
            top_k: 10,
          }],
          final_top_k: 10,
        },
      },
    }],
  }),
});
const retriever = await res.json();

Execute the retriever

Run the retriever with your query embedding. Each hit exposes document_id and payload fields.

curl -X POST "https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query_vector": [0.15, -0.28, 0.44, "...query embedding"]}
  }'

results = client.retrievers.execute(
    namespace_id="product-search",
    retriever_id=retriever.retriever_id,
    inputs={"query_vector": [0.15, -0.28, 0.44]},  # query embedding
)

const res = await fetch("https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MIXPEEK_API_KEY}`,
    "X-Namespace": "ns_your_namespace_id",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: { query_vector: [0.15, -0.28, 0.44] }, // query embedding
  }),
});
const data = await res.json();
console.log(data.documents);

Architecture

Scaling

The index auto-partitions as you grow. There’s no capacity planning, resharding, or replica provisioning on your side, and no per-vector or per-namespace caps. The same namespace serves thousands or hundreds of millions of vectors. At large scale (10M–100M+ vectors), two things matter:

Tiering. Hot (in-memory) vectors serve at ~10ms; cold (object-storage) vectors serve at ~100ms via brute-force scan. The vector store keeps your actively-queried set resident automatically, so there’s no manual tier management on your side.
Shard visibility. The shards.hot / shards.cold counts in namespace usage metrics show how the index has partitioned. Dedicated/enterprise deployments can tune shard and index parameters (see Single-Tenant).

Need concrete latency/recall targets for a specific corpus size and query rate? Talk to engineers. Sizing depends on dimensions, filter selectivity, and your hot/cold split.

Standalone vs Managed

Every namespace runs in one of two modes. Start standalone and promote when you’re ready, with no reindexing.

	Standalone	Managed
Query latency	Lower (no embedding at query time)	+50-200ms for auto-embedding
Embedding cost	You pay your provider directly	Included in platform pricing
Model flexibility	Any model, any fine-tune	Bound to registered inference services
Write path	Direct upsert only	Collections auto-process + direct upsert
Search input	Pre-computed vectors, text (BM25), sparse	Also accepts raw text/URLs (auto-embedded)
Feature URIs	Plain feature names only (e.g. `my_text_v1`); `mixpeek://…` extractor-backed URIs are not available	Full `mixpeek://<extractor>@<version>/<model>` URIs
Best for	Existing ML infra, low-latency, custom models	End-to-end processing, file pipelines

Start standalone if you already have embeddings. Promotion is additive: all existing data is preserved.

Features

All features work identically in standalone and managed modes.

Capability	Description
Dense search	Vector similarity with cosine, dot product, or euclidean distance
Sparse search	Sparse vector queries for learned sparse representations (SPLADE, etc.)
BM25 keyword search	Full-text search on payload fields via text indexes
Hybrid search	Combine dense + BM25 + sparse in one query with RRF or DBSF fusion
Metadata filtering	Filter on any payload field and combine with any search type
Payload indexes	Manual or adaptive, auto-created based on query patterns
Schema-on-write	Auto-create vector indexes on first upsert, with no upfront declaration needed
Usage metrics	Per-namespace breakdowns of vectors, queries, and writes
Namespace cloning	Clone namespaces for testing or environment branching

Billing

MVS pricing is pure usage-based, with no per-vector caps and no namespace limits. Tiers gate support level, not features.

Resource	Price
Vectors stored	$1.56 / 1M vectors / month
Storage	$0.08 / GB / month
Hot cache	$25 / GB / month
Queries	$2 / 1M queries
Writes	$2 / 1M writes

Tier minimums and what each one includes live on one page: Billing. All search features (dense, sparse, BM25, hybrid, adaptive indexes) are available on every tier. See the pricing calculator for cost estimates at scale. Track usage programmatically with the vector-backend usage endpoint (GET /v1/organizations/billing/usage/vector-backend) or view it in the Studio dashboard under Billing.

Next Steps

Namespaces

Vector indexes, metrics, BM25

Documents & Search

Upsert, query, manage

Promote

Standalone → managed

Ready to go beyond BYO vectors? Promote your standalone namespace to managed mode and add automatic embedding, file processing pipelines, and enrichment without reindexing. Your retrievers keep working unchanged: after promotion, the same retriever can auto-embed raw text instead of taking a pre-computed vector. See the migration guide for details. Learn how to promote →