> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```python Python theme={null}
  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"},
      ],
  )
  ```

  ```bash cURL theme={null}
  # 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"}
      ]
    }'
  ```
</CodeGroup>

### Parameters

<ParamField path="namespace_id" type="string" required>
  Unique identifier. Lowercase with hyphens (e.g., `product-search`).
</ParamField>

<ParamField path="mode" type="string" required>
  Must be `"standalone"`.
</ParamField>

<ParamField path="vector_configs" type="array">
  Optional. Pre-declare named vector indexes with specific dimensions and distance metrics. If omitted, MVS uses [schema-on-write](#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` |
</ParamField>

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`):

<CodeGroup>
  ```python Python theme={null}
  requests.patch(f"{BASE}/namespaces/product-search", headers=headers, json={
      "payload_indexes": [
          {"field_name": "title", "type": "text"},
          {"field_name": "description", "type": "text"}
      ]
  })
  ```

  ```bash cURL theme={null}
  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"}
        ]}'
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  requests.post(f"{BASE}/namespaces/product-search/ensure-indexes", headers=headers)
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.mixpeek.com/v1/namespaces/product-search/ensure-indexes" \
    -H "Authorization: Bearer $MIXPEEK_API_KEY"
  ```
</CodeGroup>

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).

<Note>
  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](/retrieval/stages/feature-search#lexical-bm25-search) — and fuse it with a dense vector search under `rrf` for hybrid retrieval.
</Note>

## 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`:

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

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:

```bash theme={null}
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`.

```bash theme={null}
curl "https://api.mixpeek.com/v1/namespaces/product-search/usage" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY"
```

```json title="Response" theme={null}
{
  "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](/best-practices/cost-optimization) |
| `shards.hot` / `shards.cold` | Shard distribution across hot (in-memory) and cold (object-storage) partitions            |

These metrics feed into [usage-based billing](/platform/billing). You can also monitor namespace health via the [observability dashboard](/operations/observability).

## 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](/vector-store/documents)
* [Promote to Managed](/vector-store/promote)
* [Billing & Usage](/platform/billing)