Create a logical & physical model

Generate and refine logical and physical data models from your conceptual model.

What you’re building

Logical and physical data models are represented as Entity Relationship Diagrams (ERDs), showing how data entities or tables relate to each other. A logical ERD defines the required entities, attributes, keys and relationships without depending on a specific technology, while a physical ERD adds the implementation details needed for a target database, such as table and column names, data types and constraints.

In Snap Data Studio, logical and physical views share one diagram canvas. Use the toolbar Logical / Physical toggle to switch presentation and edit fields. Assign a warehouse, database (or catalog), and schema under physical location settings before physical mode and database import are fully available.

You do not need a conceptual model to start. Open Diagrams in the project sidebar and create or import an ERD, or use Generate Model when you want a Kimball or Data Vault model from concepts and/or a source diagram. Your conceptual model is optional — use it when you want generation to follow your business concepts and linked tables.

Start a diagram

Create a blank diagram

1. Open a project, then open Diagrams in the sidebar.
2. Click New diagram (+). Snap Data Studio opens an Untitled Diagram tab with an empty canvas.

No warehouse is required to create a blank diagram. Add structure yourself with:

• Toolbar Add entity, Add area, and Add note
• Tables drawer → Add Table
• Drag from one table to another to create relationships
• Code View to edit the diagram as JSON
• AI Copilot (Agent mode) to propose tables and relationships once the diagram is open for Copilot

Reverse engineer (import)

From the Diagrams drawer, open Import diagram and choose a method. These create a new diagram from an existing schema (they do not use Generate Model).

Method	How to use	Prerequisites
Import from DB	Pick a warehouse and tables. Confirm with Generate Diagram.	Project open; warehouse credentials configured for the project; tables selected.
Import DDL	Open Import from DDL, choose a dialect (default Snowflake), paste a DDL script, then Generate Diagram.	Project open; non-empty DDL.
Import DBML	Open Import from DBML, paste a DBML schema, then Generate Diagram.	Project open; non-empty DBML.

Import tables into an existing diagram

On an open diagram, use the toolbar Import → Import tables from DB. The modal title is Import Tables. Confirm with Import Tables.

This option is unavailable until the diagram has a warehouse assigned. Set physical location settings first. If the import warehouse or location differs from the diagram defaults, you may be asked to Keep import location, Use diagram defaults, or Cancel.

Generate a data model

Use Generate Model in the header while a Diagram or Conceptual Model tab is active. The modal title is Generate model (or Building your data model while a run is in progress).

Choose a methodology

Pick one methodology card (required):

Methodology	Use when
Kimball - Dimensional Model	Analytical models with facts and dimensions.
Data Vault	Historical tracking, auditability, and scalable integration.

Configure Concepts, Guidance, and Source Model

The right side of the modal has three tabs.

Concepts

Select which concepts to include (N of M selected). Use Select All / Deselect All, search (Search concepts or domains…), and domain-level toggles.

Concepts that already have a suitable linked warehouse table for the selected methodology show a database marker (Ready linked table role). For generation from concepts, keep concepts that have that marker, link any missing tables, or also pick a source diagram.

If a concept has both Source and Intermediate linked tables, generation uses the Intermediate table for that concept and ignores the Source link. Your source diagram is not changed.

Guidance

Optional Generation guidance steers naming, grain, keys, history, and constraints. Empty guidance is allowed.

Shared prompts:

• What does this data represent?
• Any specific guidance for source entities?
• Expand Add optional constraints for additional context

Under Kimball, these help to inform the grain, entity and history tracking, and additional context. Under Data Vault, they help inform the entity classification and additional context.

Source Model

Optionally select a source ERD (Search diagrams…). You can generate from concepts alone when every selected concept has a ready linked source table, from a diagram alone, or from both.

How sources combine

Selection	What drives structure	How concepts are used
Diagram only	Tables and relationships from the source diagram	Selected concepts can still add business guidance and mark tables you have already modeled. Column details from linked warehouse tables are not copied into the diagram used as the source.
Concepts only	Warehouse tables linked on your concepts (named Concept Model when there is no other source name)	Every selected concept needs a linked table with the Source role. Those tables must have usable metadata (refresh them if generation asks you to).
Both	The diagram is the main structure	Concepts still add event and relationship guidance, linked-table roles, and attribute hints. If Intermediate and Source are both linked on a concept, Intermediate wins — the diagram is unchanged.

Run, cancel, and reopen

1. Click Generate Model (shows Starting…, then progress with stage messages).
2. Use Cancel Generation to stop a run in progress.
3. Closing the modal while generation runs does not stop the job — you can open Generate Model again to follow progress. If generation is still starting, you may see a short “try again shortly” toast.

What gets created

Generation always creates a new diagram. It does not overwrite the source diagram.

Output	Typical name
Diagram	Source name plus - Dimensional or - Data Vault (concept-only sources use Concept Model plus the same suffix)
Documentation	AI-Generated Documentation
Column mappings	Column Mappings (when applicable)

If every source table shares one database/schema (or catalog/schema), that location is applied to the generated tables.

Re-run, already-modeled tables

• Re-run: open Generate Model again to create another new diagram. There is no “update this generated model in place” action.
• Already-modeled linked tables: when concepts or relationships link tables with roles that match the methodology (for example Fact or Dimension for Kimball, or Hub, Link, Satellite, or Reference for Data Vault), generation keeps those tables as-is instead of redesigning them.

How your conceptual model is used

Generation uses details from your conceptual model — whether a concept is an event, relationship types, linked tables and roles, and attributes that are mapped or not mapped to columns. For the full list, see How enrichment feeds data model generation.

Canvas basics

Open a diagram tab to edit the ERD. Switch Logical / Physical on the toolbar. Use the warehouse button (Physical location settings, or Set warehouse, namespace, and schema when incomplete) to open Warehouse Settings and set Warehouse, Database or Catalog, and Schema. Confirming overwrites database/schema (or catalog/schema) on all tables.

Navigate and select

Action	Behavior
Drag an entity	Move it on the canvas.
Drag from one table to another	Create a relationship (you may be prompted to pick a key).
Click a table or relationship	Select it.
Double-click a table	Enter edit mode.
Click empty canvas	Clear selection.
Zoom / fit	Use the canvas zoom and fit-view controls.
Undo / Redo	Toolbar buttons, or ⌘Z / Ctrl+Z and ⇧⌘Z / Ctrl+Y.

Toolbar

Control	What it does
Undo / Redo	Step backward or forward through diagram edits.
Add entity	Add a new table/entity to the diagram.
Add area	Add a visual grouping area.
Add note	Add an annotation note.
Auto Layout	Automatically rearrange the diagram.
Import	Import tables from DB — unavailable until the diagram has a warehouse assigned.
Naming	Apply naming conventions on the open diagram — see Naming conventions.
More actions	Overflow menu for additional actions.
Line style	Curved or Smoothstep relationship lines.
Filter	Filter tables — hide tables without deleting them (badge shows hidden count).
Attribute display	All Attributes, Table Names, or Keys Only.
View options	Menu for relationship lines, attributes, and filter shortcuts.
Logical / Physical	Switch view mode on the same diagram.
Warehouse	Open physical location settings.

Physical names and validation

Physical mode uses warehouse-oriented names and types. Physical names must:

• Be non-empty and at most 255 characters
• Use ASCII letters, numbers, and underscores only
• Start with a letter or underscore (not a number)

Logical names may include letters, numbers, spaces, underscores, hyphens, and apostrophes (max 255).

Invalid names show an error highlight under the field (on the table and in the Tables drawer). Duplicate logical names in the same table show Logical name already exists in this entity.

How logical and physical names interact with project rules is covered in Naming conventions.

Naming conventions

Naming conventions are project settings. Every diagram in the project shares the same rules. They do not live on a single diagram, and changing them does not automatically rename every existing diagram.

Configure rules

1. Open Settings in the sidebar (a project must be open).
2. Choose Naming conventions. The modal title is Naming conventions plus your project name.
3. Turn naming conventions on or off, edit the rules, then Save.

When on: “Applied when you use Naming on the toolbar.”
When off: “Names stay exactly as you draw them.”

You also get a Live preview of how names will look as you edit the rules. Toast after save: Naming conventions saved.

Tabs and what they control

Tab	Purpose
General	Rules for tables, columns, and keys used across diagrams. Banner: “Your naming rules for tables, columns and keys.”
Kimball-specific	Prefixes, suffixes, and key patterns used when you generate a Kimball (star schema) model.
Data Vault-specific	Prefixes, suffixes, and key patterns used when you generate a Data Vault model.

General includes:

• Table name and Column name — case style chips: snake_case, PascalCase, camelCase, UPPER_SNAKE
• Keys — Primary key and Foreign key patterns. Use the entity placeholder token (written in curly braces in the UI) where the table name should go (for foreign keys, the referenced table).
• System columns (optional) — shared audit and history column names (for example load date, record source, effective dates, is-current flag, hash diff)

Kimball-specific adds Dimension and Fact prefix / suffix, plus a Surrogate key pattern.
Data Vault-specific adds Hub, Link, Satellite, and Reference prefix / suffix, plus a Hash key pattern.

Use Quick fill with → Kimball style or Data Vault style to load a starter set. Turn individual sections on or off. Reset to default appears on fields that differ from the defaults.

If Table name or Column name is turned off, case is left as drawn. If Keys is turned off, key patterns are not applied.

Impact across all diagrams

Where	What happens
Project settings	One rule set for the whole project — every ERD in that project uses it.
Toolbar Naming	Applies only to the diagram you have open. Saving settings does not bulk-rename other diagrams.
Typing new names	On any diagram in the project, entering a logical name on a new table can fill the physical name (and vice versa) from these rules. After both names are set, they edit independently.
Generate Model	Active conventions are applied to the newly generated Kimball or Data Vault diagram (methodology-specific prefixes and keys included). Tables you already marked as modeled stay preserved after rename.
AI Copilot	Active conventions are available as guidance when Copilot works on a diagram.
Import / reverse engineer	Import from DB, DDL, or DBML does not automatically rewrite names to your conventions. Open the new diagram and use Naming if you want to apply them.

If naming conventions are off (or never saved for the project), toolbar Apply and generation do not enforce your custom rules. Names stay as you draw them, with simple built-in defaults for live name suggestions.

Apply naming conventions on a diagram

1. Open a diagram that has tables.
2. Click Naming (Apply naming conventions) on the toolbar.
3. Review Naming conventions preview — “Review the highlighted renames, then apply or reject.”
4. Click Apply to keep the renames, or Reject to discard them.

Apply updates physical table and column names (and matching relationship key references). It does not rewrite logical names.

Common messages:

• Add some tables before formatting names — diagram is empty
• No naming conventions are active for this project. Configure them in Settings → Naming conventions first.
• No naming rules could be applied — nothing would change
• Duplicate-name conflicts — Apply is blocked and the diagram is left unchanged until you fix the conflict

Use the copilot

Open AI Copilot from the header while a diagram tab is active.

Modes

Mode	Use for
Ask	Explore and analyze the model without staging edits.
Agent	Edit the ERD and stage changes for review.

Model tiers: Fast, Automatic, or Intelligent.

Attachments and context

From the composer:

• Attach file — PDF or supported text
• Database control — select warehouse tables to attach as context
• Mentions of diagrams, documents, and code when available

Review staged changes

Agent edits stage on the canvas. When ready, review Staged changes ready, then Keep or Revert. Staged changes are not saved until you Keep. Resolve pending changes before starting another Agent edit.

What works well to ask

• Refine entities, attributes, keys, and relationships after generation
• Align naming with your warehouse conventions
• Ask for an audit or advice on the current diagram (Ask mode)
• Attach source docs or tables, then ask for targeted structural changes (Agent mode)

On diagrams, Copilot edits tables, attributes, relationships, and areas, and can help with related artifacts. On the conceptual model, Copilot edits concepts and relationships instead — see Create a conceptual model.

Helper drawers

Open these from the project sidebar while working on a diagram. They make editing faster than working only on the canvas: search and update tables, fix JSON, and manage annotations in one place.

Code View

Code View shows the diagram as editable JSON. Changes are checked as you edit. Use it to inspect the full model, fix structural issues, and apply suggested fixes when the UI offers them (for example duplicate labels or attributes, or incorrect relationship connections with Auto-Fix Edge / Delete Edge).

Tables

Tables lists tables with a count and search (Filter tables…). Use Add Table to create tables, expand a row to edit names, types, constraints (primary key, foreign key, unique, not null, and related options), and comments, and reorder where supported. Empty state: No tables yet. Changes stay in sync with the canvas.

Relationships

Relationships lists connections with a count and search (Filter relationships…). Expand a row to rename, set cardinality (including a custom matrix when needed), and select the relationship on the canvas. Very large diagrams may show a limited list in the drawer.

Annotations

Annotations manages visual aids with tabs Areas and Notes. Add, rename, search, set area colors, and jump to items on the canvas. Areas group related tables visually; notes capture freeform comments without changing the data model.

What’s next

• Connect to a data warehouse
• Create an artifact
• Create a conceptual model