Namespaces - Mixpeek

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

Create a Namespace

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"},
    ],
)

# Minimal — MVS infers vector configs on first write
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"}'

# Or pre-declare configs 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": "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):

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

curl -X PATCH "https://api.mixpeek.com/v1/namespaces/product-search" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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)

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

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)

curl -X PATCH "https://api.mixpeek.com/v1/namespaces/product-search" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload_indexes": [{"field_name": "category", "type": "keyword"}]}'

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

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.

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:

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"

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`

​Create a Namespace

​Parameters

​Text Indexes (BM25)

​Payload Indexes

​Adaptive Payload Indexes

​Index Suggestions

​Schema-on-Write

​Usage Metrics

​Other Operations

​Related

Create a Namespace

Parameters

Text Indexes (BM25)

Payload Indexes

Adaptive Payload Indexes

Index Suggestions

Schema-on-Write

Usage Metrics

Other Operations

Related