Skip to content
⚠️ Before You Start
Risk: Medium
Duration: Hours to days, depending on corpus and change size
Last Validated: Not yet validated (draft)
Kind: Runbook
Risk Note: Medium (a broken refresh gives stale or inconsistent entities; a full re-index can be costly)

Refresh the knowledge graph after corpus, prompt or version changes

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-12-08). Author: Deeparani · dry-run: Yogeshwaran · sign-off: Prasanna. Work items: RAG-11-T13, RAG-11-T14, RAG-11-T15, RAG-11-T16.

1. Summary

New or changed documents must reach the graph, extraction prompts change, or the GraphRAG library or model version changes.

Risk: Medium (a broken refresh gives stale or inconsistent entities; a full re-index can be costly). Typical duration: Hours to days, depending on corpus and change size.

2. When to use and when not to

Use it when: New or changed documents must reach the graph, extraction prompts change, or the GraphRAG library or model version changes.

Do not use it when: to be written by the author.

3. What you must know first

  • GraphRAG has an update command that computes deltas against an existing index and merges them
  • New content can change community structure, so much of the index may still be recomputed
  • graphrag init with --force overwrites configuration and prompts
  • Changing extraction prompts or models usually needs a full re-index for consistent entities
  • Keep the old graph serving until the new one is verified

4. Prerequisites and access

  • Snapshot of the graph store and GraphRAG output folders
  • Backup of settings and prompts, because init overwrites them
  • Approved token budget for the refresh
  • Golden question set for before-and-after checks

5. Steps

Outline of the steps; the author adds the commands and a check after each one.

  1. Snapshot the graph store and output folders, and back up settings and prompts.
  2. Classify the change: new content only, changed prompts, or a new library or model version.
  3. For new content only, run the incremental update in a staging copy.
  4. For prompt, model or major version changes, run a full re-index into a new output or database.
  5. Watch token usage against the budget during the run.
  6. Compare entity and relationship counts and run the golden questions on the new graph.
  7. Switch the application to the new graph through configuration.
  8. Keep the old graph for the watch window as the rollback.
  9. Delete the old graph and record the actual cost in the cost model.

Draft snippet: Incremental GraphRAG refresh into a staging copy

#!/usr/bin/env bash
# Incremental GraphRAG refresh into a staging copy, keeping the live output untouched.
set -euo pipefail
: "${LIVE_ROOT:?}" "${STAGE_ROOT:?}"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"

# 1. Snapshot settings, prompts and output before anything changes.
tar -czf "backup-graphrag-${STAMP}.tar.gz" -C "${LIVE_ROOT}" .

# 2. Build the staging copy from the live root and add the new documents.
rm -rf "${STAGE_ROOT}"
cp -a "${LIVE_ROOT}" "${STAGE_ROOT}"
cp -a new-documents/. "${STAGE_ROOT}/input/"

# 3. Run the incremental update. Check flags with 'graphrag update --help' for your pinned version.
graphrag update --root "${STAGE_ROOT}"

echo "Staging graph ready in ${STAGE_ROOT}. Run the golden questions before switching."

Snippets to add:

  • snippets/graphrag/refresh.sh: Incremental refresh into a staging copy (bash)
  • snippets/graphrag/compare_graphs.py: Compare entity and relationship counts between graphs (python)

6. Monitoring and alerts

Signal Alert when Action
Tokens used by the refresh job (Azure OpenAI metrics) Above the approved budget Stop the job and re-estimate.
Golden-question accuracy on the new graph More than 5 points below the current graph Do not switch; investigate the extraction changes.

7. Rollback

To be written by the author: how to undo each risky step.

8. Known issues and fixes

Symptom Likely cause Fix
Configuration lost after an upgrade init with --force overwrote settings and prompts Restore from backup and merge with the new defaults.
Entity counts jump or halve after refresh A prompt or model change altered extraction Treat it as a full re-index and review extraction samples by hand.
Refresh cost far above estimate The update recomputed most communities Batch content changes and refresh less often.

9. AWS and open-source equivalents

In Amazon Bedrock Knowledge Bases with Neptune Analytics, a data source sync processes S3 changes into the knowledge base and its graph; check current docs for what is rebuilt. With Neo4j, apply MERGE-based upserts and remove entities whose source chunks were deleted.

10. Validation record

Pending. Planned dry-run scenario: A second engineer adds 50 documents to a sandbox pilot and runs the incremental path, then makes a prompt change and runs the full path. Pass: both complete within budget, golden questions do not regress, and rollback to the old output works.

11. Sources