How a GraphRAG Topic Works — From Upload to Answer

This page follows one file and one question through a GraphRAG Topic. You learn what happens to a file after you upload it, and what happens between your question in the chat and the answer you read.

You do not need this page to use a Topic. Read it when you want to understand why a Topic answers the way it does, which setting changes which step, and where to look when an answer is not what you expected.

A GraphRAG Topic works like a RAG Topic, with one big addition: next to the text pieces, it builds a knowledge graph. The graph holds the things your documents mention (entities, for example a person, a part or a product) and how they are connected (relationships). Questions about connections and overview questions need this graph.

Phase When it runs What it does

A · Upload

Once per file

Reads the file, cuts it into pieces, finds the entities and relationships in every piece and adds them to the graph

B · Community building

After uploads, on a schedule, or when you ask

Groups the graph into topics (communities) and writes a summary for each

C · Chat

For every question

A router picks the best way to search, the search runs, and the model writes the answer
flowchart LR subgraph A["A · Upload (once per file)"] direction TB U1["File"] --> U2["Read the text"] --> U3["Cut into pieces"] --> U4["Find entities
and relationships"] end G[("Knowledge graph
+ text pieces
+ entity vectors")] subgraph Bc["B · Communities"] direction TB B1["Group the graph"] --> B2["Write a summary
per group"] end R[("Community
summaries")] subgraph C["C · Chat (every question)"] direction TB Q1["Question"] --> Q2["Router picks a way
to search"] --> Q3["Search"] --> Q4["Answer + sources"] end A --> G --> Bc --> R G --> C R --> C

1. Phase A — From file to graph

The whole path

flowchart TD F["You upload a file"] --> T{"File type?"} T -->|"Text file"| X1["Read as text"] T -->|"Structured file
json, xml, yaml, toml, csv, tsv"| X2["Flatten: one record at a time
as 'key: value' lines"] T -->|"Document
pdf, docx, xlsx, pptx"| X3["Docling converts it to text
and lifts out the pictures"] T -->|"Image"| X4["Vision model describes it"] X1 --> TX["Text"] X2 --> TX X3 --> TX X3 --> PI["Pictures
(described by the vision model)"] X4 --> PI TX --> CH["Cut into pieces (chunks)
Chunk Size and Chunk Overlap"] CH --> LOOP subgraph LOOP["For every piece"] direction TB E1{"Table of contents
or index?"} -->|"Yes"| E0["Skip: no entities"] E1 -->|"No"| E2["Extraction model finds
entities and relationships"] E2 --> E3["Deduplication: is this entity
already in the graph?"] E3 --> E4["Write to the graph
(remember which piece it came from)"] E4 --> E5["Embed the entities
and the piece"] end PI --> PM{"Picture handling?"} LOOP --> PM PM -->|"Picture in the graph (default)"| PN["One Image node per picture,
linked to the entities it shows"] PM -->|"Extract entities"| PE["The description is read
like normal text"] PM -->|"Ignore"| PX["Pictures are not used"]

Step by step

# Step What happens What you can influence What you notice

1

Receive

The Topic checks the file name and type. A file with a type the Topic does not accept is refused.

File Types (wizard step 2)

A refused file shows a message at upload

2

Read the text

Text files are read directly. Structured files are always flattened, one record at a time, into key: value lines. Documents are converted by the Docling server. Without one, they are refused.

Docling Server, Docling Settings (advanced)

PDF and Office files take longest

3

Replace the old version

If a file with the same name was ingested before, what it left is removed first: its pieces, its pictures, and its share in the graph (see "Removing a document" below).

—

A re-upload fully replaces the file

4

Cut into pieces

The text is cut into pieces of at most Chunk Size characters. Each piece repeats Chunk Overlap characters of the one before.

Chunk Size, Chunk Overlap

Larger pieces: fewer model calls and faster uploads, but coarser sources and some missed details. About 1000–2000 works well

5

Find entities and relationships

For every piece, the Graph Extraction Model lists the things the text mentions, their type (for example Person, Part) and how they connect. It also notes other names for the same thing, such as abbreviations. A piece that only looks like a table of contents or an index is skipped.

Graph Extraction Model

This is the main cost of an upload: one model call per piece. A stronger model builds a better graph, but is slower and more expensive

6

Deduplicate

Many pieces mention the same thing under slightly different names ("ECB", "European Central Bank"). The Topic first compares names — same name, same name ignoring spaces and capitals, abbreviation of a name. What stays unclear goes to the Deduplication Model.

Deduplication Model

Without this step, the graph would hold the same thing many times. A weak model can merge things that are different, or keep duplicates

7

Write to the graph

The entities and relationships are written to the graph database. Each entity and relationship remembers which pieces it comes from. A piece in which nothing was found is still stored as text.

Graph Database (registered under Admin → Graph Databases)

The graph database fills as the upload goes on

8

Embed

The embedding model turns every entity and every piece into numbers. They are written to the vector store.

Embedding Model, Vector Database, Collection Name

If the embedding model is not reachable, the upload fails

9

Pictures

With Picture in the graph, each picture becomes its own node in the graph, linked to the entities it shows. A model decides which entities a picture shows.

Picture handling, Image Describer Model

Uploads with many pictures take longer. Pictures can then show up in chat answers

10

Keyword index

When keyword search is on for Local Search or Global Search, the entities, the pieces and the community summaries are also written to a keyword index.

Vector Settings (wizard step 3)

Exact terms such as product codes are found better

What is stored afterwards

What Where Used for

Entities and relationships, with the pieces they come from

Graph database

Following connections

Text pieces and entity vectors

Vector database

Finding entities and pieces by meaning

Keyword index

In the Topic (when keyword search is on)

Finding exact words

Pictures and the original file

In the Topic

Showing pictures, download links

Community summaries

Vector database

GLOBAL questions. They appear after phase B

Removing a document

Deleting a document under Data Upload does not delete its entities outright. Each entity and relationship remembers every piece it comes from. The delete only takes this document’s pieces away. An entity that other documents also mention stays in the graph. An entity that only this document mentioned is deleted. Community summaries are not rewritten by a delete: run Recompute Communities Now afterwards.

Community summaries keep what a deleted document said. After a delete, overview answers can still mention an entity from the removed document, until the next community rebuild. Run Recompute Communities Now after you remove documents.

2. Phase B — Building communities

A community is a group of closely connected entities, for example "everything about the brake system". GLOBAL questions ("What are the main topics?") are answered from community summaries, because no single piece holds the overview.

flowchart TD S["Refresh Cycle fires,
or you click Recompute Communities Now"] --> R["Read the whole graph"] R --> C["Cluster it into communities
Leiden method, Resolution setting"] C --> Z{"Community has
two entities or more?"} Z -->|"No"| Z0["No summary"] Z -->|"Yes"| M{"Changed since
the last run?"} M -->|"No"| M0["Keep the old summary"] M -->|"Yes"| W["Community Report Model
writes a summary"] W --> V["Embed and store the summaries"] M0 --> V V --> D["Delete summaries
that no longer apply"]
What Detail

When it runs

On the Refresh Cycle schedule, and whenever you click Recompute Communities Now on the Actions tab. Nothing recomputes right after an upload

Resolution

Higher: more and smaller communities, more detailed summaries, but more model calls. Lower: fewer and larger communities. 1.0 is standard, 0.5–2.0 is the useful range

Cost

One model call per changed community. A large graph can take minutes. It runs in the background

What you notice

Until it has run, GLOBAL questions find no summaries and answer with the no-results message. New documents appear in GLOBAL answers only after the next run

Fewer summaries than communities

Normal. A community with a single entity gets no summary

3. Phase C — From question to answer

You do not choose how a question is searched. A router reads each question and picks the best way.

The whole path

flowchart TD Q["You send a question
(and maybe a file)"] --> H["Add the earlier messages of this chat"] H --> RT["Router: one model call reads the question
and picks a way, with a confidence"] RT --> D1{"Which way?"} D1 -->|"DIRECT
thanks, small talk,
'make it shorter'"| DI["Answer from the conversation"] D1 -->|"ATTACHMENT
the attached file
answers it alone"| AT["Answer from the file"] D1 -->|"PATH
'How is A related to B?'"| PA["Find the shortest chain
between A and B"] D1 -->|"LOCAL
facts about named things"| LO["Search around entities"] D1 -->|"GLOBAL
overview of all documents"| GL["Search community summaries"] D1 -->|"HYBRID
overview and detail,
or unsure"| HY["Summaries first, then
follow-up searches"] DI -->|"Model says it needs documents"| HY AT -->|"Model says it needs documents"| HY PA -->|"No two entities, or no path"| LO DI --> OUT AT --> OUT PA --> OUT LO --> OUT GL --> OUT HY --> OUT["Answer with sources"] OUT --> SV["Saved in the chat history"]

If the router is below its Confidence Threshold (default 0.6), the question goes to HYBRID. HYBRID is the safe choice: it is the slowest way, but the one that misses the least. DIRECT needs an extra confidence of 0.9 (DIRECT Confidence Threshold) and can be switched off with Answer without searching (DIRECT).

The six ways

Way Best for How it works Answer shows

DIRECT

Thanks, small talk, "shorter", "as a table"

Answered from the chat history alone. No search

No sources

ATTACHMENT

A question that only the file you attached can answer

Answered from the attached file alone. No search

No sources

PATH

"How is A related to B?"

Finds the two named entities, then the shortest chain of connections between them (at most Path Max Hops), and answers from that chain and its source pieces

Sources of the chain

LOCAL

Facts about named things: people, parts, products, events

Finds starting entities, follows connections from them, collects the text pieces behind them (see below)

Source documents of the pieces used

GLOBAL

Overview questions about all documents

Finds the best community summaries, lets the model read each one, then writes one answer from what was relevant

No source files, because the answer comes from summaries

HYBRID

Overview and detail

Searches summaries first, plans follow-up questions, runs a LOCAL search for each, then writes one answer from everything

Source documents of the pieces used

LOCAL in detail

flowchart TD Q["Question"] --> S1["Find starting entities
by meaning, by keywords,
and from the best matching pieces"] S1 --> S2["Merge the lists by rank"] S2 --> S3["Follow the connections from them
Hop Depth steps, at most Max Subgraph Nodes"] S3 --> S4["Collect the text pieces behind
the entities and relationships found"] S4 --> S5["Keep the Max Cited Chunks best pieces"] S5 --> S6["Prompt: the graph as text +
the pieces + history + question"] S6 --> S7["Language model answers
and cites the pieces"] S7 --> OUT["Answer with sources"] S2 -->|"Nothing above the
Min. Similarity Score"| NO["No-results message"]
Setting What it does Higher or lower

Seed Strategy

Where the starting entities come from: NODES (entity names), CHUNKS (pieces worded like your documents) or FUSED (both, default)

FUSED finds more, but is a little slower

Top-K Nodes

How many starting entities

Higher: broader, slower

Min. Similarity Score

How close an entity must be to count

Higher: only close matches, more "no results"

Hop Depth

How many connection steps to follow

Higher: more related facts, but slower and less focused

Max Subgraph Nodes

Limit of entities collected in total

Higher: more facts for the model, but longer input

Max Cited Chunks

How many text pieces the answer is written from, and so how many sources it can show

Lower: shorter source lists. Higher: fuller answers

Top-K Seed Chunks, Top-K Unlinked Chunks

Pieces used to find entities, and extra pieces that no entity carries (for example tables the extraction missed)

Higher: more starting points, slower

GLOBAL in detail

flowchart TD Q["Question"] --> R1["Find the best community summaries
Top-K Reports, Min. Similarity Score"] R1 -->|"None found"| NO["No-results message"] R1 --> M["Map: the model reads each summary alone
and says if it helps, and what it adds"] M --> RD["Reduce: one answer from all
summaries that helped"] RD --> OUT["Answer
(streamed while it is written)"]

A higher Top-K Reports gives broader answers, but one more model call per summary.

HYBRID in detail

flowchart TD Q["Question"] --> R1["Find the best community summaries"] R1 --> PL["Model plans follow-up questions
about concrete things"] PL --> LS["For each follow-up question:
a LOCAL search"] LS --> MORE{"More to ask?
Max Follow-up Rounds"} MORE -->|"Yes"| PL MORE -->|"No"| SY["Synthesis: one answer from
the summaries and all findings"] SY --> OUT["Answer
(streamed while it is written)"] PL -->|"Planning fails"| LO["Fallback: LOCAL search
on the original question"] LO --> OUT

Max Follow-up Rounds times Max Follow-up Questions is the most searches one chat question can cause. Raise them for fuller answers. Lower them for faster, cheaper answers.

After the search

Whichever way was used, the answer is finished in the same way as in a RAG Topic:

  • Citations in the answer become file names. Documents appear below the answer as sources. A source that came from a graph database record (not from an uploaded file) shows as name (graph ingestion) and has no download.

  • Pictures that the model placed in the answer are shown at their position.

  • The answer is saved in the chat history. A turn that you stop is not saved.

  • GLOBAL and HYBRID answers stream while they are written. For the other ways, the model first writes the whole answer, then it is shown word by word.

4. Where the model calls happen

Each model call costs time and, for cloud models, money.

When Call Model role Only if

Upload

Docling conversion

—

The file is a document

Upload

Picture description

Image Describer Model

The topic uses pictures

Upload

Entities and relationships, one per piece

Graph Extraction Model

Always

Upload

Same-entity check

Deduplication Model

Names are unclear

Upload

Which entities a picture shows

Image Describer Model

Picture in the graph

Upload

Embedding of entities and pieces

Embedding Model

Always

Communities

One summary per changed community

Community Report Model

Always

Chat

Router

Router Model

Always

Chat

Embedding of the question

Embedding Model

Always

Chat

Planning, synthesis

Follow-up Model

HYBRID

Chat

Answer

Language Model

Always

A role without its own model uses the Language Model. Roles are described in Models and Roles.

5. Seeing it happen — the DEV Reports tab

If you need to know exactly what a Topic did, use the DEV Reports tab. Switch on Report uploads, Report chat answers or Report community rebuilds, then upload a file, ask a question or rebuild. The tab shows every step above: the text pieces, the entities and relationships found, what the deduplication merged, the way the router chose and why, the entities and pieces found for a question, and the prompts. The switches are off after every start of the Topic. Reports contain full prompts and documents. Only users with DEV_REPORTING can see them. How to read a report: DEV Reports.

6. Which setting fixes which problem

Symptom Phase What to try

A file is accepted, but its facts are not found

A

Check the Ingested Sources list. A scan without readable text yields nothing. Check Docling Settings

The graph holds the same thing many times

A

Use a stronger Deduplication Model

Many facts are missing from the graph

A

Use a stronger Graph Extraction Model, or a smaller Chunk Size

Overview questions answer "no results"

B

Run Recompute Communities Now on the Actions tab. New documents show up in overview answers only after a run

Overview answers are too thin

B, C

Lower Resolution (larger communities), or raise Top-K Reports

Connection questions get a fact list, not a chain

C

Name both things in the question. The router needs two named entities for PATH

Answers are slow

C

A router decision of HYBRID is the slowest way. Lower Max Follow-up Rounds and Max Follow-up Questions

A question gets no sources

C

The router chose DIRECT, ATTACHMENT or GLOBAL. Raise the DIRECT Confidence Threshold, or switch DIRECT off

Exact codes or names are not found

C

Turn on keyword search in Vector Settings. Upload the files again

Related