How a Document Becomes Graph

Uploading a document to a GraphRAG Topic does noticeably more work than uploading to a RAG Topic. This page walks through what happens between "file selected" and "this content is answerable". Then a slow upload, a large model bill, or an overview answer that seems to miss something all have an obvious place to look.

The path from file to graph

flowchart TD F["File uploaded"] --> T{"1 · Read the file
by file type"} T -->|"Plain text"| T1["Decoded directly"] T -->|"Structured data"| T2["Flattened to
key/value text"] T -->|"Image files"| T3["Described by
vision model"] T -->|"Other files"| T4["Converted
by Docling"] T1 --> C["2 · Split the text
into chunks"] T2 --> C T3 --> C T4 --> C C --> E["3 · Embed chunks
and keep the file"] E --> X["4 · Extract entities
and relationships"] X --> D["5 · Merge duplicates
with the existing graph"] D --> W["6 · Write to the
graph database"] W --> N["7 · Embed entities
(and keyword index,
if switched on)"] N --> S["Searchable by LOCAL
(GLOBAL after a rebuild)"]

Things to know about this path:

  • Steps 4 to 6 are what a plain RAG Topic does not do. They are the reason GraphRAG uploads are slower and use more model calls. A model reads every chunk to find entities, on top of the embedding call every chunk already needs.

  • Which models work: the Extraction model finds the entities. The Dedup model decides whether two entities are the same thing. Each can be its own model, or reuse the Language Model. See Models and their roles.

  • Pictures (inside a document, or image files) follow the picture handling you chose in wizard step 2. They can be skipped, read like normal text, or stored as pictures in the graph so that answers can show them. A picture is only described if a vision model is set. See File types, Docling and pictures.

  • Docling is only used for files that are neither plain text nor images, for example PDF or Word. Without a Docling server, uploading such a file fails.

  • Keyword index: step 7 builds a keyword index only if you chose meaning and keywords for LOCAL or GLOBAL search in wizard step 3. By default, searches use meaning only.

  • A document is answerable by LOCAL right away. GLOBAL needs a rebuild of the communities. See the next section.

Communities are not rebuilt per upload

flowchart TD Start(["Scheduled, or
on demand"]) --> C1["1 · Group the graph
into communities (Leiden)"] C1 --> C2["2 · Assign a community
to each entity"] C2 --> C3["3 · Write a summary
per community"] C3 --> C4["4 · Embed
each summary"] C4 --> E["GLOBAL can now answer
from this snapshot"]

Communities are always on. The rebuild runs on the refresh cycle you set in wizard step 3. You can also start it yourself on the Topic’s Actions tab, in the section Communities, while the Topic is RUNNING. See Configuration and functions. A community with only one entity gets no summary, so a rebuild can report fewer summaries than communities. This is normal.

GLOBAL does not see new documents until the next rebuild. Between two rebuilds, new documents are invisible to GLOBAL, even though LOCAL already sees them. This is the most common reason a GraphRAG Topic knows something when you ask about it directly, but not when you ask about it as an overview. Run Recompute Communities Now after a large upload.

Removing a document

On the Data Upload tab, the list Ingested Sources shows everything the graph was built from. The trash icon removes one source. What happens:

  • The text pieces of that source are deleted.

  • Each entity and connection loses its link to that source. Those that no other source also contains are deleted. Those that other sources contain are kept. So a delete often changes fewer things than you expect.

  • The summaries of the communities are not rewritten. An overview answer can still mention a removed entity until the next rebuild of the communities.

  • To undo a removal, upload the document again.

  • If the list was out of date and the source is already gone, you get a warning that nothing was changed, and the list refreshes. This is not an error.

Two ways into the graph

Everything above describes the upload on the Data Upload tab. A second route exists for another system that has already modelled its own graph data. That system sends its entities and relationships straight into this Topic’s graph, so no model reads text and no extraction takes place. You cannot start this route from the web interface. If your data arrives this way, whoever connected that system set it up. A Topic that only gets its graph from another system can switch File Ingestion off in its settings, and then the upload area is hidden.

You can see the effect in the Ingested Sources list. It shows uploaded file names and also the ids of records another system sent. A record that comes from graph synchronisation has no stored file, so there is nothing to download. Removing such a source only removes its link from the entities. It does not delete them. The same rule shows on chat answers: such a source appears as name (graph ingestion) and has no link. See the glossary.

Related