Knowledge Graph Extraction

Relevant source files

The following files were used as context for generating this wiki page:

• backend/onyx/prompts/kg_prompts.py
• AGENTS.md
• CLAUDE.md
• backend/onyx/prompts/search_prompts.py
• CONTRIBUTING.md
• backend/onyx/prompts/deep_research/orchestration_layer.py

Knowledge Graph (KG) Extraction in Onyx is a specialized process within the indexing and retrieval pipeline designed to build and query structured relationships between entities found in unstructured text. By transforming documents into a network of entities and relationships, Onyx enables complex queries that go beyond simple semantic search, such as counting entities, identifying specific relationship paths, and performing multi-hop reasoning.

The system relies on a combination of Large Language Models (LLMs) for high-fidelity extraction and a background processing architecture to maintain the graph. Extraction occurs during the document processing phase, where a dedicated kg_processing worker handles relationship building and clustering algorithms to ensure the graph remains accurate and deduplicated.

Sources: AGENTS.md:65-69, backend/onyx/prompts/kg_prompts.py:151-155

Extraction Architecture

The extraction process is divided into two primary phases: Document Indexing Extraction and Query-Time Extraction. During indexing, the system identifies entities and relationships within new documents. During query time, it extracts entities and filters from user questions to generate structured SQL queries against the graph database.

The KG Processing Pipeline

The background processing is managed by Celery workers. The kg_processing worker specifically handles the Knowledge Graph lifecycle.

The diagram above illustrates the flow from document ingestion to the persistent storage of graph data.

Sources: AGENTS.md:23-35, AGENTS.md:65-69

Extraction Methodology

Extraction is driven by precise LLM prompts that enforce a strict schema for entities and relationships. The system uses a set of predefined entity types and relationship types to ensure consistency across the graph.

Entity and Relationship Schema

The extraction focuses on three core components:

• Entities: Prescribed types formatted as ENTITY_TYPE_NAME::entity_name.
• Relationships: Connections formatted as SOURCE_ENTITY_TYPE::source_entity__relationship__TARGET_ENTITY_TYPE::target_entity.
• Terms: High-level terms identified in the text for broader categorization.

Sources: backend/onyx/prompts/kg_prompts.py:27-41

Extraction Prompting Logic

The MASTER_EXTRACTION_PROMPT guides the LLM to identify non-trivial relationships expressing needs, wants, likes, plans, or problems. A critical constraint is that the LLM must only use provided entity types and must refer to "all" entities of a type using the * wildcard if referred to generally in the text.

Sources: backend/onyx/prompts/kg_prompts.py:151-200

Component	Format Example	Description
Entity	ACCOUNT::Nike	A specific instance of an entity type.
Wildcard Entity	CONCERN::*	Represents any or all entities of the 'CONCERN' type.
Relationship	ACCOUNT::Nike__had__CONCERN::performance	A typed connection between two specific entities.
Attribute	[degree: severe]	Metadata filters applied to entities in queries.

Sources: backend/onyx/prompts/kg_prompts.py:30-41, backend/onyx/prompts/kg_prompts.py:84-90

Query-Time Extraction and Translation

When a user asks a question, the KG system performs a "Search Strategy" analysis to decide if the question should be answered via a standard semantic search or a structured Knowledge Graph search (SQL).

Strategy Detection

The system evaluates the user's intent to determine:

1. Search Type: SEARCH (filtered search) or SQL (specific entity identification or counting).
2. Search Strategy: SIMPLE (list/count) or DEEP (requires analysis of source text).
3. Divide and Conquer: Whether to analyze objects individually before aggregating results.

Sources: backend/onyx/prompts/kg_prompts.py:465-535

SQL Generation

If a SQL strategy is chosen, the system translates the natural language question into a Postgres-compatible SQL query targeting two internal tables: entity_table and relationship_table.

The Knowledge Graph schema used for SQL generation.

Sources: backend/onyx/prompts/kg_prompts.py:650-685, backend/onyx/prompts/kg_prompts.py:705-735

Source Detection and Refinement

Once entities are identified through SQL, the system must map them back to the original documents for grounded answering. This is handled by the SOURCE_DETECTION_PROMPT, which joins the results of the relationship queries with the entity_table to retrieve source_document IDs.

Error Correction

The system includes an iterative loop to fix SQL syntax errors. Common corrections include:

• Ensuring SELECT DISTINCT columns match ORDER BY columns.
• Casting JSON attributes for comparison (e.g., attributes ->> 'status' = 'active').
• Removing source_document from the SELECT clause when performing aggregations.

Sources: backend/onyx/prompts/kg_prompts.py:835-865, backend/onyx/prompts/kg_prompts.py:910-940

Summary of KG Components

The Knowledge Graph system is a complex interplay of LLM-based extraction and traditional relational database querying.

System Part	Responsibility	Primary Files
Extraction Prompts	Define how the LLM identifies nodes and edges.	kg_prompts.py
KG Worker	Background task execution for graph building.	AGENTS.md
Search Rephraser	Turns user history into standalone KG queries.	search_prompts.py
Orchestration	Determines when to use KG vs. Vector Search.	orchestration_layer.py

Sources: backend/onyx/prompts/kg_prompts.py:1, AGENTS.md:65, backend/onyx/prompts/search_prompts.py:16-20