Skip to main content

​
cognee.report()

​
Description

Generate a Graph Insight Report — a Markdown overview of what a knowledge graph actually contains: its most connected nodes, links that cross node-set boundaries, a breakdown of how its edges got there, and a handful of suggested questions for exploring the graph further. The report is read-only. It is computed from the graph engine’s get_graph_data() and makes no schema or storage changes, so it is safe to run against a production graph. Run it after remember() / cognify() to sanity-check a freshly built graph. The full Markdown is returned as a string and written to output_path, unless you pass output_path=None to skip the file write.

​
Parameters

​
Optional[Union[str, List[str]]]
default:"'main_dataset'"
Dataset name(s) to analyse. A single string is treated as a one-element list.
​
Optional[str]
default:"'graph_report.md'"
File path for the generated Markdown report. Pass None to skip writing the file and only return the string.
​
int
default:"10"
How many hub nodes and cross-set connections to surface.
​
Optional[User]
default:"None"
User context for dataset access. Falls back to the default user.
Only one graph is analysed per call: datasets is resolved to the datasets you have read access to, and the first of those determines which graph is read. Passing several dataset names does not merge them into a combined report — call report() once per dataset instead.

​
Returns

str — the full Markdown report.

​
What the report contains

The top top_n nodes ranked by a combined score of min–max-normalised degree plus PageRank. Ranking prefers the knowledge layer (Entity and EntityType nodes) and falls back to all content nodes when the graph has neither.The analysis graph excludes NodeSet container nodes and belongs_to_set membership edges, so organisational scaffolding never wins the hub ranking. Each entry lists the node’s name, its node sets, its degree, and its PageRank score. A node with no node-set membership shows — in the set column — normal for graphs built without node sets.
Entity-to-entity edges whose two endpoints have different node-set membership — the places where your sources actually connect to each other. Fully disjoint pairs (no shared set at all) rank first, then pairs are ordered by the combined PageRank of their endpoints.Membership is read from the belongs_to_set edges pointing at NodeSet nodes, plus the comma-separated source_node_set property that chunks and documents carry. If nothing qualifies, the section says so — add data under multiple node sets to populate it.
A count and percentage split of how edges entered the graph:
These tags are derived at report time from the endpoint node types, not read from the graph. Cognee stores no confidence score or provenance tag on edges, so treat the split as a structural summary rather than a per-edge quality signal.
Four to five short questions for exploring the graph, generated by a single LLM call over the first 2000 characters of the report body. This is the only LLM call the report makes — every other section is computed deterministically.Content questions (“How are X and Y related?”) work directly with recall() / search(). The LLM sometimes suggests graph-structure questions instead — shortest paths, degree thresholds, per-node edge counts — which the completion-style search types cannot compute; use SearchType.CYPHER or SearchType.NATURAL_LANGUAGE for those. Questions about EXTRACTED/DERIVED edges cannot be answered by any search type: those tags exist only inside the report (see Edge Provenance above), not in the graph.

​
Cost and fallbacks

  • One LLM call, for the Suggested Questions section only. If it fails (no API key, rate limit, provider error), the failure is logged as a warning and the section degrades to a single generic question — report() does not raise.
  • PageRank is computed with networkx (sparse). If it is unavailable or fails numerically, a warning is logged and hubs are ranked by degree alone, with PageRank reported as 0.0000.
  • Empty graph: if the graph has no nodes, the report body is _Graph is empty — run cognify first._ instead of the four sections.

​
Examples

From the terminal:
The same retriever is registered as SearchType.GRAPH_REPORT, which is useful when you want the report to flow through the normal search plumbing:
The query text is ignored and the result is a single-element list holding the same Markdown string. Prefer cognee.report() when you want the file written for you.

​
See also