Business entities

Business entities are the concepts your business cares about (Customer, Order, Shipment), and their attributes are the facts about each concept. They’re the source of truth that governance, the glossary, and map & match all read from, so the model you build here is what gives meaning to every source table and column you map to it. This guide covers creating and editing entities and attributes on a model’s canvas, browsing entities across your organization, bulk-editing them on a model’s Entities tab, and adopting the skeletons that Map & Match derives.

Find or create a model

From Business > Models in the left navigation, browse your business models. They’re organized by domain: each domain groups its models together in the grid, with any submodels nested under their parent model. Click a domain’s name, or choose Open from its actions menu, to open the domain’s own detail page (see below); a model or submodel’s name is a link, so a single click opens that model’s own detail page and a double click renames it in place, while clicking elsewhere in its row selects the row instead.

A model’s detail page carries four tabs: Details, Canvas, Entities, and Map & Match, plus an Open in Glossary action that opens the organization-wide Glossary with this model already selected. This guide covers the Canvas tab, where you create and arrange entities, attributes, and relationships, and the Entities tab, where you search, filter, and bulk-edit the model’s own entities. A breadcrumb at the top of the page (Business models, and for a submodel its parent model) takes you back to the grid. Modeling is editor-only and runs on a feature branch, like every other catalog change: your work reaches main when you commit it.

The models grid

Each row shows:

• Entities: the count of entities that belong directly to that model or submodel.
• Status: the current lifecycle status.
• Kind: whether the model is Relational or Dimensional.
• Updated: the date of the last change.

Create a model

Select New model at the top of the models grid to open the create dialog: a Name, a Domain (pick an existing one, or pick New domain from the list to reveal a field where you name the new one), an optional Parent model to create the new row as a submodel, and a Kind. Creating the model takes you straight to its detail page.

Two row-level shortcuts pre-fill the same dialog: a domain’s actions menu offers Create, and a model’s actions menu offers Add.

Create a domain

Select New domain at the top of the models grid, beside New model, enter a name, and select Create domain. This takes you straight to the new domain’s own detail page.

A brand-new domain has no models yet, so its group in the grid holds a single placeholder row (its tooltip reads “This row is a placeholder; create a model first”), and the domain’s own Details tab says “No models yet. Add one with the New model action above.” Add the first one with New model from the domain’s detail page header, or with Create from the domain row’s actions menu.

This standalone New domain button creates an empty domain on its own, before any model exists in it. That is a different path from the New domain option inside the Create a model dialog above, which creates a domain and a model together in one step: use the dialog’s option when the model’s domain does not exist yet, and use this button when you want the domain in place first, with models added afterward. See “Open and edit a domain” below for what the domain’s own detail page carries once you are on it.

Rename and archive

Every row (domain, model, or submodel) carries an actions menu (the three-dot control on the right). Rename opens a small dialog where you edit the name and save. Archive hides the row, and everything nested under it, from the grid; it stays reachable by direct link, where you can bring it back by setting its status to Draft or Active on its Details tab.

Open and edit a domain

Click a domain’s name, or choose Open from its actions menu, to open the domain’s own detail page. It carries two tabs, Details and Entities, and the same Open in Glossary action a model’s page offers.

The Details tab is where you edit the domain itself: Name, Status, Definition, AI context, and AI instructions, fields a model’s own Details tab edits too. Its footer counts every entity across every model and submodel in the domain, not just entities on the domain row itself (a domain rarely carries any of its own). Below the fields, Models in this domain lists the domain’s models, each a link to its own detail page, and a read-only Used in projects & workspaces section rolls up every project and workspace that any of the domain’s models is used in.

The domain’s Entities tab aggregates across every model and submodel in the domain: instead of one model’s own entities, you see everything that belongs to any model in the domain, in one place. It is a read-only aggregate: to add an entity or change a mapping, open the model it belongs to.

Canvas and Map & Match stay per-model for now: a domain’s detail page doesn’t carry either tab. To draw or arrange the relationship diagram, or to run Map & Match, open the model itself.

Set a model’s kind

Each model carries a Kind: Relational or Dimensional, chosen when you create it and editable afterward on the model’s Details tab. The kind decides how the model renders. A Relational model opens on the standard relationship canvas. A Dimensional model opens on the dedicated dimensional canvas, where dimensions and facts are laid out for a star schema and can feed the dimensional generator. New models are Relational by default; switch a model to Dimensional when you want to build it as a star schema. The kind is a property of the model itself, independent of the categories your catalog uses.

Create an entity

Add an entity to the canvas and give it a name that reads as a business concept, not a table name: Customer, not dim_customer. Each entity carries a few descriptive fields:

• Entity type / category: what kind of concept this is, so the model groups and reads consistently. Pick the type that fits the concept you’re describing.
• Definition: the authoritative prose for what the concept means in your business. This is the definition the glossary shows in its Definition column, and it follows the Draft → Approved lifecycle.
• AI context, AI instructions, Usage, and Limitations, at the end of the panel’s semantic fields: what an AI needs to know about the concept that its definition shouldn’t hold. Usage says who uses the concept and for which questions, and Limitations what it doesn’t cover or must not be used for. Context flows down the domain tree covers the other two.

You can create an entity with nothing but a name and fill in the rest later; the model is yours to grow.

Every entity you create is born with a business key attribute, named by convention from the entity’s technical name: create Customer and it already carries Customer_BK, flagged as the business key and identifier. The naming pattern (“Business key column pattern”) and the key’s length (“Max identifier length”) live in your organization settings; changing them affects future entities only. An entity created before this convention existed acquires its key the first time you need one: set it by hand on an attribute (below) or let the relationship dialog prompt you.

Add and edit attributes

Attributes hang off an entity and describe its facts (Customer ID, email address, signup date). Add attributes to an entity from its panel, with Add attribute in More actions. Each attribute carries its own definition and its own classifications, and each one is what a source column maps to in Map & Match. Its panel also keeps Example values after Synonyms: up to ten real values as they appear in the data, each added as a chip when you press Enter (an eleventh is refused, with a sentence saying why). AI context and AI instructions follow Definition, ahead of the attribute’s relationship.

The attribute flagged as the entity’s business key wears a BK badge in the attributes grid. Any other attribute can take over the designation with its row action Designate: the flag moves, the previous key attribute keeps its other properties.

Edit an entity or attribute by opening its panel (a single click on the entity’s card on the canvas) and changing the fields. On the Details tab your edits wait for Save in the panel’s toolbar, and Discard changes puts the stored values back; the Attributes grid still saves each cell as you go. More actions holds the entity’s other commands, among them Add attribute, Add relationship, View history and, last, Delete entity. A relationship you open from the Relationships tab takes the same panel, titled Relationship, with a trail back to the entity, and Close returns you to the entity. See Detail panels for the toolbar, the pop-out window and the Unsaved changes question. Renaming keeps the object’s place on the canvas and keeps any mappings intact. Renaming an entity whose technical name drives derived key names prompts you before touching anything in other entities: it lists the foreign-key attributes that still follow the old derivation and you choose which of them rename along.

A name or definition that came from an accepted AI proposal, such as an entity the business modeling workshop created, carries the AI badge while it is still the AI’s. The entity panel shows it beside Name and beside Definition; an attribute’s editor shows it beside Definition, and an attribute’s name shows it as a small sparkle icon beside the name on the entity’s Attributes tab. The badge includes the confidence as a percentage when the proposal had one. Change the value and the badge goes, because the text is now yours; renaming leaves the definition’s badge alone, and editing the definition leaves the name’s. AI context keeps a badge of its own while a skill’s text stands there.

Arrange the canvas

Drag entities to lay the model out the way it makes sense to you. Your arrangement is saved and restored between visits, so the picture stays stable as you add concepts. Viewers can drag to explore, but their arrangement isn’t saved.

Create relationships on the canvas

Relationships carry foreign-key semantics, not just a line between boxes: the referencing entity receives a foreign-key attribute derived from the referenced entity’s business key.

1. Click an entity card to select it. The card shows a selection ring and a connect handle appears on its right edge.
2. Drag from the connect handle onto any part of another entity card and release.
3. The relationship dialog opens with a direction sentence: “Order references Customer: Order receives a foreign-key attribute based on Customer’s business key.” Use Swap if the drag direction was not the direction you meant; the entity on the “references” side always receives the foreign-key attribute.
4. The foreign-key attribute name is proposed from the referenced entity’s key (for example Customer_BK) and is editable. Editing the name is how role naming happens: two relationships to Address can create ShippingAddress_BK and BillingAddress_BK. If the referencing entity already has an attribute with the proposed name, the dialog offers to link the existing attribute instead of creating a duplicate.
5. If the referenced entity has no business key yet, the dialog embeds a define business key step: promote one of its existing attributes, or derive the pattern-named attribute. Creation stays blocked until the key is resolved.

Deleting a relationship (select the edge, then press Delete, or right-click it) prompts before touching data. When the relationship carries a foreign-key attribute, the prompt offers to delete that attribute too: pre-checked when it was auto-created and nothing else references it, disabled when other relationships or column mappings still depend on it.

Delete a domain, model, entity, or attribute

Domains and models can now be deleted from their own detail page, alongside Rename and Archive. It is worth being precise about the difference between the two: delete is permanent, archive is reversible. Archive (in the models grid row menu) hides a domain or model, and everything nested under it, from the grid; it stays reachable by direct link and you can bring it back by setting its status to Draft or Active. Delete removes the domain or model, and everything nested under it, for good. Reach for archive when you want a domain or model out of the way but might return to it, and delete only when you are certain you want it gone.

Before you confirm a delete, the dialog tells you exactly what else it will remove, so there is no guessing:

• Deleting an entity also removes its attributes, and unmaps any source columns and source tables that were mapped to them.
• Deleting a domain or model also removes its submodels, and clears the domain’s or model’s project and workspace assignments.

If a model or domain you are deleting is still assigned to a workspace, the dialog asks you to confirm that extra step before it proceeds, so you don’t remove a model a workspace depends on without noticing.

Deleting an entity now asks you to confirm before it proceeds, the same as deleting a domain, model, relationship, or relationship group. This is new: entity deletion used to happen without a confirmation step.

An attribute cannot be deleted in two situations, and the dialog names which one applies: while it is the entity’s business key, or while a relationship references it. To delete the attribute, first set a different attribute as the business key, or remove the relationship that references it.

Relationships that involve three or more entities

Some business actions naturally involve more than two entities at once: an order placement involves the customer, the order, and the products chosen. These arrive on the canvas as a small labeled pill, with a line running from the pill to each participating entity. Select the pill to see each line labeled with that participant’s verb, for example “places” on the customer’s line.

These multi-entity relationships are created by the business modeling workshop when you accept a combined connection; there is no draw-to-create gesture for them on the canvas yet.

Edit one by clicking its pill. It opens in the panel, titled Natural business relationship, which lets you:

• Rename the relationship and edit its definition and AI context. These wait for Save in the panel’s toolbar, and Save stays dimmed with “A natural business relationship needs a name.” while the name is blank.
• Change any participant’s verb inline; participant changes apply at once.
• Add a participant from the model’s other entities, or remove one. A relationship of this kind always keeps at least three participants; the remove control explains this when you are at the minimum.

Delete one from the same panel. Delete relationship group sits last in More actions, and a confirmation makes the boundary clear: the participating entities stay on the model, only the relationship between them is removed.

Browse entities across your organization

Business > Glossary gives you one tree across every model: domains, their models, their submodels, the entities that belong to each, and each entity’s attributes beneath it, plus an Unassigned bucket for entities that don’t belong to any model yet. An entity that belongs to more than one model appears once under each. Search narrows the tree and the terms grid beside it at the same time, and clicking any entity opens it in the panel beside the grid: the same entity editor you use from the canvas or a model’s Entities tab, docked beside the grid here too. The page records the open term in its own address, so you can bookmark or share a direct link to it, and an older bookmark to the entities page still lands here because it redirects with its query string intact.

New entity creates an entity into whichever model or submodel you have selected in the tree, or as unassigned if you have a domain, the Unassigned bucket, or nothing selected.

This is where you find and inspect entities across the whole organization. To bulk-edit a model’s entities, open the model on its own Entities tab. For the rest of the surface, including the terms grid and the definition lifecycle, see Business glossary.

A project or a workspace has the same tree on its own page, which the Glossary item opens while you are inside that project or workspace, filtered to the models in that project or workspace and the entities that hang off them. The Unassigned bucket is organization-level only: since an unassigned entity belongs to no model, it belongs to no project or workspace either, so it never shows up in a scoped glossary. See Scope models to projects and workspaces for how a project or workspace’s model membership is managed.

Bulk-edit entities in a model

A model’s Entities tab lists that model’s own member entities with search, filters, and sort. An entity’s name is a link: a single click opens that entity in the panel beside the grid, and a double click renames it in place. Clicking elsewhere in a row selects it instead, and selecting rows reveals the bulk action bar: Set status…, Set default domain…, Add tags…, Remove tags…, and Archive in its overflow menu, plus a direct Delete button.

How entities reach the glossary

You don’t publish to the glossary separately. Every entity and attribute you create appears in the Business glossary as a term automatically, with its definition, status, and classifications, alongside a count of how many source columns map to it. The glossary is not a second copy to keep in step: it reads the same entities and attributes you build here, which is why a definition you write on the canvas is the definition the rest of your team looks up. Definitions can be written and approved from either side, on the entity or attribute itself or in the glossary grid. A model reaches its own slice of it with the Open in Glossary action on its detail page.

Adopt derived skeletons

When you run Map and match, accepting a match for a table or column that fits no existing entity or attribute creates a skeleton, a real, governable object that DeltaVault derived from the mapping rather than one you drew by hand. Skeletons wear a Derived chip on the canvas.

A derived skeleton is fully usable straight away: you can classify it, name an owner and steward, and write its definition. What it isn’t yet is a deliberate, first-class part of your model. When you’re ready to make it one:

1. Open the skeleton’s panel.
2. On its Details tab, click Adopt into model to promote its origin from derived to modeled.
3. Flesh it out: add the attributes, relationships, type, and definition a hand-modeled concept would have.

Adopting doesn’t change any mappings; it just signals that the concept is now part of your intended model rather than a by-product of matching. Many teams let Map & Match derive the bulk of their entities, then adopt and refine the ones that matter.

Context flows down the domain tree

The chain. A business entity’s ancestors are its model and its domain. Whatever AI context those rows carry is automatically included when a context-aware skill runs against the entity or its model, so entities inherit from their model and domain without any extra step.

The worked example, step by step. Run Suggest business domains and models from the Business models list. Each proposed domain and model arrives with a Proposed AI context you can edit or blank in the accept step: blanking leaves the field unset on that record, and accepting never clears or overwrites context already stored there. See Run an AI skill: how AI context compounds for the full rules. Accept it. Then open one of those models and run Suggest missing entities for this model: the run automatically receives the model’s and domain’s accepted context, so the entities it proposes reflect what you approved a minute earlier instead of starting cold.

Where to see or change what is stored. Every domain, model, entity, and attribute shows its AI context in its own editor: the domain’s or model’s Details tab, the end of the entity panel’s semantic fields, the attribute panel. A skill proposes it in the accept step, where you can edit or blank it, and afterward you can change it in that editor at any time. It’s a plain box with no AI editor of its own, and it shows the AI badge until you edit it. Beside it, AI instructions hold the rules you want an AI to follow when it answers questions over this concept’s data. You write them, with the field’s AI help if you ask for it (see AI-assisted fields). On an entity or an attribute, Suggest with AI in the AI suggestions section can also propose them, and the AI context too, and nothing changes until you accept.

Related guides

• Scope models to projects and workspaces: adding models to a project or workspace, and browsing their entities in a scoped Entities page
• Business glossary and governance quick start: where modeling fits in the full sequence
• Map and match source metadata: linking tables and columns to your entities and attributes
• Business glossary: the vocabulary your entities and attributes populate
• Data governance overview: classifications, ownership, and the definition lifecycle
• Run an AI skill: how AI context compounds