Bind an ontology to a lakehouse

Binding connects your ontology’s business vocabulary to real data. You map each class to a lakehouse table, each attribute to a column, and each relationship to a join. Once an ontology is bound, you can ask the Data Agent questions about it, and you can publish it to a Microsoft Fabric ontology item.

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

[screenshot]

Before you start¶

• You need Read/Write access to stage and save bindings. With Read Only access every control is visible but disabled, and a banner explains why.
• Your organization needs a Fabric credential that can see the lakehouse’s workspace.
• An ontology binds to a lakehouse or to a database, never both. If the ontology already has a database binding environment, Bind to Lakehouse is disabled with the tooltip This ontology is bound to a database. See Bind an ontology to a database.

Create an environment¶

You bind inside a binding environment. An environment (Dev, Test, Prod, and so on) connects this ontology to one Fabric ontology item and, optionally, one lakehouse. If the ontology has none yet, the workspace shows Create your first environment.

1. Click Create environment (or New on the environment bar).
2. Enter a Name (up to 100 characters) and an optional Description (optional).
3. If other environments exist, you can choose one under Seed bindings from (optional) to start with a copy of its bindings. Leave it on Start empty otherwise.
4. Under Fabric ontology item, choose one:
   • Create new — click Choose location, pick a workspace (and folder, if you like), and enter a Name. Names must start with a letter and use only letters, numbers, and underscores. Kenseme creates an empty Fabric ontology item there; its content is published on the first sync.
   • Bind existing — click Choose workspace and pick an ontology item from the list. Pushing replaces that item’s definition, so choose an item you’re happy for Kenseme to manage.
5. Under Lakehouse (optional), click Select lakehouse and pick the lakehouse whose tables you’ll bind to. Leave it out if you only want to publish the ontology’s structure to Fabric.
6. Click Create.

[screenshot]

Switch between environments with the dropdown at the left of the environment bar; each entry shows its lakehouse underneath. Edit changes the selected environment.

Map classes and attributes¶

The workspace shows your ontology on the left (classes, each with its attributes) and the lakehouse on the right (tables and their 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, then click the target on the other side, or drag from one to the other. Press Esc to cancel an armed connection. The tray along the bottom lists everything still unmapped.

Use the filter boxes on the environment bar (Filter classes…, Filter tables…) and the Mapped and Unmapped checkboxes to narrow the panels while you work.

Relationships map to joins. Click a relationship under its class to set which table and columns it joins on. See Map a relationship.

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 lakehouse and proposes bindings for classes, attributes, and relationships. A progress ring on the environment bar shows how far it has got.
2. When the run finishes, the Binding plan dialog opens by itself. You can reopen it any time with Review plan (N) in the More menu.

The plan groups proposals into four 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.
⇄ From Fabric	Bindings that exist on the Fabric ontology item but not in Kenseme.	Yes
⊘ Not bindable	Things that couldn’t be matched, with the reason. Show finds the entity in the workspace.	Read only

Use All and None on each section to tick in bulk, Edit on a relationship row to adjust the join before accepting it, then click Apply N bindings. Applying stages the bindings; Save commits them.

[screenshot]

Suggest only the relationships¶

When your classes are already bound, Generate relationship suggestions (directly below Generate suggestions in the More menu) proposes joins for the 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 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.

Note: Fabric doesn’t enforce primary or foreign keys on lakehouse tables, but Kenseme reads any keys you’ve declared as informational constraints. Where none are declared, suggestions rely on table and column names, so review them where names aren’t consistent.

Focus Mode: one class or relationship at a time¶

The map is good for the whole picture, but its panels are narrow. Focus Mode gives a full-width screen to a single class or relationship, and it’s where you set entity keys.

Open and leave Focus Mode¶

Click a class in the ontology panel, or a relationship row under a class. The address bar gains a ?focus= parameter (plus &kind=rel for a relationship), so the URL is shareable and survives a reload.

To go back, click ← Map in the breadcrumb, press Esc, or use the browser’s Back button. Staged decisions are kept as you move between the map and Focus Mode.

[screenshot]

The three panes¶

• Left — class navigator. Every class, with a chip for its entity key (K2 for a two-part key, ⚠ when it needs attention) and a count of bound relationships such as 3/5.
• Middle — editor. The table, entity key, display column, attributes, relationships, and the validation issues for this class.
• Right — bound table. The mapped table’s columns, with K1/K2 on key columns, D on the display column, and primary- and foreign-key flags. On a relationship screen it shows the junction table (bridge join) or the table holding the foreign key (direct join).

Bind the class to a table¶

The table name in the header is a picker.

• An unbound class shows Bind to a table…. Open it, type to filter, and pick a table.
• A bound class shows its schema.table. Picking another table rebinds it.
• The broken-link button next to the picker removes the table binding.

A table already bound to a different class is greyed out with the reason, such as dbo.customers — bound to Customer. Each table can back only one class.

When you rebind, Kenseme keeps whatever still fits the new table: a key part, display column, or attribute column whose name also exists on the new table is kept (letter case is ignored). Anything else is cleared, and every relationship that touches the class is unmapped, in both directions. A confirmation headed Rebind {Class} (or Unbind {Class}) spells out the effect first, for example:

Rebinding Customer to dbo.customers_v2: 3 attributes repointed, 1 attribute unmapped, key kept, display column kept, 2 relationships unmapped. Nothing is saved until you Save; Reset undoes staged changes.

A first bind, with nothing yet hanging off the class, happens without a confirmation.

Set the entity key¶

The entity key is the column, or ordered set of columns, that identifies one row as one instance of the class. Fabric needs it to publish the class.

• Use PK adopts the table’s primary key, in the table’s column order.
• Add key part… appends a column. Columns are labelled (PK), (FK), and (nullable).
• Each part shows its position (K1, K2, …), type, and any warning (nullable, not in snapshot). ✕ removes a part and Clear removes them all.
• ▲ and ▼ change the order. Order matters: the first part is used as the display name when no display column is set, and foreign keys are matched to key parts by position. The line entityIdParts: [order_id, line_no] shows exactly what will be published.

Set the display column¶

The Display column picker chooses the column used as a readable label for an instance, such as a customer’s name rather than its ID. If it’s empty, the first key part is used.

Bind attributes to columns¶

The Attributes → columns section lists every attribute of the class with a bound/total count. Each row reads attribute → column, and the column is a picker:

• Pick a column to bind the attribute, pick another to move it, or clear the picker to unbind it.
• The picker only offers columns of the class’s own table.
• If the attribute’s type and the column’s SQL type disagree, the binding is still made, the row shows ⚠, and a toast reads ⚠ Type mismatch — flagged but kept.

A class with no table yet shows not bound in place of the picker.

Add an attribute for an unbound column¶

When the table has a column your ontology doesn’t describe yet, click Add attribute in the attributes header.

1. Pick a column. Only columns that nothing is bound to are offered.
2. Keep or change the Name, which starts from the column name.
3. Click Add attribute.

The attribute’s value type is taken from the column. The attribute is added to the ontology straight away, and its binding is staged like any other change.

Suggest mappings for one class¶

Suggest mappings, in the attributes header, asks the AI to propose columns for this one class’s unbound attributes, against its one table. Unlike Generate suggestions, it runs immediately and stores nothing until you apply.

1. Click Suggest mappings.
2. The Suggested attributes dialog lists each proposal as attribute → column, with a HIGH, MEDIUM, or LOW confidence, the column type, a ⚠ where types disagree, and the reason.
3. Rows marked new propose a brand-new attribute for a column nothing describes yet. You can edit its name.
4. Every row arrives ticked. Untick what you don’t want and click Apply N mappings.

Existing attributes are staged like hand-made bindings. Rows marked new add the attribute to the ontology immediately; only their bindings wait for Save. If the AI has nothing confident to offer, you see No confident suggestions for this table.

[screenshot]

Map and unmap a relationship¶

The relationships section lists every relationship that starts at this class. An unbound one has Map, which opens the relationship editor pre-filled. A bound one shows its join with Edit and Unmap. Unmap removes the binding only; the relationship stays in the ontology.

Click a relationship’s name to open its own screen:

• A direct join asks which side holds the foreign key and which column it is.
• A bridge join shows the junction table and both legs: the column that joins the source class’s key and the column that joins the target’s.

A relationship can only be published when both of its classes have an entity key. An endpoint without one shows as an amber card reading ⚠ no entity key. Click the card to jump to that class, set its key (often one click of Use PK), and come back. The note turns green: Both endpoints are key-bound — this relationship will push.

Foreign keys no relationship covers¶

Relationships are created in the ontology editor, not here. When the lakehouse has a foreign key that no relationship covers, the class screen lists it under Foreign keys on schema.table that no relationship covers, often with a suggestion such as suggests shipToCustomer → Customer and an Open ontology editor ↗ button. Create the relationship there, then come back to bind it. New relationship identifiers are lowerCamelCase, as the ontology editor enforces.

Validate and save¶

The issues summary above the map flags problems as you work, with one-click fixes where possible. For a full check, choose Validate from the More menu. It checks that the bindings will push to Fabric and lists anything to fix.

• Save (N) commits your staged decisions. Reset discards them.
• Staged (N) in the More menu lists the staged decisions, with Discard per row and Discard all.
• Switching environments with unsaved decisions asks you to confirm first.

Other tools in the More menu¶

Item	What it does
Disambiguate merged attributes	Splits an attribute shared by several classes into one attribute 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 (Copy from, Copy to), so you don’t remap the same ontology for Dev and Prod. 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. You don’t have to publish to Fabric first.

To publish the ontology and its bindings to Fabric, or pull changes back, use the sync button on the environment bar. See Sync an ontology with Microsoft Fabric.

Related¶

• Sync an ontology with Microsoft Fabric
• Fabric credentials
• Bind an ontology to a database
• Data Agent overview