Namespaces

Create standalone namespaces with vector indexes, distance metrics, BM25, and payload indexes

A namespace is the isolation boundary for your vectors, documents, and indexes.

Create a Namespace

Python

from mixpeek import Mixpeek

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

# Minimal — MVS infers vector configs on first write
client.namespaces.create(
    namespace_id="product-search",
)

# Or pre-declare configs to set a specific distance metric
client.namespaces.create(
    namespace_id="product-search",
    vector_configs=[
        {"name": "text_embedding", "dimension": 1536, "metric": "cosine"},
        {"name": "image_embedding", "dimension": 512, "metric": "dot"},
    ],
)

Parameters

namespace_id · string · required

Unique identifier. Lowercase with hyphens (e.g., product-search).

mode · string · required

Must be "standalone".

vector_configs · array

Optional. Pre-declare named vector indexes with specific dimensions and distance metrics. If omitted, MVS uses schema-on-write — vector indexes are created automatically on first upsert with inferred dimensions and cosine metric.

Field	Type	Description
name	string	Index name (e.g., text_embedding)
dimension	integer	Must match your model’s output dimension
metric	string	cosine (default), dot, or euclidean

Documents can include vectors for any subset of indexes — not every index needs a vector in every document. When you upsert a document with a new vector name that hasn’t been seen before, MVS creates a new vector index automatically.

Text Indexes (BM25)

Full-text keyword search runs on payload indexes of type text. You declare indexes with payload_indexes, then register them in the store with ensure-indexes — which also backfills existing documents with no re-ingestion or re-embedding.

Step 1 — Declare a text index (on an existing namespace, patch payload_indexes):

Python

requests.patch(f"{BASE}/namespaces/product-search", headers=headers, json={
    "payload_indexes": [
        {"field_name": "title", "type": "text"},
        {"field_name": "description", "type": "text"}
    ]
})

Step 2 — Register and backfill (idempotent, zero re-extraction):

Python

requests.post(f"{BASE}/namespaces/product-search/ensure-indexes", headers=headers)

Pass ?force_rebuild=true to drop and rebuild an index from the full store — use this to repair a text/BM25 index that registered empty (e.g. during a cold start).

BM25 matches across all text-indexed string fields, not a single field. Once a text index exists, run keyword search in a retriever with the lexical option on Feature Search — and fuse it with a dense vector search under rrf for hybrid retrieval.

Payload Indexes

Speed up filtered searches by indexing frequently queried fields. Payload indexes use the same payload_indexes declaration + ensure-indexes flow as text indexes above — just pick the matching type:

Python

requests.patch(f"{BASE}/namespaces/product-search", headers=headers, json={
    "payload_indexes": [{"field_name": "category", "type": "keyword"}]
})
requests.post(f"{BASE}/namespaces/product-search/ensure-indexes", headers=headers)

Types: keyword, integer, float, bool, datetime, geo, text, uuid. Use dot notation for nested fields (e.g. metadata.title). Arrays are indexed element-wise — index a multi-value field with its element type (objects: ["car", "person"] → keyword) and a filter matches if any element matches.

PATCH merges, PUT replaces. A PATCH is additive: send only the fields you’re adding and every existing index is kept. Use PUT when you want the body to be the complete list — any user index you omit there is dropped.

You can also GET the namespace, append to payload_indexes, and PATCH the whole thing back. The protected system entries in that response are ignored on input, so you don’t need to strip them first.

Adaptive Payload Indexes

MVS monitors your query patterns and automatically creates payload indexes when a field appears in filters frequently enough. By default, any field used in >10 queries/hour gets auto-indexed — no manual action needed.

Setting	Default	Description
auto_create_payload_indexes	true	Auto-create payload indexes when filter threshold is hit
filter_threshold	10 queries/hour	How many filter queries before auto-indexing
auto_create_text_indexes	false	BM25 indexes are heavier — suggest-only by default
check_interval_s	600 (10 min)	How often the advisor checks query patterns

Control this with the MVS_AUTO_INDEX environment variable (true/false).

Index Suggestions

For fields that don’t yet meet the auto-create threshold, you can check what MVS recommends:

curl "https://api.mixpeek.com/v1/namespaces/product-search/index-suggestions" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY"

Returns recommended indexes based on filter frequency, field cardinality, and existing coverage.

Schema-on-Write

Unlike traditional vector databases that require declaring all vector indexes at creation time, MVS is schema-on-write. When you upsert a document with a new vector name, MVS automatically:

1. Infers the dimension from the first write
2. Creates a dense index with the detected dimension and cosine metric
3. Enforces schema on subsequent writes (mismatched dimensions raise an error)

This means you can add new embedding models to an existing namespace without reconfiguring anything — just start writing vectors with the new name.

Usage Metrics

Get detailed performance and usage metrics for a namespace via GET /v1/namespaces/{id}/usage.

curl "https://api.mixpeek.com/v1/namespaces/product-search/usage" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY"

Response

{
  "namespace_id": "product-search",
  "document_count": 125000,
  "vector_count": 250000,
  "storage_bytes": 1073741824,
  "index_count": 3,
  "queries_last_24h": 48200,
  "vectors": {"total": 250000, "by_name": {"text_embedding": 125000, "image_embedding": 125000}},
  "documents": {"total": 125000, "with_all_vectors": 120000, "partial": 5000},
  "storage": {
    "total_bytes": 1073741824,
    "by_tier": {"hot": 1073741824, "cold": 0, "archive": 0},
    "vector_bytes": 768000000,
    "payload_bytes": 32000000,
    "index_bytes": 16384000
  },
  "queries": {"last_24h": 48200, "last_7d": 312000, "last_30d": 1250000,
    "by_type": {"dense_search": 30000, "hybrid_search": 15000, "bm25_search": 3200}},
  "writes": {"last_24h": 5200, "last_7d": 35000, "last_30d": 142000},
  "shards": {"total": 4, "hot": 4, "cold": 0}
}

Key metrics:

Metric	Description
vectors.by_name	Vector count per named index — useful for checking partial coverage
queries.by_type	Breakdown by search type — informs cost optimization
shards.hot / shards.cold	Shard distribution across hot (in-memory) and cold (object-storage) partitions

These metrics feed into usage-based billing. You can also monitor namespace health via the observability dashboard.

Other Operations

Operation	Method	Endpoint
Get info	GET	/v1/namespaces/{id}
Delete	DELETE	/v1/namespaces/{id}
Clone	POST	/v1/namespaces/{id}/clone
Vector metadata	PUT	/v1/namespaces/{id}/vector-metadata

Related

• Documents & Search
• Promote to Managed
• Billing & Usage