Reindex a RAG workspace after many writes

After enough ragDeleteEmbeddings and re-ingest cycles, scores can drift. The index no longer reflects the source text. ragReindex({ workspace }) processes the stored text for that workspace and regenerates every embedding from scratch.

ragReindex runs k-means over the stored embeddings. K-means needs at least K samples to produce K centroids. HyperDB's NUM_CENTROIDS defaults to 4 and is not configurable through the SDK, so any workspace with fewer than 4 documents gets a no-op reindex with reason: "insufficient documents".

The reindex is idempotent: running it twice in a row is safe, the second run finds nothing to do.

The result is { reindexed, details }. reindexed: true means anything was rebuilt; false carries a reason you can log. The call is two lines:

const result = await ragReindex({ workspace });
console.log("Reindexed:", result.reindexed);
if (!result.reindexed) {
  console.log("Reason:", result.details?.reason ?? "unknown");
}

For this 4-recipe demo the reindex deliberately bails. The point of the lesson is to read the result and know what to do with it: in a real workspace with thousands of documents, this branch never fires, you just log the success and proceed with the updated embeddings.

Note: a reindex on a large workspace takes roughly the same time as the original ingest. Plan to run it during a quiet window or as a one-shot maintenance task.

Put it to the test

1. Call await ragReindex({ workspace }) and console.log result.reindexed plus the reason from result.details?.reason when it's false.