Knowledge graph — "who and what is in our documents?"

Search answers "which files mention this?". The knowledge graph answers the questions that come after it: who appears across these contracts?, which files put these three people in the same room?, what is this document actually about?

K-Lake builds it by enrichment — reading the text it has already extracted and recording the entities it names (people, organisations, locations, agreements, and whatever else you configure) along with the relations the text asserts between them.

Enrichment reads extracted text, so extraction has to have run first. A source with extraction disabled contributes nothing to the graph. Coverage is reported per source so you can see exactly how much of a source has been enriched.

Turning it on

Enrichment is a Smart Action, enabled per source. Once on, it runs automatically on newly extracted files, and a background sweep picks up files that were extracted before you enabled it — so switching it on for an existing source backfills rather than only applying to new arrivals.

Check how far it has got:

kdbl-control source enrich-coverage --source-id "smbfs://nas/contracts"

This reports how many extracted files have been enriched, so a partially drained backlog is visible as a partial number rather than looking like a source with few entities.

Exploring it

The web console's Entities page (Find › Entities in the sidebar, or press ⌘K / Ctrl+K and type entities) offers three views over the same graph: search for an entity, open it, and choose Orbit, Network or Documents. Three, rather than one, because the data has two very different regimes: on a typical corpus the large majority of entities have no asserted relation at all, half of the connected ones have exactly one, and the largest hub can have well over a thousand. No single layout serves both ends of that.

View	What it shows	When to use it
Orbit	One entity at the centre, with a capped number of neighbours around it. Bounded by construction, so it cannot turn into a hairball. Where an entity has no asserted relations it falls back to document co-occurrence, so it is never an empty canvas.	Starting from one name and seeing what surrounds it.
Network	An accumulating force layout that grows as you expand. The only view that shows structure across entities — clusters, bridges, shared neighbours.	Looking for shape rather than a specific answer. Prune it as you go.
Documents	A bipartite entity ↔ document view.	Answering why two entities are associated — the other two views assert the link, this one evidences it.

Every view is paired with a table of the same result. The canvas is for exploring; the table is the accessible, copy-pasteable, screenshot-friendly record you can paste into a ticket or a report.

Expansions are capped by the server, not by the browser — so the view stays responsive because it is never handed an unbounded graph in the first place.

Asserted relations vs co-occurrence

These are two different strengths of claim and the distinction matters:

• Related — an edge the model actually claimed from the text, such as WORKS_FOR. A real assertion, and the stronger signal.
• Co-occurring — the two entities appear in the same documents. This means "seen together", not "connected".

Co-occurrence is the only edge most entities have, which is why it is offered at all — but do not read it as a relationship.

Everything is access-trimmed

Entity results obey the same per-file security trimming as search. Two counts are reported and they legitimately disagree:

Count	Scope
visible_document_count	Documents this token can see.
mention_count	Tenant-wide total, not trimmed.

A user who can see one of an entity's forty documents sees 1 and 40. That is deliberate: the trimmed count tells them what they can open, and the total tells them the entity matters more widely than their access shows — without revealing anything about the documents themselves. The screenshot above shows both, side by side: 412 mentions · 5 documents you can read.

Fixing duplicates

Real corpora spell people several ways. "A. Smith", "Alice Smith" and "SMITH, ALICE" are one person, and a graph that treats them as three is worse than useless.

Merge folds one entity into another:

kdbl-control entities merge 482 --into 17

Merges are reversible. The folded entity is not rewritten or destroyed — it keeps a pointer to its new parent, and unmerge restores it:

kdbl-control entities unmerge 482

You can also merge directly from the Entities page, and list what was previously folded into an entity with entities merged <id>.

Reads are merge-aware: a set of entity ids assembled before a merge keeps working afterwards, because each id expands to its merge family. A saved query does not break because someone tidied up the vocabulary.

Asking across several entities at once

The intersection question — "which files put these three people in the same room?" — is a first-class query rather than something you assemble by hand:

kdbl-control entities intersect --ids 12,48,301

Like everything else here it is merge-aware and access-trimmed.

From a document, not an entity

The reverse lookup answers "what is this file about?":

kdbl-control entities by-file \
  --source "smbfs://nas/contracts" --key "2024/msa-acme.pdf"

The same information appears on the file detail page in the web console, so a file you found through ordinary search shows the entities it mentions, each linking to the Entities page.

Tuning what gets extracted

The default schema is tuned for enterprise documents — the entity and relation kinds that actually recur in contracts, policies, correspondence and reports.

You can override it per source when a source has its own vocabulary: in the web console, click Configure on the Entity enrichment step of the source's Smart Actions (its Configure tab) and fill in Entity types to look for and Relationship types to look for; or use the API. A legal archive and an engineering wiki do not want the same labels, and a schema that tries to serve both serves neither.

Per-document work is bounded — a character budget and a relation control — so one pathological file cannot consume the fleet. Both the budget and current enrichment coverage are visible from the API, the CLI and the web console (the Entity enrichment card on the source's Overview tab).

Generic words are not entities. "Company", "customers", "employees", "world" name nobody and nowhere, and every document mentions them, so they would connect everything to everything. They are never recorded as people, organisations or places; estates enriched before 0.1.41 are cleaned up by the graph's maintenance sweep without re-enrichment. Names in scripts without capital letters (Chinese, Japanese, Arabic) are judged by the list alone and kept.

Sizing the fleet — and why a large estate needs GPUs — is covered in the sizing guide.

CLI reference

Command	Answers
entities search	Find entities by name prefix and/or kind. With no filter, lists the most-mentioned — the useful "what is in here at all" starting point.
entities show <id>	One entity, with both document counts.
entities related <id>	Asserted relations. Degree-capped.
entities co-occurring <id>	Entities appearing in the same documents. Weaker claim — see above.
entities documents <id>	Documents mentioning it — the citation path. Access-trimmed.
entities intersect --ids …	Documents mentioning a set of entities.
entities by-file --source … --key …	What a document is about.
entities merge <id> --into <id>	Fold a duplicate away. Reversible.
entities unmerge <id>	Put it back.
entities merged <id>	What was folded into this one.
source enrich-coverage --source-id …	How much of a source has been enriched.

See the CLI reference for full flags, and the REST API for the same surface over HTTP.