Bind an ontology to a database

A database binding connects your ontology’s business vocabulary to real tables in an external database: SQL Server, PostgreSQL, MySQL, Databricks, Fabric Warehouse, or Fabric Lakehouse. You map classes to tables, attributes to columns, and relationships to joins. The Data Agent and the ontology’s MCP server then use those bindings to answer questions against live data.

In the app: Data Context › Ontologies › your ontology › More › Bind to Database

[screenshot]

Before you start¶

• The Bind to Database feature must be on for your organization. It’s included in the Trial, Business, and Enterprise plans. On other plans an organization admin turns it on under Organization Settings › Features. When it’s off, Bind to Database doesn’t appear in the More menu, and the page shows Bind to Database isn't enabled. See Feature flags.
• Your organization needs a database connection. If there are none, the workspace says No database connections yet, and admins get an Add a database connection button. See Add a database connection.
• You need Read/Write access to stage and save bindings. With Read Only access every control is visible but disabled.
• An ontology binds to a database or to a lakehouse, never both. If the ontology already has a lakehouse binding environment, Bind to Database is disabled with the tooltip This ontology is bound to a lakehouse. See Bind an ontology to a lakehouse.

Tip: If you generated a schema from this ontology, Bind Generated Schema in the More menu binds the ontology to a database connection that runs that schema. See Generate a schema from an ontology.

Create an environment¶

A binding environment (Dev, Test, Prod, and so on) points this ontology at one database connection. If there are none yet, the workspace shows Create your first environment.

1. Click Create environment (or New on the environment bar).
2. Fill in the fields described below.
3. Click Create.

Field	What it does
Name	Required, up to 100 characters.
Description (optional)	A note for your team.
Connection	The database connection to bind against. Each option shows its database system.
Include schemas (optional)	Comma-separated schema names to read (database names on MySQL). Blank reads everything.
Exclude schemas (optional)	Comma-separated schema names to skip.
Command timeout (seconds)	How long each catalog read may take, 5–3600. Defaults to 3600.
Seed bindings from (optional)	Start with a copy of another environment’s bindings. Shown only when other environments exist.

Kenseme starts reading the database’s tables and columns straight away. While it works you see Capturing schema…. A large or cold database can take a minute or more; Databricks warehouses may need to start first. Progress also appears under Organization Settings › Background Jobs.

Switch environments with the dropdown on the left of the environment bar; each entry shows its connection underneath. Edit and Delete act on the selected environment.

Note: Changing an environment’s connection or schema filters flags it for a schema refresh. Suggestions stay disabled until you refresh.

Keep the schema snapshot current¶

Everything in the workspace is checked against a snapshot of the database schema, not against the live database. The environment bar shows the database system and a chip such as Schema as of 3 days ago · 42 tables. The chip turns amber when the snapshot is more than seven days old.

To take a new snapshot, choose Refresh schema from the More menu. It runs in the background.

• If nothing you’ve bound has disappeared, the new snapshot replaces the old one and a toast confirms it.
• If some bindings now point at tables or columns that no longer exist, nothing changes yet. A banner reads A schema refresh is awaiting review — N binding(s) would be removed. Click Open review to see each affected binding, the target it lost, the reason, and its origin. Column type changes are listed separately; they’re informational and never remove a binding. Click Accept and remove N bindings to apply the new snapshot, or Cancel to leave everything as it was.

If a refresh fails, a red banner explains why, with Retry refresh.

[screenshot]

Map classes and attributes¶

The workspace shows your ontology on the left (classes, each with its attributes) and the database on the right (schemas, tables, and columns).

• To bind a class to a table, connect the class to the table.
• To bind an attribute to a column, connect the attribute to a column of its class’s table.

Click a row’s port to arm it (the hint reads Click a … to connect, or press Esc to cancel.), then click the target, or drag from one side to the other. The tray along the bottom lists everything still unmapped.

Every change is staged. Nothing is saved until you click Save.

Let Kenseme suggest bindings¶

1. Open the More menu and choose Generate suggestions. Kenseme compares your ontology with the schema snapshot and proposes bindings for classes, attributes, and relationships. It runs in the background.
2. When the run finishes, a toast reports how many suggestions are ready and the Binding plan dialog opens by itself. You can reopen it any time with Review plan (N).

The plan has three sections:

Section	What’s in it	Ticked by default
✓ Exact matches	Confident matches on name or key.	Yes
◆ AI-suggested	The model’s proposals.	No — opt in to each one.
⊘ Not bindable	Things that couldn’t be matched, with the reason. Show finds the entity in the workspace.	Read only

Tick what you want and click Apply N bindings. Tick Reject unchecked suggestions first if you want every unticked suggestion removed from the plan when you apply. Applying stages the bindings; Save commits them.

Generate suggestions is disabled until a schema snapshot exists, while a refresh or another suggestion run is in progress, and while the environment needs a refresh.

Suggest only the relationships¶

When your classes are already bound, Generate relationship suggestions proposes joins for relationships only, without touching pending class and attribute suggestions.

• It needs at least one saved class binding. Until then it’s disabled with the tooltip Map at least one class to a table first.
• Each relationship is resolved from declared foreign keys first, then an exact table-and-column name match, then the AI model for whatever is left.
• AI rows are prefixed AI: and arrive unticked.

Focus Mode: one class or relationship at a time¶

Focus Mode gives a full-width screen to a single class or relationship. It’s where you set entity keys and edit joins in detail. It works the same way as in the lakehouse workspace; the full walkthrough is in Bind an ontology to a lakehouse. In short:

• Open it by clicking a class, or a relationship under a class. The URL gains ?focus= and can be shared. Leave with ← Map, Esc, or Back.
• Bind the class to a table with the picker in the header. A table that’s really a view is marked (view); binding to a view is fine. Rebinding keeps what still fits the new table and unmaps the class’s relationships, after a Rebind {Class} confirmation.
• Set the entity key with Use PK or Add key part…, and order the parts with ▲ and ▼. Choose a Display column for readable labels.
• Bind attributes to columns with the column pickers. Type mismatches are flagged with ⚠, never blocked.
• Add attribute creates a new attribute for a column nothing describes yet. The attribute is added to the ontology straight away; its binding is staged.
• Suggest mappings asks the AI for column proposals for this class only. Rows marked new create attributes when you apply them.
• Map relationships as direct foreign-key joins or bridge joins. A relationship needs an entity key on both of its classes; click an amber ⚠ no entity key card to go and set one.
• Foreign keys no relationship covers are listed with an Open ontology editor ↗ button. Relationships are created in the ontology editor, not here.

If the environment has no usable snapshot, the table, key, and column pickers are replaced by a message and a Refresh schema button. If the snapshot is merely out of date because the connection or filters changed, a warning says You can still bind against it — refresh the schema to be sure.

[screenshot]

Validate and save¶

The issues summary above the map flags problems as you work, such as an attribute bound to a column of an incompatible type. Some issues offer a one-click fix.

For a full check, choose Validate from the More menu. It checks every binding against the schema snapshot and lists what it finds.

• Save (N) commits your staged decisions. Reset discards them.
• If a save fails, a red banner stays until you save successfully, reset, or close it.
• If a background run (a schema refresh or suggestions) finishes while you have unsaved decisions, Kenseme doesn’t reload over your work. A banner says New server data is available. with Save and reload and Discard and reload.

Other tools in the More menu¶

Item	What it does
Disambiguate	Splits an attribute shared by several classes into one per class and re-maps the bindings.
Audit	Opens the audit log of binding decisions for this environment.
Copy bindings…	Copies bindings from one environment to another. Needs at least two environments.

After binding¶

Once at least one class is mapped, a banner reads This ontology is mapped, so its data can be asked about in plain language. with links to Ask the Data Agent and MCP Server settings.

Related¶

• Add a database connection
• Data Agent overview
• Expose an ontology over MCP
• Bind an ontology to a lakehouse