Incremental Updates

Once a graph has been ingested, real corpora keep changing: documents get edited, replaced, or removed. Re-running a full ingest on every change is expensive and discards the existing graph. The v1.1.0 incremental update primitives let you mutate an already-built graph in place, with crash-safe semantics and scoped orphan cleanup. This page is the API reference and usage guide for those primitives:

update() — re-sync a single document
delete_document() — remove a single document and its orphans
apply_changes() — heterogeneous batch (added / modified / deleted)
finalize() — run once at the end of a batch

The canonical use case is CI-driven graph updates on PR merge: a typical diff has all three change types in one go, and apply_changes() routes each list to the right primitive.

Mental Model — What Lives in the Graph

To understand the effect of each primitive, it helps to know the node shapes the lexical graph keeps:

Label	Purpose
`Document`	One per ingested source. Carries `content_hash`, `path`, and metadata.
`Chunk`	Linked to its `Document` via `PART_OF`. Holds embeddings.
`__Entity__`	Extracted entities. Linked to chunks via `MENTIONED_IN`.
`RELATES` (edge)	Fact between two entities. Carries `source_chunk_ids` for provenance.

Incremental updates are scoped via these relationships — orphan cleanup never goes global, it only inspects entities the touched document actually referenced.

`update()`

Re-sync a previously-ingested document. The new content replaces the old chunks, entities are re-extracted, and entities that become orphaned (no remaining MENTIONED_IN edges) are cleaned up along with their incident RELATES edges.

result = await rag.update(
    source=None,                    # OR text=...
    text=None,
    document_id=None,
    loader=None,
    chunker=None,
    extractor=None,
    resolver=None,
    cache_unchanged_chunks=False,
    if_missing="error",             # "error" | "ingest"
    force=False,
    ctx=None,
)

Parameters

Argument	Meaning
`source`	File path. Mutually exclusive with `text`. In file mode, `document_id` defaults to the normalised path (a URI source is used verbatim) — the same id `ingest(source)` derives.
`text`	Raw text. Skips the loader. Requires an explicit `document_id`.
`document_id`	Stable id of the `Document` node to update. Required for text mode.
`loader` / `chunker` / `extractor` / `resolver`	Per-call strategy overrides, identical to `ingest()`.
`cache_unchanged_chunks`	`False` (default) extracts every chunk again. `True` copies what the graph already holds for a chunk whose text is unchanged, so only changed chunks pay for extraction, and its entities keep their summaries (the new edge says exactly what the old one did). A chunk whose edges an earlier SDK version wrote is extracted again either way, so its new edge records what it says. The graph is the cache: an entity deleted by hand is not brought back, and a changed ontology, prompt or model does not reach unchanged chunks. Counts are in `metadata["cache_stats"]`.
`if_missing`	`"error"` (default) raises `DocumentNotFoundError` if the id is unknown. `"ingest"` falls through to a fresh `ingest()` — upsert semantics.
`force`	`False` (default) returns `no_op=True` when the content hash is unchanged. `True` re-extracts anyway — the way to apply a new ontology, chunker or extractor to existing text, since `ingest()` also skips unchanged documents.

Returns — `UpdateResult`

UpdateResult(
    document_info: DocumentInfo,
    nodes_created: int,
    relationships_created: int,
    chunks_indexed: int,            # new chunks written
    chunks_deleted: int,            # old chunks removed
    entities_deleted: int,          # orphan entities pruned
    no_op: bool,                    # True if content_hash matched
    replaced_existing: bool,        # False if if_missing="ingest" upserted
    metadata: dict[str, Any],
)

Effect on the graph

Scenario	What changes
Content hash matches (touch-only edit)	Nothing. SHA-256 short-circuits the call to a single Cypher lookup. `no_op=True`. Use this for CRLF/formatter-only PRs. Pass `force=True` to re-extract regardless.
Real content change	New chunks written under a pending Document, then atomically cut over to the canonical id. Old chunks are deleted. Entities previously mentioned only by this document are removed.
Entity still referenced by another doc	Preserved. Orphan cleanup is scoped to candidates from this document — never global.
`RELATES` edge sourced only from old chunks	Removed as a stale fact (cleanup keyed on `source_chunk_ids`).
`if_missing="ingest"` and id unknown	Behaves like a fresh `ingest()`. `replaced_existing=False`.

Crash safety

The call uses a six-phase state machine with one load-bearing commit point (mark_pending_committed). Crashes before the commit roll back (pending data is discarded); crashes after the commit roll forward (cleanup resumes on the next call to update/delete_document against this id).

Example

# Initial ingest with a stable id
await rag.ingest(text=V1_TEXT, document_id="alice_bio")

# Touch-only — short-circuits via content hash
result = await rag.update(text=V1_TEXT, document_id="alice_bio")
assert result.no_op is True

# Real edit — replaces chunks, prunes orphans
result = await rag.update(text=V2_TEXT, document_id="alice_bio")
print(f"replaced {result.chunks_deleted} chunks, "
      f"removed {result.entities_deleted} orphan entities, "
      f"wrote {result.chunks_indexed} new chunks")

`delete_document()`

Remove a single document and everything it uniquely owns.

result = await rag.delete_document(
    document_id: str,
    *,
    if_missing="error",             # "error" | "ignore"
)

Parameters

Argument	Meaning
`document_id`	The Document node id (the normalised path for file-mode ingests; `text-<16hex>` for text-mode ingests without an explicit id).
`if_missing`	`"error"` (default) raises `DocumentNotFoundError`. `"ignore"` returns an empty result with zero counts — useful for CI deletes when the caller doesn’t track which files were ever ingested.

Returns — `DeleteDocumentResult`

DeleteDocumentResult(
    document_uid: str,
    chunks_deleted: int,
    entities_deleted: int,
)

Effect on the graph

What is removed	Notes
All `Chunk` nodes linked to the Document via `PART_OF`	Unconditional — the chunks belong only to this Document.
The `Document` node itself	Removed last, after cleanup completes.
`__Entity__` nodes that the doc referenced and have no remaining `MENTIONED_IN`	Scoped to candidates from this document; entities still cited elsewhere are kept.
`RELATES` edges whose `source_chunk_ids` are entirely from this Document’s chunks	Stale-fact cleanup. Edges with multi-document provenance survive.

The surviving entities’ descriptions are rewritten: what this document’s chunks said about them is taken off, unless another chunk still says it (no LLM call). A summarised entity cannot have text taken out of its summary: when the removed text is no longer said by any remaining edge, it is rebuilt from its remaining MENTIONED_IN edges if every one of them was written by this version (said_version; a table row’s edge does not count), and otherwise its summary is kept and the removed text beside it is still dropped. An unchanged chunk keeps its entities’ summaries for sure only with cache_unchanged_chunks=True; without it the chunk is extracted again, and a summary is kept only if the model describes the entity in the same words. An entity still holding more than five descriptions is summarised by the next finalize(). update() does the same for the chunks a new version replaces. Text a document ingested by an earlier SDK version wrote cannot be told apart, and is kept.

Crash safety

A single atomic write (pending_delete=true + cleanup-state arrays on the doc) is the commit marker. Before that write the live document is untouched. After it, every remaining step is idempotent and resumes on the next call against this id.

Example

await rag.delete_document("alice_bio")

# Idempotent cleanup of files removed in a PR — never errors if unknown
await rag.delete_document("some/path.md", if_missing="ignore")

`apply_changes()`

Heterogeneous batch — the convenience wrapper for CI-driven incremental ingestion. Dispatches each list to the right primitive in a fixed order:

deleted → delete_document()
modified → update(if_missing="ingest") (so a “modified” file the graph has never seen is upserted, not errored)
added → ingest()

result = await rag.apply_changes(
    *,
    added=None,
    modified=None,
    deleted=None,
    loader=None,
    chunker=None,
    extractor=None,
    resolver=None,
    max_concurrency=3,              # for `added`
    update_concurrency=1,           # for `modified` — see warning below
    ctx=None,
)

Parameters

Argument	Meaning
`added`	New file paths to ingest.
`modified`	File paths whose content changed.
`deleted`	Document ids (typically file paths) to remove.
`loader` / `chunker` / `extractor` / `resolver`	Strategy overrides forwarded to the add/update path. Ignored for deletes.
`max_concurrency`	Parallelism cap for `ingest()` of the `added` list. Safe to raise — adds have no orphan-cleanup race surface.
`update_concurrency`	Default 1, and you almost certainly should not raise it. The orphan-cleanup invariant only holds while updates serialize. See Concurrency below.

The order deletes → updates → adds is part of the public contract; do not assume reordering is safe. Relationship tables (a RelationshipMapping in the ontology) in added or modified run after all of it, modified first, because their endpoints resolve against nodes the entity tables in the same batch write. A git diff that lists consumed_batch.csv before unit.csv still writes every edge, and each entry keeps its position in the result. Overlapping ids across input lists raise ValueError at the input boundary — this is almost always a broken git-diff parser.

Returns — `ApplyChangesResult`

ApplyChangesResult(
    added:    list[BatchEntry[IngestionResult]],
    modified: list[BatchEntry[UpdateResult]],
    deleted:  list[BatchEntry[DeleteDocumentResult]],
)

Each entry aligns by index with the corresponding input list. Per-file errors are wrapped as BatchEntry with error (string) and error_type (exception class name) set; the batch never raises. Branch on entry.is_success:

for entry in result.modified:
    if entry.is_success:
        ...   # entry.result is an UpdateResult
    elif entry.error_type == "DocumentNotFoundError":
        ...

Effect on the graph

apply_changes() does not itself touch the graph — it dispatches to the primitives documented above and aggregates their results. Two whole-batch consequences worth knowing:

No automatic finalize(). Call finalize() once after the batch, not once per file. Its dedup checks only the entities whose check is pending — the ones the batch added, which have no name vector yet, and any an earlier run left pending — so one call covers the whole batch and a second call with nothing pending does no dedup work (an entity whose check did not complete stays pending and is retried). update() and deletes may run while finalize() deduplicates; a merge whose entities they change is skipped and decided again on the next run.
Peak entity cardinality is minimised because deletes run first — orphan candidates are gone before adds can re-introduce overlapping ids.

Canonical CI usage

async with GraphRAG(connection=..., llm=..., embedder=...) as rag:
    await rag.apply_changes(**parse_git_diff(pr_sha, base_sha))
    await rag.finalize()

Concurrency and the `update_concurrency` trap

Raising update_concurrency above 1 is unsafe in general because the orphan-cleanup correctness proof relies on MENTIONED_IN edges being persisted before any cutover begins. Two concurrent updates sharing an entity e1 are only guaranteed to preserve it because:

Pre-cutover, e1 still has its old MENTIONED_IN edges.
Post-pipeline.run() (but pre-cutover), the new MENTIONED_IN edges are already written.

So an update doing orphan cleanup will always see at least one incident edge. Raising the default to ≥2 is only safe if you can independently guarantee that no two parallel updates can share an entity in their candidate snapshots. The integration test test_concurrent_updates_preserve_shared_entity is the tripwire for this invariant — break it before bumping the value.

`finalize()`

Run once after a batch of ingests/updates/deletes. Skipping it leaves cross-document duplicates in place and disables entity-/edge-level vector search.

result = await rag.finalize()

Returns — `FinalizeResult`

FinalizeResult(
    null_stubs_removed:     int,
    entities_deduplicated:  int,
    judge_calls:            int,
    judge_stats:            dict[str, int | str],
    descriptions_summarised:      int,
    description_summary_failures: list[str],
    entities_embedded:      int,
    relationships_embedded: int,
    indexes:                dict[str, bool],
    # plus the report lists: probable_duplicates, unmerged_name_collisions,
    # property_conflicts, ... — see the API reference
)

What it does (in order)

Removes NULL-name stub entities (legacy cleanup).
deduplicate_entities() — incremental: the pending entities (added since the last finalize(), or left pending by it) are checked against the whole graph (exact-name and acronym match, then one judge pass over their nearest names). Dedup also writes every entity’s name embedding. Then every entity holding more than five descriptions gets one LLM summary of them (descriptions_summarised); one whose summary fails keeps them and is listed in description_summary_failures, to be tried again by the next run.
embed_relationships() — embeds fact text on RELATES edges.
ensure_indices() — rebuilds/verifies all indexes.

apply_changes() does not call it automatically: one finalize() after the batch judges all of the batch’s new entities together, in fewer LLM calls than one per file.

Choosing the Right Primitive

Situation	Use
Single doc, you know it exists and the text changed	`update(...)`
Single doc, may or may not exist (upsert)	`update(..., if_missing="ingest")`
Single doc, remove it	`delete_document(...)`
Single doc, remove it but the caller is not sure it was ever ingested	`delete_document(..., if_missing="ignore")`
PR diff or any heterogeneous batch	`apply_changes(added=..., modified=..., deleted=...)` then `finalize()`
Just added/changed one doc and you’re about to query	`ingest()` or `update()` then `finalize()`

End-to-End Example

A full runnable example lives in graphrag_sdk/examples/07_incremental_updates.py. It exercises:

Initial ingest with a stable document_id
No-op update (content-hash short-circuit)
Real update with orphan cleanup
Adding a second document
A heterogeneous apply_changes() batch
A single trailing finalize()
Verifying with completion()

Home

Pipeline

Ontology

Reference

Mental Model — What Lives in the Graph

`update()`

Parameters

Returns — `UpdateResult`

Effect on the graph

Crash safety

Example

`delete_document()`

Parameters

Returns — `DeleteDocumentResult`

Effect on the graph

Crash safety

Example

`apply_changes()`

Parameters

Returns — `ApplyChangesResult`

Effect on the graph

Canonical CI usage

Concurrency and the `update_concurrency` trap

`finalize()`

Returns — `FinalizeResult`

What it does (in order)

Choosing the Right Primitive

End-to-End Example

See Also

​Mental Model — What Lives in the Graph

​update()

​Parameters

​Returns — UpdateResult

​Effect on the graph

​Crash safety

​Example

​delete_document()

​Parameters

​Returns — DeleteDocumentResult

​Effect on the graph

​Crash safety

​Example

​apply_changes()

​Parameters

​Returns — ApplyChangesResult

​Effect on the graph

​Canonical CI usage

​Concurrency and the update_concurrency trap

​finalize()

​Returns — FinalizeResult

​What it does (in order)

​Choosing the Right Primitive

​End-to-End Example

​See Also

Mental Model — What Lives in the Graph

`update()`

Parameters

Returns — `UpdateResult`

Effect on the graph

Crash safety

Example

`delete_document()`

Parameters

Returns — `DeleteDocumentResult`

Effect on the graph

Crash safety

Example

`apply_changes()`

Parameters

Returns — `ApplyChangesResult`

Effect on the graph

Canonical CI usage

Concurrency and the `update_concurrency` trap

`finalize()`

Returns — `FinalizeResult`

What it does (in order)

Choosing the Right Primitive

End-to-End Example

See Also