Knowledge Graph

Knowledge Graph reads your documents with an AI model, identifies what they mention (people, companies, regulations, products, concepts) and how those things relate to each other, and stores it all as a knowledge graph in a database of yours. You can then ask it questions: it finds the most relevant text fragments, follows the relationships between what appears in them and writes an answer with the sources it used.

Use it when you need to query a set of documents where it matters how things are connected, for example regulations that refer to other regulations, contracts between several parties or technical documentation with many cross-references.

When to use it

Build a reference base on regulations or internal manuals and answer questions citing the source document.
Answer questions that span several documents, such as “which contracts did this supplier sign and on what terms”.
Give an agent a search tool over your documentation.
Prepare reports from many documents with a multi-step research.
Keep several sets of documents (legal, technical, sales) apart in the same database and query them separately.

What you need

Connection	What to connect
Database (required)	Where the graph is stored. Connect the Database Info output of a database component with its Operation set to DatabaseInfo, for example Postgres SQL, MySQL, SQLite, libSQL or Supabase.
Llm (required)	An AI model component, for example OpenAI. It reads the documents when they are added and writes the answers when you search.
Embeddings	An embeddings component, for example OpenAI Embeddings. It is needed to search, and it is best to connect it when adding documents too: without it, documents are stored without the information that makes them findable.

How it works

The Operation field decides what the component does on each run. Usually you will use one flow to load documents and another one to query them, with the same database and the same Domain:

Add Document: reads the documents, splits them into fragments, extracts what they mention and how it relates, and stores it. A document that was already processed and has not changed is skipped.
Resolve Entities: merges repeated entities that are written differently in several documents, so the graph has no duplicates.
Search: answers a question with the most relevant fragments and the graph’s relationships. If the fragments found are not useful, it rephrases the question and searches again.
Deep Search: carries out a multi-step research over the graph and writes a more elaborate answer, with the role and format you give it.
Retriever: does not search by itself; it offers the graph as a search source for other components.

Configuration

Common fields

Field	What it does
Operation (required)	Add Document, Resolve Entities, Search, Deep Search or Retriever. Default: Add Document. The visible fields change with the operation.
Domain	A label to keep several graphs apart in the same database, for example `employment_rules` or `technical_manuals`. Searches only look inside their domain. Default: `default`.

In Advanced, Table Prefix is the prefix of the tables created in the database (default: kgraph_). Change it if you want to keep completely separate graphs in the same database.

Add Document

Field	What it does
Documents (required)	The documents to add: files that come from a file upload component, a URL or another source, or data that already contains the text. One or several.
Document Type	What kind of documents they are, to guide the extraction. Default: `General`.
Chunk Size	The size of each fragment the document is split into, in characters. Default: 2000.
Chunk Overlap	How many characters two consecutive fragments share, so ideas are not cut in half. Default: 200.
Section-Aware Chunking	Splits documents by their section headings, so each fragment follows the document’s structure. On by default.
Semantic Hierarchy	The names of your documents’ levels, from highest to lowest and separated by commas, for example `TITLE,CHAPTER,Section,Article`. It keeps the hierarchy even when all headings look the same.
Extract Document Metadata	Uses the AI model to extract details of each document, such as its title, dates or type. Off by default.
Enable Table Extraction	Detects the tables in the documents and extracts short, precise facts from them. On by default.
Generate Chunk Atomic Facts	Generates, from what was extracted, short self-contained statements that help find specific facts. It makes no extra calls to the AI model. On by default.
LLM Chunk Atomic Facts	Asks the AI model to write those statements for each fragment. They are of higher quality, but each fragment means one more call to the model. Off by default.
Max Facts per Chunk	The maximum number of statements per fragment when the AI model writes them. Default: 10.
Enable Entity Normalization	Uses the AI model to make entity names consistent, for example writing “nia 200” as “NIA-ES 200”. Off by default.

In the Document Processing tab you can adjust the instructions the AI model receives: Graph Extraction Prompt (how to extract entities and relationships), Document Summary Prompt (how to summarise each document), Metadata Extraction Prompt and Entity Normalization Prompt. It also has the table settings: Context Before Table and Context After Table (how much surrounding text is used as context, 500 and 200 characters by default) and Minimum Table Rows and Minimum Table Columns (the minimum size for something to count as a table, 2 by default). The default values work well for most documents.

In Advanced, Generate Graph Image adds an image of the graph to the result, and Graph Export Format chooses the format the graph is returned in: json (the default), graphml or gexf.

Resolve Entities

Field	What it does
Similarity Threshold	Between 0 and 1: how similar two entities must be to be merged. The higher, the stricter. Default: 0.9.

Search

Field	What it does
Search Query	The question. When the component is an agent’s tool, the agent writes it.
Top K Results	The maximum number of fragments used. Default: 5.
Fast Mode	Identifies more quickly what the question mentions. On by default.
Max Rewrite Attempts	How many times it can rephrase the question if the fragments found are not relevant. Default: 2.
Enable Stream Progress	Shows progress messages while searching, when the component works as an agent’s tool. Off by default.
Retrieval Only	Returns the fragments found without writing an answer. Useful when another agent will work with them. Off by default.
Include Grading	With Retrieval Only, adds an assessment of whether the fragments are enough to answer (sufficient, partial or insufficient) and why.

The Search tab has Graph Hops (how many steps it follows along the graph’s relationships from what the question mentions, 2 by default), Metadata Fields (with Retrieval Only, which details of each document come with each fragment, separated by commas, for example title,effective_date), Date Order Field (a date detail of the documents used to sort the results, for example publication_date) and Date Order Direction (desc, newest first, or asc).

Deep Search

Field	What it does
Search Query	The question or the research request.
Agent Role	The role the research works with, for example “You are an expert auditor…”.
Output Format Instructions	How the answer should be presented, for example “Report with an executive summary”. By default, in Markdown format.
Citation Metadata Fields	Which document details are included in the citations, separated by commas, for example `title, date, url`.
Domain Description	A description of the field the documents belong to, for example “Spanish auditing standards”, to give the research context.
Top K Results	How many fragments each search retrieves. Default: 5.

Graph Hops, Date Order Field and Date Order Direction, in the Search tab, also apply.

Retriever

It uses Top K Results (how many fragments each search returns) and, in the Search tab, Date Order Field and Date Order Direction.

Using it as an agent tool

You can connect this component to an agent’s Tools input. In the Tool tab, Tool Name and Tool Description are the name and explanation the agent uses to recognise the tool and decide when to call it: write a clear description of what it does.

By default it is called knowledge_base. The agent writes the question and the component answers with the operation it has selected, Search or Deep Search.

Output

Output	Operations	What it contains
Data	Add Document, Resolve Entities	In Add Document, a summary: how many new entities and relationships were added, the graph totals and the whole graph in the chosen format (plus the image, if you asked for it). In Resolve Entities, confirmation that the entities were merged.
Message	Search, Deep Search	The written answer (`answer`). In Search it also includes the fragments used as citations (`citations`). With Retrieval Only, instead of the answer it returns the list of fragments (`documents`) with their text, their score and the document details.
Retriever	Retriever	The graph as a search source. Connect it to components that accept a retriever, such as RetrieverTool or Retrieval QA History.

Example

The legal department of Grupo Alcázar wants to query its internal policies:

Loading flow. The PDFs of the internal policies arrive at Documents. The component, set to Add Document, has a Postgres SQL component with the DatabaseInfo operation, an AI model in Llm and an embeddings model in Embeddings connected. In Domain they type internal_policies and in Semantic Hierarchy CHAPTER,Article.
Clean-up. After loading all the documents, a run with Resolve Entities merges the duplicate entities.
Query flow. Another Knowledge Graph node set to Search, with the same database, the same models and the same Domain, is connected as a tool to an agent. When someone asks “How long do I have to report a conflict of interest?”, the agent calls the tool and answers citing the source articles.

Good practices

Use the same database, the same Domain and the same embeddings model when loading and when querying. If you change the embeddings model, load the documents again.
Run Resolve Entities after loading a large batch of documents.
Set Semantic Hierarchy if your documents have a fixed structure (titles, chapters, articles): it improves the fragments and the answers.
Turn on LLM Chunk Atomic Facts or Extract Document Metadata only if you need them: each one adds calls to the AI model and therefore cost.

Agent: an agent you can give the graph to as a tool.
RetrieverTool: turns the Retriever output into a tool.