# Rebuild Index (Vector / Elasticsearch)

This is part of [**RAG & Knowledge Base Operations**](https://docs.unique.ai/administrators/knowledge-base-for-admins/rag-knowledge-base-operations) — read the hub for the shared framework (permissions, monitoring, dry run, safety, resilience). This runbook covers the `REBUILD_INDEX` specifics.

## Overview

Rebuild Index re-creates a company's **search index(es) from existing data** — the **vector (Qdrant) collection** and/or the **Elasticsearch full-text index** — **without re-ingesting source files and without re-embedding**.

Use it to:

- Recover from index corruption or vector/keyword inconsistency.
- Apply new index settings / mappings.
- Re-create an index after an infrastructure change.

Rebuild Index does **not** change the embedding model — the Qdrant rebuild copies the existing vectors. For a model/dimension change use **Re-embedding**; to change shard count use **Re-sharding**.

## Targets

| `target` | What it rebuilds |
| --- | --- |
| `QDRANT` | The vector collection — copy → verify → swap |
| `ELASTICSEARCH` | The full-text index — re-index chunks from the live collection |
| `BOTH` | Qdrant first, then Elasticsearch |

## Phases

- **QDRANT / BOTH:**`qdrant:copying` → `qdrant:verifying` → `qdrant:swapping`
- **ELASTICSEARCH / BOTH:**`elasticsearch:rebuilding` → `elasticsearch:verifying`

(For `BOTH`, the Elasticsearch step indexes from the **post-swap** live collection.)

## Prerequisites

- **Choose the**`target` (`QDRANT`, `ELASTICSEARCH`, or `BOTH`).
- **Vector-DB capacity** for a second collection during the Qdrant rebuild (`QDRANT` / `BOTH`).
- **Dry run first.**
- Permissions, monitoring, lock, and resilience: see the hub.

## Run it

**Dry run (preview):**  
```graphql
mutation {
  createMaintenanceJob(input: {
    operationType: "REBUILD_INDEX"
    target: "BOTH"
    dryRun: true
  }) { id status }
}
```

**Execute:**  
```graphql
mutation {
  createMaintenanceJob(input: {
    operationType: "REBUILD_INDEX"
    target: "BOTH"
    destructive: false
    dryRun: false
  }) { id status createdAt }
}
```

| Field | Required | Description |
| --- | --- | --- |
| `operationType` | ✅ | `"REBUILD_INDEX"` |
| `target` | ✅ | `"QDRANT"`, `"ELASTICSEARCH"`, or `"BOTH"` |
| `destructive` | ➖ (default `false`) | `false` = keep the source until the rebuild is durable ( **recommended**). `true` = delete up front (no rollback). |
| `dryRun` | ➖ (default `false`) | `true` = preview only |

## Monitor

`phase` reflects the active sub-step (e.g. `qdrant:copying`, `elasticsearch:rebuilding`); `processed` / `total` track items rebuilt. See the hub for the `maintenanceJob` query, statuses, and `cancelMaintenanceJob`.

## Safety & rollback

- **Non-destructive by default** — the live index keeps serving until the atomic swap (Qdrant) / verified re-index (Elasticsearch).
- Vectors and chunks are **rebuilt from existing data** (no model change), so results are equivalent after the rebuild.
- For `BOTH`, Qdrant is rebuilt and swapped **before** Elasticsearch re-indexes, so the keyword index is rebuilt against the new live collection.

## Troubleshooting

| Symptom | Cause | Resolution |
| --- | --- | --- |
| Fails in `qdrant:copying` / capacity errors | Vector DB lacks room for a second collection | Free space / scale the cluster, then re-run |
| Fails in `*:verifying` (count mismatch) | Rebuilt index didn't receive all items | Re-run; if it recurs, check the target store's health |
| Elasticsearch step errors | ES cluster health / mapping issues | Check ES health; verify index settings/mappings |
| Transient connection errors | Network / keep-alive blips | Retried automatically (see hub) |