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 five tabs: Details, Canvas, Entities, Glossary, and Map & Match. 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 three tabs: Details, Entities, and Glossary.

The Details tab is where you edit the domain itself: Name, Status, Comment, and AI Context, the same fields a model’s own Details tab edits. 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 and Glossary tabs aggregate 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. Both tabs are read-only aggregates: 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 governed definition that flows to the glossary and follows the Draft → Approved lifecycle.

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 sheet. Each attribute carries its own definition and its own classifications, and each one is what a source column maps to in Map & Match.

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 sheet (click the entity’s card on the canvas) and changing the fields. 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.

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.

Click an entity card to select it. The card shows a selection ring and a connect handle appears on its right edge.
Drag from the connect handle onto any part of another entity card and release.
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.
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.
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. The detail sheet lets you:

Rename the relationship and edit its definition and AI context.
Change any participant’s verb inline.
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 sheet. 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 > Entities gives you one tree across every model: domains, their models, their submodels, and the entities that belong to each, 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. Use the search box to filter the tree by name, and click any entity to open it in the detail pane on the right: the same entity editor you use from the canvas or a model’s Entities tab, docked in a pane here instead of a popup sheet. The page keeps the selected entity in its ?entity= link, so you can bookmark or share a direct link to it.

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 view is for finding and inspecting entities across the whole organization. To bulk-edit, open the model on its own Entities tab.

A project or a workspace has the same tree on its own Entities page, which Business > Entities 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 Entities page. 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 detail pane, 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: it’s a read view. Every attribute you create, with its definition, status, and classifications, appears in the Business glossary automatically, alongside a count of how many source columns map to it. Each model also carries its own Glossary tab, showing only that model’s member entities. Writing a clear definition here is what makes the glossary useful to the rest of your team.

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:

Open the skeleton’s sheet.
Click Adopt into model to promote its origin from derived to modeled.
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 for a project. 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 run Suggest business entities against one of those models: 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. The AI context field lives on the domain or model itself, editable any time; see AI-assisted fields. An entity’s context is different: it’s captured and edited in the accept step when a skill proposes or enriches it, not hand-edited afterward.

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 read view your entities populate
Data governance overview: classifications, ownership, and the definition lifecycle
Run an AI skill: how AI context compounds