Knowledge Graph Retrieval#

RAGFlow implements a dual-path retrieval architecture that keeps knowledge graph (KG) data and ordinary document chunks in the same backing store (Elasticsearch or Infinity), but routes them through entirely separate retrieval classes. The two paths are:

• Dealer.retrieval() — standard hybrid BM25+KNN search for normal document chunks 1
• KGSearch.retrieval() — graph-aware retrieval that synthesizes entities, relations, and community reports into a single prepended result block 2

KGSearch extends Dealer 3, so it inherits the base vector-search machinery while adding graph-specific query logic.

Isolation via available_int=0#

All KG chunks—entities, relations, community reports, graph snapshots, and subgraphs—are written to the doc store with available_int=0 at index time. Dealer.retrieval() hardcodes "available_int": 1 in every search request 4, so KG chunks are invisible to normal document search without any runtime branching.

The flag is set by the two indexing helpers in rag/graphrag/utils.py:

• graph_node_to_chunk() — sets "available_int": 0 on entity chunks and also stores rank_flt (PageRank) and n_hop_with_weight (pre-computed 2-hop neighbor paths)
• graph_edge_to_chunk() — sets "available_int": 0 on relation chunks

Graph snapshot and subgraph chunks written inside set_graph() also carry "available_int": 0.

Each KG chunk additionally carries a knowledge_graph_kwd field ("entity", "relation", "community_report", "graph", or "subgraph") that KGSearch uses as a targeted filter during retrieval.

KGSearch Retrieval Pipeline#

KGSearch.retrieval() is an async method that executes in five stages:

1. Query rewrite — Calls an LLM via query_rewrite() to extract entity type keywords (ty_kwds) and entity names (ents) from the question. LLM responses are cached in Redis via get_llm_cache/set_llm_cache.

2. Parallel graph lookups — Three concurrent store searches (each filtered by knowledge_graph_kwd):

   • get_relevant_ents_by_keywords() — KNN on entity embeddings, filtered by knowledge_graph_kwd=entity 5
   • get_relevant_ents_by_types() — ordered by rank_flt DESC, filtered by entity type 6
   • get_relevant_relations_by_txt() — KNN on relation embeddings, filtered by knowledge_graph_kwd=relation 7

3. N-hop expansion — Each entity chunk stores pre-computed 2-hop neighbor paths in n_hop_with_weight. KGSearch reads this field to add multi-hop relation scores without additional store queries 8.

4. Scoring — Entities are ranked by sim * pagerank (P(E|Q) ≈ pagerank × similarity). Relations get boosted by n-hop path overlap and entity-type membership 9.

5. Result assembly — Top entities and relations are serialized to CSV tables, then community reports are appended via _community_retrieval_() (ordered by weight_flt DESC, filtered by knowledge_graph_kwd=community_report). The final chunk is returned with docnm_kwd="Related content in Knowledge Graph" and similarity=1.0 10.

The use_kg Option and Call Site#

use_kg is a boolean flag on the retrieval API. When set, the retrieval handler in chunk_api.py:

1. Resolves the tenant's default chat LLM
2. Calls settings.kg_retriever.retrieval(question, tenant_ids, kb_ids, embd_mdl, llm)
3. Inserts the returned KG chunk at index 0 of ranks["chunks"] if its content_with_weight is non-empty

kg_retriever is a module-level KGSearch singleton initialized at startup in common/settings.py 11. It shares the same docStoreConn as the standard retriever but is a distinct object.

The KG injection happens after Dealer.retrieval(), child-chunk expansion, and optional ToC re-ranking, so the KG block is always the first result the LLM sees regardless of its vector score.

The same use_kg injection pattern appears in the Dify external knowledge integration handler at api/apps/restful_apis/dify_retrieval_api.py 12.

Key Source Files#

Status note: As of v0.27.0, the GraphRAG system is superseded by the Knowledge Compilation Engine (rag/advanced_rag/knowlege_compile/). The KGSearch/Dealer dual-path architecture remains active for datasets created before the migration. See PR #16515 for the new engine.