Skip to main content
A namespace is the isolation boundary for your vectors, documents, and indexes.

​
Create a Namespace

from mixpeek import Mixpeek

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

# 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.
FieldTypeDescription
namestringIndex name (e.g., text_embedding)
dimensionintegerMust match your model’s output dimension
metricstringcosine (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): 
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): 
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: 
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).

​
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.
SettingDefaultDescription
auto_create_payload_indexestrueAuto-create payload indexes when filter threshold is hit
filter_threshold10 queries/hourHow many filter queries before auto-indexing
auto_create_text_indexesfalseBM25 indexes are heavier — suggest-only by default
check_interval_s600 (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:
MetricDescription
vectors.by_nameVector count per named index — useful for checking partial coverage
storage.by_tierBytes across hot/cold/archive tiers
queries.by_typeBreakdown by search type — informs cost optimization
shards.hot / shards.coldShard distribution across tiers
These metrics feed into usage-based billing. You can also monitor namespace health via the observability dashboard.

​
Other Operations

OperationMethodEndpoint
Get infoGET/v1/namespaces/{id}
DeleteDELETE/v1/namespaces/{id}
ClonePOST/v1/namespaces/{id}/clone
Vector metadataPUT/v1/namespaces/{id}/vector-metadata