Knowledge Graph Ontology
Control which entities and relations Knowledge Graph extracts, auto-discover a project-specific ontology from sample files, and evolve it together with the graph data.
An ontology is the schema of a project's knowledge graph: the entity types to look for, the relation types that connect them, and which entity types each relation is allowed to connect. Ingestion only extracts entities and relations that fit the project's ontology, so the ontology decides what the graph contains and which questions it answers well.
Every project starts with a generic default ontology. To tailor extraction to your own documents, for example to find Contract, Party, and Clause entities in legal documents, let the server draft a project-specific ontology from a few sample files, review and edit the draft, and approve it. To rename, drop, or extend types the project already uses, and update the data the graph already holds in the same step, evolve the ontology.
Ontology Structure
GET /v1/graph/ontology returns, and PUT /v1/graph/ontology/draft accepts, ontologies in GraphRAG-SDK's own Ontology JSON shape:
{
"entities": [
{
"label": "Person",
"description": "A named individual (author, employee, participant, contact).",
"properties": [
{ "name": "role", "type": "STRING", "description": "Job title or role." }
]
},
{
"label": "Organization",
"description": "A company, agency, team, or other named group entity.",
"properties": []
}
],
"relations": [
{
"label": "WORKS_FOR",
"description": "Person is employed by or affiliated with an Organization.",
"patterns": [["Person", "Organization"]],
"properties": [
{ "name": "start_date", "type": "DATE", "description": "When the employment started." }
]
}
]
}| Field | Description |
|---|---|
entities[].label | Name of the entity type, for example Person. GLiNER receives these labels as the entity types to look for. |
entities[].description | What counts as this entity type. The extraction prompts include it, so a precise description improves extraction. |
relations[].label | Name of the relation type, for example WORKS_FOR. |
relations[].description | What the relation means. |
relations[].patterns | Allowed [source label, target label] pairs. The extractor drops relations whose entity types match none of the pairs, and reports them in the ingestion job's warnings. An empty list, as on RELATED_TO, allows any pair. |
properties | Typed properties the extractor captures on an entity or a relation. |
properties[].name | Property name in snake_case, such as role or founded_year. See Draft Sanitization. |
properties[].type | One of STRING, INTEGER, FLOAT, BOOLEAN, DATE, or LIST. Defaults to STRING. |
Every entity also carries a name property that GraphRAG-SDK manages itself, whether or not the ontology declares it. Do not use Document or Chunk as a label: GraphRAG-SDK uses them for its own nodes.
Default Ontology
A project uses the default ontology until it saves or approves its own. The default declares no properties.
| Entity Type | Description |
|---|---|
Person | A named individual: author, employee, participant, or contact. |
Organization | A company, agency, team, or other named group. |
Technology | A named technology, platform, framework, or standard. |
Product | A named product, service, or deliverable. |
Location | A named place: city, country, region, address, or venue. |
Date | A specific date, time, or date range. |
Event | A named occurrence: meeting, release, incident, milestone, or transaction. |
Concept | An abstract idea, topic, category, or named process. |
Law | A named law, regulation, standard, contract clause, or policy. |
Dataset | A named collection of data. |
Method | A named technique, algorithm, or procedure. |
| Relation Type | Allowed Patterns |
|---|---|
WORKS_FOR | Person → Organization |
LOCATED_IN | Organization, Person, Event, Product, or Location → Location |
PART_OF | Organization → Organization, Product → Organization, Technology → Product, Concept → Concept, Location → Location |
CREATED_BY | Product, Technology, or Dataset → Organization or Person |
USES | Organization → Technology or Product, Method → Technology, Product → Technology |
PARTICIPATED_IN | Person or Organization → Event |
OCCURRED_ON | Event → Date |
GOVERNED_BY | Organization, Product, Event, or Concept → Law |
COLLABORATES_WITH | Organization → Organization, Person → Person |
RELATED_TO | Any pair. A fallback for relevant associations that fit no other relation. |
Ontology Lifecycle
Each project has at most one ontology record, which holds two ontologies:
ontologyis the current draft. Discovery writes it, and you edit it.approved_ontologyis the active ontology, which ingestion, search, and completion use. It staysnull, and the project keeps using the default ontology, until you save or approve a draft.
The record's state is one of the following:
| State | Meaning | Next Steps |
|---|---|---|
discovering | Discovery is running. | Poll GET /v1/graph/ontology, or cancel. |
draft | Discovery finished, or you saved an edited draft. | Edit, approve, or propose again. |
approved | You approved the draft. | Propose again to change the ontology. |
failed | Discovery failed. last_error says why. | Edit the previous draft, or propose again. |
cancelled | You cancelled discovery. | Propose again. |
The typical flow is:
Upload a few representative files with POST /v1/files.
Start discovery with POST /v1/graph/ontology/propose.
Poll GET /v1/graph/ontology until state is draft.
Review ontology, and edit it with PUT /v1/graph/ontology/draft if needed.
Approve the draft with POST /v1/graph/ontology/approve.
Ingest your files. To apply the new ontology to files you ingested earlier, ingest them again with ?force=true.
Saving or approving a draft never changes what the graph already contains. Entities and relations
extracted under the previous ontology stay in the graph until you ingest their files again with
POST /v1/graph/files/{file_id}/ingest?force=true. To rename or drop types together with their
data, or to fill new types and properties from data the graph already holds, apply
ontology changes instead.
Discover an Ontology
Pass 1 to 10 file IDs of already uploaded files, and an optional boundaries hint:
curl -X 'POST' \
'https://deepfellow-server-host/v1/graph/ontology/propose' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"file_ids": ["FILE_ID_1", "FILE_ID_2"],
"boundaries": "legal contracts"
}'The endpoint returns 202 Accepted:
{
"status": "discovering",
"ontology_id": "68da445c5186deb8bca2bdeb"
}| Field | Description |
|---|---|
file_ids | 1 to graph.ontology_discovery_max_sample_files file IDs. The limit defaults to, and never exceeds, 10. A longer list returns 422 Unprocessable Entity. |
boundaries | Optional free-text hint that narrows the scope of the ontology, such as a document type or a domain. |
Discovery runs in the background:
The server converts each sample file with Doc Chunker, through the same pipeline ingestion uses, so discovery reads the same text that ingestion will.
The server picks graph.ontology_discovery_sample_chunks_per_doc chunks from each file, spread evenly from its beginning to its end.
graph.ontology_discovery_llm_model proposes entity and relation types from each sampled chunk, running up to graph.ontology_discovery_concurrency calls in parallel. The prompts use the starting ontology as a vocabulary to build on.
GraphRAG-SDK merges the proposals across files, collapses synonyms, and merges the result into the starting ontology.
The server cleans up the result and stores it as the draft.
The starting ontology is the project's approved ontology, or the default ontology if the project has none. The draft therefore always contains every type the project already uses, plus the types discovery added, so proposing again never drops a type you approved earlier. The same files always yield the same sampled chunks. The LLM's answers still vary between runs, so two runs over the same files produce similar but not always identical drafts.
propose overwrites the current draft once discovery finishes, and returns 409 Conflict while discovery is already running for the project. The active ontology stays untouched until you save or approve the new draft.
Choose sample files that cover the kinds of documents the project will hold. Since discovery reads
only a few chunks per file, several short, varied files give it more to work with than one long
file. To draft ontologies faster, or at a lower cost, set graph.ontology_discovery_llm_model to
a different model than graph.llm_model.
Check Discovery Progress
curl -X 'GET' \
'https://deepfellow-server-host/v1/graph/ontology' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY"Response:
{
"id": "68da445c5186deb8bca2bdeb",
"project_id": "68da445c5186deb8bca2bdec",
"state": "draft",
"ontology": {
"entities": [
{ "label": "Person", "description": "A named individual (author, employee, participant, contact).", "properties": [] },
{ "label": "Contract", "description": "A legally binding agreement between parties.", "properties": [
{ "name": "effective_date", "type": "DATE", "description": "Date the contract takes effect." }
] }
],
"relations": [
{ "label": "PARTY_TO", "description": "An organization or person that signed a contract.", "patterns": [["Organization", "Contract"], ["Person", "Contract"]], "properties": [] }
]
},
"approved_ontology": null,
"source_file_ids": ["FILE_ID_1", "FILE_ID_2"],
"boundaries": "legal contracts",
"last_error": null,
"warnings": [],
"evolution_policy": "manual",
"proposed_changes": [],
"created_at": "2026-08-03T10:00:00Z",
"updated_at": "2026-08-03T10:05:00Z"
}The example shortens ontology for readability. A real draft also lists every type of the default ontology.
GET /v1/graph/ontology returns 404 Not Found until the project runs discovery for the first time. While state is discovering, ontology still holds the previous draft, or null on a first run.
evolution_policy is the project's evolution policy. proposed_changes is only filled in the responses to saving and approving a draft: see Compatibility with Ingested Data.
warnings lists the discovery steps that failed without failing the whole discovery, for example a sampled chunk the LLM returned no valid proposal for, or a skipped synonym-merging pass. The draft is still usable, but it reflects less of your files. Each new propose clears the list.
Cancel Discovery
curl -X 'POST' \
'https://deepfellow-server-host/v1/graph/ontology/cancel' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY"Cancelling sets state to cancelled and returns the ontology record. It returns 409 Conflict if state is not discovering. Nightshift skips a queued discovery that has not started yet. Cancellation does not interrupt a discovery that is already running: once it finishes, it still stores its draft and sets state to draft. To start over, propose again.
Discovery Failures
The server retries each LLM call that fails, for example on a rate limit or a temporary DeepFellow Infra error, up to graph.ontology_discovery_llm_call_attempts times, waiting 1, 2, 4, and more seconds between attempts.
A discovery fails in the following cases:
- A sample file does not belong to the project or cannot be converted.
- An LLM call still fails after its last attempt.
- Sampling yields no text from the sample files.
- Every sampled chunk failed to produce a proposal. Discovery then has nothing to add to the starting ontology.
state becomes failed, and last_error holds the error. Nightshift first retries discovery with backoff until it reaches graph.ontology_discovery_max_attempts deliveries. After that, propose again to retry.
Edit the Draft
Replace the draft with an edited ontology:
curl -X 'PUT' \
'https://deepfellow-server-host/v1/graph/ontology/draft' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"ontology": {
"entities": [
{ "label": "Contract", "description": "A legally binding agreement between parties.", "properties": [] },
{ "label": "Organization", "description": "A company, agency, team, or other named group.", "properties": [] }
],
"relations": [
{ "label": "PARTY_TO", "description": "An organization that signed a contract.", "patterns": [["Organization", "Contract"]], "properties": [] }
]
}
}'Send the complete ontology every time. The request replaces the draft as a whole, so any type you leave out is removed from the draft. If the project already uses that type, the type stays active, and the response proposes a change that drops it. See Compatibility with Ingested Data.
Saving a draft takes effect at once: the server writes the draft to ontology, applies what it
adds, and writes the resulting active ontology to approved_ontology. The next ingested document
already uses it. Approval is not required for an edit to take effect.
Before the server stores the draft, it runs the same compatibility check as approval, so an edit never breaks ingestion or search. The endpoint returns the updated ontology record with state set to draft, or one of these errors:
| Status | Cause |
|---|---|
404 Not Found | The project never ran discovery. Propose first. |
409 Conflict | state is discovering, approved, or cancelled. Only a draft or failed ontology accepts edits. |
409 Conflict | One of the draft's additions failed to apply. The additions before it stay applied, the ones after it become proposed changes, and the draft is not saved. |
409 Conflict | The draft changes the type of a property FalkorDB already holds for the project. |
422 Unprocessable Entity | The body is not a valid Ontology, for example a property with an unknown type. |
503 Service Unavailable | The server could not read the project's active ontology. Try again later. |
To change an approved ontology, propose again, then edit and approve the new draft, or apply ontology changes directly.
Approve the Draft
curl -X 'POST' \
'https://deepfellow-server-host/v1/graph/ontology/approve' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY"Approval runs the compatibility check, applies what the draft adds, writes the resulting active ontology to approved_ontology, sets state to approved, and returns the ontology record. It returns 404 Not Found if the project never ran discovery, 409 Conflict if state is not draft or if the check fails, and 503 Service Unavailable if the server cannot read the project's active ontology.
Since a saved draft is already active, approval mostly marks the ontology as final. After approval, the draft no longer accepts edits until the next propose.
Compatibility with Ingested Data
FalkorDB keeps a copy of each project's ontology, which grows as the project ingests documents. This copy is the active ontology: ingestion, search, and completion use it, and approved_ontology mirrors it. Saving or approving a draft compares the draft against that copy:
- Additions are applied. A new entity type, relation type, property, or relation pattern, and a changed non-empty description, is applied at once as an ontology change with
originset todiscovery. Each applied change records a new version. The data already in the graph does not change. - Removals are proposed. A type, relation pattern, or entity property that the draft leaves out stays active. The response lists a
proposedchange that drops it inproposed_changes. Review and apply it like any other change. Saving the same draft again returns the same proposed changes instead of new copies. - Retyped properties are rejected. A property that keeps its name but changes its
typeon an existing entity or relation type, for examplefounded_yearfromINTEGERtoSTRING, would leave the data already in the graph inconsistent with the new schema. The request returns409 Conflict, and nothing changes.
A project that has not ingested anything yet has no copy in FalkorDB. It passes the check with any draft, and the draft becomes the active ontology as it is, removals included. The 409 Conflict error message lists every conflict, for example:
{
"error": {
"message": "Ontology conflicts with the already-registered ontology: Entity 'Organization': property 'founded_year' type change INTEGER -> STRING not allowed.",
"type": "invalid_request_error",
"param": null,
"code": null
}
}To resolve a conflict, keep the property's original type, or give the property a new name. To change the type of an entity property the graph already holds, drop it and add it again.
Evolve the Ontology
Ontology changes rename, drop, add, or describe the types of an ontology the project already uses, and update the data the graph already holds in the same step, without ingesting files again. You review each change before it runs, and every applied change records a new version of the ontology.
Change Types
Each change has a payload whose op field names the change type. The change types call a property an attribute:
op | Other payload Fields | Effect on Data Already in the Graph | risk |
|---|---|---|---|
add_entity | label, description, properties | None. With backfill set to all, the LLM scans every chunk of the graph for entities of the new type. | additive |
add_relation_pattern | relation, source, target, description (used only when relation is new) | None. Omit both source and target to add a relation type that connects any pair. | additive |
add_attribute | owner, attribute (name, type, description) | None. With backfill set to all, the LLM fills the value on existing entities of the owner type. | additive |
set_description | kind (entity, relation, or attribute), label (the owner when kind is attribute), attribute (required when kind is attribute), description | None. | additive |
rename_entity | old, new | Relabels the type's entities. | migrating |
rename_relation | old, new | Renames the type of the relations. | migrating |
rename_attribute | owner, old, new | Renames the property on the owner's entities. | migrating |
drop_entity | label | Deletes the type's entities, their relations, and every relation pattern that references the type. | destructive |
drop_relation | label | Deletes every relation of the type. | destructive |
drop_relation_pattern | relation, source, target | Deletes the relations of the type between the two entity types only. | destructive |
drop_attribute | owner, name | Removes the property from the owner's entities. | destructive |
The server sets risk from op, and rejects the following changes with 422 Unprocessable Entity:
- Renaming a type to the name of another existing type, which would merge the two types
- Renaming or dropping a property of a relation type
backfillset toallon any change other thanadd_entity, oradd_attributeon an entity type- A change that references a type, property, or relation pattern the ontology does not have, or that adds one it already has
- A type name that the knowledge graph needs for its own structure:
Chunk,Document, and__Entity__as entity types, andRELATES,MENTIONED_IN,PART_OF, andNEXT_CHUNKas relation types - A property name that is not in
snake_case, or that the knowledge graph reserves:name,description,source_chunk_ids,spans,rel_type,fact,src_name,tgt_name,id, andlabel - Dropping the last entity type of the ontology
Relation properties are only added. The reserved relation types include PART_OF of the default ontology. Renaming or dropping it as a whole returns 422. Adding patterns to it works.
To change the type of an entity property, drop the property and add it again with the new type. The values come back only if the new property uses backfill set to all. A relation property cannot be changed this way, since relation properties are only added.
Review and Apply Changes
The typical flow is:
Create a change with POST /v1/graph/ontology/changes.
Preview what it touches with POST /v1/graph/ontology/changes/{change_id}/dry-run.
Accept it with PATCH /v1/graph/ontology/changes/{change_id}.
Apply accepted changes with POST /v1/graph/ontology/changes/apply.
Poll GET /v1/graph/ontology/changes/{change_id} until status is applied or failed.
Create a change:
curl -X 'POST' \
'https://deepfellow-server-host/v1/graph/ontology/changes' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"payload": { "op": "rename_entity", "old": "Organization", "new": "Company" },
"backfill": "none"
}'The endpoint returns 201 Created with the change:
{
"id": "68da445c5186deb8bca2bdf0",
"project_id": "68da445c5186deb8bca2bdec",
"op": "rename_entity",
"payload": { "op": "rename_entity", "old": "Organization", "new": "Company" },
"risk": "migrating",
"origin": "user",
"backfill": "none",
"status": "proposed",
"inverse_of": null,
"data_not_restored": false,
"dry_run": null,
"result": null,
"error": null,
"applied_version": null,
"created_at": "2026-10-20T10:00:00Z",
"updated_at": "2026-10-20T10:00:00Z"
}status | Meaning |
|---|---|
proposed | Waiting for review. You, a draft save or approval, or a restore created it. |
accepted | Ready to apply. |
rejected | Not applied. Accept it to apply it later. |
applying | Queued or running in Nightshift. A change whose updated_at is older than graph.ontology_evolution_abandoned_after_seconds counts as abandoned. See Accept, Reject, or Edit a Change. |
applied | Applied. applied_version is the version it created, and result counts what it changed. |
failed | Not applied, or applied only in part. error says why. |
GET /v1/graph/ontology/changes lists the project's changes, oldest first. To list only the changes with one status, add ?status=proposed, or another status.
An unknown change_id returns 404 Not Found from GET, PATCH, and the dry run. Creating a change, or editing its payload, returns 503 Service Unavailable if the server cannot read the project's active ontology.
Preview a Change
The dry run counts what the change would touch, stores the counts in dry_run, and changes nothing:
{
"dry_run": {
"chunks_in_scope": 0,
"affected_nodes": 42,
"affected_edges": 17
}
}chunks_in_scope is the number of chunks a backfill scans. The LLM receives one call per chunk, so this is the cost of the backfill. affected_nodes and affected_edges count the entities and relations a rename or drop changes. The dry run of an applying or applied change returns 409 Conflict.
Accept, Reject, or Edit a Change
curl -X 'PATCH' \
'https://deepfellow-server-host/v1/graph/ontology/changes/CHANGE_ID' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "status": "accepted" }'Set status to accepted or rejected. To edit a change, send a new payload or backfill. The change goes back to proposed, and the server clears its dry run. Only a proposed, accepted, rejected, failed, or abandoned change accepts this request. Other changes return 409 Conflict. An abandoned change is an applying change whose updated_at is older than graph.ontology_evolution_abandoned_after_seconds, for example after a lost queue message. To apply an abandoned change, accept it and apply it again. A change is safe to apply again.
A change with backfill set to all is accepted only after a dry run. If the dry run counts more chunks than graph.ontology_evolution_max_backfill_chunks, accepting it returns 422 Unprocessable Entity. Creating an add_entity change with backfill set to all returns 422 Unprocessable Entity unless graph.ontology_evolution_entity_backfill is true.
Apply Changes
curl -X 'POST' \
'https://deepfellow-server-host/v1/graph/ontology/changes/apply' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"change_ids": ["CHANGE_ID_1", "CHANGE_ID_2"],
"confirm_destructive": true
}'The endpoint sets the changes to applying, queues them, and returns 202 Accepted:
{
"status": "applying",
"change_ids": ["CHANGE_ID_1", "CHANGE_ID_2"]
}It returns 404 Not Found if a change does not exist, 409 Conflict if a change is not accepted, 422 Unprocessable Entity if a change is destructive and confirm_destructive is not true, and 503 Service Unavailable with a Retry-After header if RabbitMQ is unavailable.
A destructive change deletes graph data, and restoring a version never brings that data back.
Before you apply a drop, run a dry run and check affected_nodes and affected_edges.
Nightshift applies the changes on the ontology_evolution queue, in the order you created them. While it applies them, Knowledge Graph ingestion of the project waits. Every document ingested afterward uses the new ontology.
If a change fails to apply, it becomes failed. The changes after it go back to accepted, and the changes before it stay applied. If an infrastructure error stops Nightshift, for example when FalkorDB is unavailable, Nightshift tries the request again, up to 3 times in total. After the last attempt, every change of the request that is not applied yet becomes failed, and error says why. A failed backfill lists the chunks it did not finish in result.failed_chunks.
To retry a failed change, accept it and apply it again. Changes are safe to apply again, and a backfill skips the chunks it already finished.
Whether files ingested earlier need to be ingested again depends on the change:
| Change | Files Ingested Earlier |
|---|---|
| Rename, drop, or description change | The change updates their data itself. ?force=true does not extract them again because of it. |
Addition with backfill set to all | The backfill updates their data itself. ?force=true does not extract them again because of it. |
Addition with backfill set to none, including every addition a draft save or approval applies | Their data stays as it was. To extract them with the new ontology, ingest them again with POST /v1/graph/files/{file_id}/ingest?force=true. |
A file that an addition left extracted with an older ontology stays that way after a later rename, drop, description change, or backfill, so ?force=true still extracts it again.
Ontology Versions
Every applied change records a new version of the ontology. Version 1 is the ontology the project used before its first applied change.
curl -X 'GET' \
'https://deepfellow-server-host/v1/graph/ontology/versions' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY"The response lists the versions, newest first:
[
{
"version": 2,
"snapshot": { "entities": [], "relations": [] },
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"change_id": "68da445c5186deb8bca2bdf0",
"created_at": "2026-10-20T10:05:00Z"
},
{
"version": 1,
"snapshot": { "entities": [], "relations": [] },
"fingerprint": "60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752",
"change_id": null,
"created_at": "2026-10-20T10:05:00Z"
}
]The example shortens snapshot, which holds the whole ontology of the version. change_id is the change that created the version. GET /v1/graph/ontology/versions/{version} returns one version, or 404 Not Found.
Restore a Version
curl -X 'POST' \
'https://deepfellow-server-host/v1/graph/ontology/versions/1/restore' \
-H "Authorization: Bearer DEEPFELLOW_PROJECT_API_KEY"Restoring a version applies nothing. It creates proposed changes that undo every change applied after the version, newest first, with origin set to restore and inverse_of set to the change each one undoes:
{
"changes": [
{
"id": "68da445c5186deb8bca2bdf3",
"op": "rename_entity",
"payload": { "op": "rename_entity", "old": "Company", "new": "Organization" },
"origin": "restore",
"inverse_of": "68da445c5186deb8bca2bdf0",
"data_not_restored": false,
"status": "proposed"
}
],
"data_not_restored": []
}The example shortens each change. Accept and apply the changes like any others. Undoing a drop adds the type or property back, but not the data the drop deleted: such changes have data_not_restored set to true, and the response lists their IDs in data_not_restored. The request returns 404 Not Found if the version does not exist. If a relation property was added after the version, the request returns 422 Unprocessable Entity, since relation properties are never dropped.
Evolution Policy
GET /v1/graph/ontology/policy returns, and PUT /v1/graph/ontology/policy sets, the project's evolution policy:
{ "policy": "manual" }policy is manual or auto_additive, and defaults to manual. The policy is reserved for automatic proposals of ontology additions. Currently, it has no effect: every change waits for review, except the additions that a draft save or approval applies.
Draft Cleanup
When discovery finishes, the server cleans up the draft before it stores it.
Draft Sanitization
Discovery LLMs occasionally propose a value they saw in the text, such as John Smith or 1976, as a property name. The server drops every property whose name does not match ^[a-z][a-z0-9_]*$: a lowercase letter followed by lowercase letters, digits, or underscores. It sanitizes the draft when discovery finishes, when you save a draft, and when you approve one, and it drops such properties silently, without an error.
Near-Duplicate Types
If a new type's name differs from an existing one only by letter case, punctuation, or a plural ending, such as Organizations or organization next to Organization, the server merges the new type into the existing one. Its properties and relation patterns move to the existing type. The types of the starting ontology always keep their names, and the server never merges them into each other, even if two of them differ only this way. Between two new types, the first one discovery proposed keeps its name. The check covers regular English plurals only, so the server does not merge People into Person.
Definitions of Known Types
GraphRAG-SDK's synonym-merging pass sometimes rewrites the descriptions of types the starting ontology already has, or changes the type of their properties. The server restores the original descriptions, since the extraction prompts rely on them, and the original property types and descriptions, so approving the draft never fails the compatibility check on a property you did not change. New properties that discovery adds to a known type stay in the draft.
Limits on New Types
If graph.ontology_discovery_max_new_entities or graph.ontology_discovery_max_new_relations is above 0, the draft keeps at most that many new entity or relation types. Types of the starting ontology never count toward the limit. The server keeps the new entity types that the most relation patterns reference, and the new relation types with the most patterns. The server removes the relation patterns that reference a dropped entity type, and drops a new relation type left with no patterns.
Use the Web UI
Open the project details page and click Ontology in the Toolboxes section header. The page has three parts:
- Choose sample files. Select up to 10 of the project's files, enter optional Boundaries, and click Propose. While discovery runs, the page refreshes by itself and shows a Cancel button. If you have unsaved edits, the page asks for confirmation first, since the new draft will overwrite them.
- Review & edit draft. Add, edit, and remove entities, relations, patterns, and properties. Save draft saves your edits and makes them active at once. Approve is enabled only for a saved draft in the
draftstate. - Approved ontology. Lists the labels of the active ontology, and notes when a newer draft exists.
Configuration
These are dynamic settings. See Knowledge Graph Settings for the full list.
| Setting | Description | Default |
|---|---|---|
graph.ontology_discovery_llm_model | Model on DeepFellow Infra that drafts ontologies. Independent of graph.llm_model. | gpt-4o-mini |
graph.ontology_discovery_sample_chunks_per_doc | Number of chunks sampled from each sample file. | 3 |
graph.ontology_discovery_concurrency | Number of LLM calls discovery runs in parallel. | 4 |
graph.ontology_discovery_max_sample_files | Maximum number of sample files per discovery. Values above 10 have no effect. | 10 |
graph.ontology_discovery_max_attempts | Nightshift deliveries a discovery gets before its state becomes failed. | 3 |
graph.ontology_discovery_llm_call_attempts | Attempts each discovery LLM call gets before it fails. At least 1. | 4 |
graph.ontology_discovery_max_new_entities | Maximum number of new entity types one discovery adds. 0 means no limit. | 0 |
graph.ontology_discovery_max_new_relations | Maximum number of new relation types one discovery adds. 0 means no limit. | 0 |
graph.ontology_evolution_max_backfill_chunks | Maximum number of chunks one ontology change backfills. A change over the limit is not accepted. 0 means no limit. | 5000 |
graph.ontology_evolution_entity_backfill | Allows add_entity changes with backfill set to all. | false |
graph.ontology_evolution_abandoned_after_seconds | Seconds, at least 60, after which a change that is still applying counts as abandoned. Nightshift updates a change when it starts applying it, so set this above the time your longest backfill takes. See Accept, Reject, or Edit a Change. | 21600 |
We use cookies on our website. We use them to ensure proper functioning of the site and, if you agree, for purposes such as analytics, marketing, and targeting ads.