
This blog is written by AI for SEO
How to Update an Ontology When Your Data Changes
To update an ontology schema safely, treat the ontology as a versioned artifact: draft the change as a new version, load it beside the current one, compare the two, and only then switch. Editing the live model in place is how AI agents and reports quietly break.
Most teams get the first ontology built and then stall in week two, when a CRM field gets renamed, a vendor table splits in two, or a contract PDF says something the billing table doesn't. This guide covers the general approach any team can follow, then shows how Helix Foundry handles each step. It also says plainly where a person still has to review.
Two kinds of change: schema change and data change
A schema change alters the shape of the model: a new type, a new link, a renamed property, an entity split in two or two merged into one. A data change alters what sits inside that shape: new rows, edited rows, documents that contradict each other.
Keep them apart. They fail differently and get fixed differently. A schema change needs a decision and a review. A data change should mostly flow in on its own. Mix them and you can't tell whether a wrong answer came from a bad model or a bad row.
A quick test: if the change would make you edit a query or an agent prompt, it's a schema change. If the same queries should keep working and just return fresher answers, it's a data change.
The general approach: version the ontology, stage it, compare, switch
Four moves work with any tool.
Version it. Every schema state gets an identifier, and old versions stay around so you can go back.
Stage it. Draft the new version without touching the one your agents and reports use today.
Load it beside the old one. Build the graph from the new version as a separate snapshot instead of mutating the existing graph.
Compare, then switch. Look at counts, added and removed records, and renamed ones. Only when the diff matches your intent do you point everything at the new version.
Loading beside the old one gives you rollback. If the new version is wrong, the old graph is still there, untouched. Teams that migrate in place learn about their mistakes from the people who consume the output.
Handling data change: new rows, edited rows and documents that disagree
New and edited rows are the easy case if your sync reads only what changed. In Helix Foundry, connections sync on a schedule. None of that needs a schema decision.
Documents are the hard case. A table says a contract renews in March and the PDF says April. Neither is a schema problem, but both break trust if the system silently picks one. Foundry keeps where every value came from, either a table row or a quote in a document, so a disagreement stays visible. Values that documents disagree on wait for your review instead of being written as settled fact.
The practical rule: let row changes flow automatically, and route contradictions to a human with the evidence next to them.
Updating the schema in Helix Foundry: draft, review, make a version current
In Foundry, the ontology agent drafts types, links and rules, plus the tables and documents each one comes from, based on your data and your goal.
A schema update runs like this:
Sync first. Make sure the new field or table is in the synced data the agent can see.
Generate a draft. Describe the change as part of your goal, for example that vendors now split into legal entity and billing account. The agent proposes a new version.
Review and edit. A version is a draft until you approve it. Read the types, links and rules, and fix what the agent got wrong.
Make it current. A load only uses the current version. Making an older version current again is how you roll back.
Editing creates a new version and leaves the old one alone, which is why the old graph and the new one can sit side by side. Connections do not write to the external sources they read, though Foundry writes loaded data to the Helix database.
If you are still deciding whether the model needs this much structure, Do You Need an Ontology? Five Signs Your Data Needs One covers that.
Comparing two loads side by side before you trust the new version
A load is a complete snapshot built from the current version, your synced tables and the documents you selected. The newest load that finishes Ready becomes current, and earlier loads are kept for comparison and rollback.
That is your staging step. Make the new version current, run a load, then open the load menu and compare it with the previous one. The Explorer shows the two side by side: counts of types and links, and records added, removed or renamed.
Read the diff against your intent:
A split entity should show new records of the new type and a matching drop in the old one.
A renamed property should show renamed records, not removed ones.
A link you added should show up in the link counts and nowhere surprising.
If the numbers don't match what you meant to change, you caught it before any agent or report read the new graph. Then check the load for items flagged for review. Rule breaks and conflicting document facts are listed there, and each one needs a decision.
Running Foundry and upgrading it without losing your graph
The self-hosted setup from the README is three commands:
git clone https://github.com/helixdb/helix-foundry.git
cd helix-foundry
docker compose up -d --waitThen open http://localhost:3000. You need Docker with Compose v2, ports 3000 and 8333 free, and room for a few GB of images on first start. The local install is for one person on their own computer, so don't expose it to a network. On Helix Cloud, use foundry.helix-db.com and choose Set up with your agent.
To upgrade a local install, run git pull && docker compose up -d --wait from the repository. Never run docker compose down -v. The -v flag removes the volumes, and your graph lives in them.
Foundry loads into HelixDB, the graph-vector database it is built on, so your ontology ends up as one connected graph your agents can query, with the source of each value kept.
Trade-offs: what still needs a person
Foundry drafts. It doesn't decide. Three things still need a human.
The draft. The agent proposes types, links and rules, and someone has to read them. A wrong link that looks plausible is worse than a missing one.
The contradictions. When a document and a table disagree, you choose: keep a value, replace a table value with a documented one, approve a claim or reject it. Foundry surfaces the conflict with the evidence, but the call is yours.
The diff. The comparison shows what changed, not whether it was supposed to. Only you know that a drop of 40 records in one type is the intended merge and not a mapping that lost them.
Budget review time per schema change. It costs far less than debugging an agent that has been reasoning over a bad model for two weeks.
Stage every schema change, and keep the old load until you trust the new one
Updating an ontology is safe when the old version stays intact until the new one has earned its place. Draft, review, load beside the current graph, compare, then switch, and keep the previous load around for rollback. To try it on your own data, clone helix-foundry from GitHub, run docker compose up -d --wait, and make your next schema change as a new version instead of an edit.