# Re-sharding a Collection

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 `RESHARD_COLLECTION` specifics.

## Overview

Re-sharding recreates a company's vector collection with a **different shard count** and atomically swaps the live collection to it. It **copies the existing vectors as-is** — there is **no re-embedding and no model change** — so it is faster than re-embedding but still scales with the number of points.

Use it to **scale a vector collection**: as a tenant's corpus grows, a higher shard count improves indexing/query parallelism and distributes the collection across the vector-DB cluster.

For an embedding-model or dimension change, use **Re-embedding**. To recover or re-create an index, use **Rebuild Index**. Re-sharding only changes the shard layout.

## Phases

`copying` → `verifying` → `swapping` → `cleanup`

It captures the source collection's layout (shard count, replication factor), creates a new collection with the **target shard count**, copies all points, verifies the point count matches the source, swaps the live collection, and removes the old one.

## Prerequisites

- **Target shard count decided.** Shard count scales with collection size and the number of vector-DB nodes — consult Unique on sizing if unsure.

- **Vector-DB capacity** for a second copy of the collection during the `copying` phase.

- **Dry run first** (estimates point count and shows the target shard count).

- Permissions, monitoring, lock, and resilience: see the hub.

## Run it

**Dry run (preview):**

```graphql
mutation {
  createMaintenanceJob(input: {
    operationType: "RESHARD_COLLECTION"
    shardNumber: 12
    dryRun: true
  }) { id status }
}
```

**Execute:**

```graphql
mutation {
  createMaintenanceJob(input: {
    operationType: "RESHARD_COLLECTION"
    shardNumber: 12
    destructive: false
    dryRun: false
  }) { id status createdAt }
}
```

| Field | Required | Description |
| --- | --- | --- |
| `operationType` | ✅ | `"RESHARD_COLLECTION"` |
| `shardNumber` | ✅ | Target shard count for the new collection |
| `destructive` | ➖ (default `false`) | `false` = keep the source until the swap is durable ( **recommended**). `true` = delete the source up front (no rollback). |
| `dryRun` | ➖ (default `false`) | `true` = preview only |

## Monitor

`phase` progresses `copying → verifying → swapping → cleanup`; `processed` / `total` track points copied. See the hub for the `maintenanceJob` query, statuses, and `cancelMaintenanceJob`.

## Safety & rollback

- **Non-destructive by default** — search keeps serving on the current collection until the atomic swap; a failure before the swap leaves users unaffected.

- Vectors are **copied unchanged** (same model/dimension), so search quality is identical after re-sharding.

- **Rollback** after completion: re-shard back to the previous shard count.

## Troubleshooting

| Symptom | Cause | Resolution |
| --- | --- | --- |
| Fails in `copying` with capacity errors | Vector DB lacks room for a second copy | Free space / scale the cluster, then re-run |
| Fails in `verifying` (count mismatch) | New collection didn't receive all points | Re-run; if it recurs, check vector-DB health and ingestion activity during the copy |
| Transient connection errors | Network/keep-alive blips | Retried automatically (see hub) |

This re-shards a **single company's collection** via the maintenance-jobs framework. It is distinct from **cluster-level Qdrant shard scaling** (an infrastructure operation with its own runbook).