Skip to main content

Overview

Taxonomies provide structured, hierarchical vocabularies for classifying and categorizing entities in the knowledge graph. They help ensure consistent tagging and enable structured browsing of your organization’s knowledge. Navigate to Model & Define > Taxonomies.

Viewing Taxonomies

The taxonomies page displays a hierarchical tree table showing:
  • Taxonomy name
  • Parent-child relationships
  • Full path from root to leaf
  • Associated synonyms
  • Status information
You can filter taxonomies by type to focus on a specific classification system.

Creating Taxonomies

Click Add New Taxonomy to create a new entry:

Hierarchical Structure

Taxonomies support unlimited nesting depth. For example:

Type-Specific Views

Click on a taxonomy type in the sidebar to see a filtered view showing only taxonomies of that type. This provides a focused view for managing a single classification system.

Synonyms

Each taxonomy entry can have multiple synonyms — alternative terms that the AI treats as equivalent during classification. For example:
  • Healthcare → “Health Care”, “HC”, “Medical”
  • Federal → “Fed”, “US Government”, “USG”
Synonyms improve classification accuracy by helping the AI recognize variations in terminology.

Managing Taxonomies

Editing

Click any taxonomy entry to edit its name, parent, type, or synonyms.

Deleting

Remove taxonomy entries that are no longer needed. Deleting a parent entry also deletes every entry under it, so move any children you want to keep first. On the taxonomies list, a row’s Delete removes the whole taxonomy and every term in it. It asks first: the dialog names the taxonomy and how many terms go with it, says that instructions using its @tag then list nothing, and enables Delete only after you type delete. Cancel deletes nothing.
Build your taxonomy before ingesting documents. The AI uses taxonomies during classification, so having a well-defined vocabulary from the start produces better results.

Asking the copilot

The Admin Copilot has a page pack for the taxonomy list and each taxonomy’s page. Open it with the Copilot button or ⌘J. It knows the saved ontology, the other knowledge-model pages and the files you attach in the chat (see The knowledge-model copilot). It can explain a taxonomy and what its @tag expands to, check it, and propose changes as a card: These cards change the terms of a taxonomy. None of them creates, renames or deletes a taxonomy type. Creating and deleting a taxonomy are page-action cards that you confirm on the list; renaming one stays with the list’s own Rename.

Draft mode

Every other action on a taxonomy’s page writes at once. A copilot card doesn’t: applying it stages a draft, which you save in one step.
  • Apply stages the card’s changes over the saved tree (Staged as a draft — nothing is saved until you click Save changes). The tree shows the draft, and each changed term is marked Added, Renamed (with its old name), Moved, Status changed, Description changed or Removed (struck through).
  • A banner counts the staged changes (2 staged changes, not saved) and offers Save changes and Discard.
  • Save changes writes the whole draft in one go: every change is saved, or none. It is refused if the taxonomy was saved since the draft was made (This taxonomy was saved since the draft was made. Reload it, check the draft and Save again.). The draft stays, drawn over the latest saved tree: check it and click Save changes again.
  • Discard drops the draft and shows the saved tree again.
  • While a draft is open, the tree’s own edits wait: the row actions (add, edit, delete) are hidden and Upload CSV is disabled until you save or discard the draft.
  • The draft is kept only while the page is open: reloading or leaving the page drops it.
  • A card holds the whole draft as it would be after the change, so applying it replaces the draft. If the draft changed since the card was made, Apply asks first. Undo on the card puts the earlier draft back, while the draft still holds what the card staged.
Save refuses a draft in which two terms under one parent share a name (the top level included), a name holds a , or > (the CSV import splits on them), a name or a description holds a NUL character, or a term moves under itself or one of its own terms. The copilot checks the same rules before you see a card.

What the card warns about

@TaxonomyName tags in extraction instructions and enrichment prompts expand to the active leaves only. A card warns you before Apply when:
  • a term that was an active leaf gets an active term under it, so the tag stops listing it;
  • the taxonomy is left with no active leaf, so the tag expands to nothing (the warning names where the tag is used);
  • a removal takes the terms under it too.

Filling a taxonomy from an attached CSV

Attach a CSV of terms in the chat and ask the copilot to fill a taxonomy with it. The copilot does not retype the rows: the server reads the file the way the page’s Upload CSV reads it, and the card holds the terms. Apply stages them as a draft like any other card, and Save changes writes them. The first row decides how the file is read: A status of active or inactive is read as written; any other value is read as active, and the card says so.
  • Slices. One card holds up to the card’s edit limit (Max edits per proposal, 150 by default; one draft holds at most 500 changes). The card is headed Import rows 1-150 of 405 of “industries.csv”: 150 new terms and names where the next slice starts. Apply it and click Save changes, then say “continue”, and the copilot reads the next slice. Terms already saved don’t use up room, so asking again from the start moves straight on to the rows that are still new.
  • A term already there is skipped. Terms are matched ignoring case, and a term the taxonomy already has is left as it is: its description and status are not overwritten. The card counts them (Left as they are). A parent a row implies but the file never lists is added first.
  • Rows that can’t be imported are listed, never dropped quietly. The card names each one by row number and text, with the reason (Not imported: row 14 “…”): a , or > inside a name (the CSV import splits on them), a name over 255 characters, a tab or line break in a name, more values than the header has columns, or a last row cut off. The rest of the file still imports.
  • What the copilot refuses to read. A file that is still being read or failed, one that isn’t CSV rows (.json, .pdf), and an Excel file (export it as CSV). A .csv or .txt whose columns are separated by tabs or semicolons is refused too, because the import reads only commas: ask for a comma-separated copy, or paste the terms. No card is made, and the copilot says why.
How this differs from the page’s Upload CSV, on a taxonomy’s own page: The page’s import can also run in a replace mode through the API. It now reads and checks the whole file before it deletes anything, and an empty or unreadable file, or one with no importable row, is refused with the taxonomy untouched. The page itself always merges.

Creating and deleting a taxonomy from a card

Two actions that are not edits of a taxonomy’s terms come as a page-action card, made for the Taxonomies list from any knowledge-model page and confirmed by you there (see Page-action cards). The copilot performs neither.
  • Create a taxonomy. Ask for a taxonomy by name, with a description if you like. Apply on the list opens a confirmation whose button, Open Add New Taxonomy, opens the page’s own Add New Taxonomy dialog with the name and description filled in. Check them (they stay editable) and click Create. The taxonomy is created with no terms: add them by hand, from a term card or from a CSV. Closing the dialog creates nothing and leaves the card open. A name a taxonomy already has, or one that gives no usable slug (empty, or over 64 characters), gets no card.
  • Delete a taxonomy. The card is marked destructive. Its Also affected lines count the terms that go with the taxonomy (active and inactive, with the top-level ones named) and say where its @tag is used (the saved ontology, artifact types and, if you can read rules, enrichment rules), which then expands to nothing. Someone who can’t read enrichment rules is told they were not checked. The confirmation reads Delete taxonomy, and it deletes the taxonomy and every term, as the list’s Delete does. It is refused when a term was added, edited or removed since the card was made. There is no undo.

Cards made on another page

On the taxonomy list and the other knowledge-model pages (Ontology, Artifact Types, Data Mapping, Enrichment Rules and Matching Strategies), the copilot makes a card for the taxonomy you name, built on its saved tree:
  • The card reads Made for “Industries” (Taxonomies) and has an Open “Industries” button. It opens that taxonomy’s page, where you apply the card and click Save changes.
  • It is refused once the taxonomy has been saved since the card was made (This taxonomy was saved since this was proposed — ask the copilot again.). If the page holds a draft, Apply asks first, because the card replaces it.
  • A taxonomy doesn’t depend on the ontology, so saving the ontology doesn’t affect these cards.
Proposing and Save changes need the Graph Managers role with write access, and so do the create and delete cards. The copilot never saves a draft or deletes a taxonomy: Save changes and your own confirm on a delete card are the only writers. After you save a draft that holds a copilot card, the copilot points you to the next taxonomy card still open, if there is one, without calling the model. Taxonomies are also used in Enrichment Rules via the @TaxonomyName syntax. When you reference a taxonomy in an enrichment prompt (e.g., @Domain), the system expands it to the full list of values, helping the LLM classify and tag nodes consistently.