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
Unique identifier. Lowercase with hyphens (e.g., product-search).
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 |
Text Indexes (BM25)
Add full-text keyword search on payload fields. Existing documents are backfilled automatically.
requests.post(f"{BASE}/namespaces/product-search/text-indexes", headers=headers, json={
"fields": ["title", "description"],
"language": "english"
})
language (default "english"), strip_html (default false), min_token_length (default 2). For large namespaces, backfilling runs async — the response includes a batch_id to track progress.
Payload Indexes
Speed up filtered searches by indexing frequently queried payload fields.
requests.post(f"{BASE}/namespaces/product-search/payload-indexes", headers=headers, json={
"field_name": "category",
"field_type": "keyword"
})
keyword, integer, float, bool, datetime, geo.
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 |
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"
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:
- Infers the dimension from the first write
- Creates a dense index with the detected dimension and cosine metric
- 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"
{
"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}
}
| Metric | Description |
|---|
vectors.by_name | Vector count per named index — useful for checking partial coverage |
storage.by_tier | Bytes across hot/cold/archive tiers |
queries.by_type | Breakdown by search type — informs cost optimization |
shards.hot / shards.cold | Shard distribution across tiers |
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 |
