Create a logical & physical 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 data platform, database (or catalog), and schema under physical location settings before physical mode and data platform 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

Open a project, then open Diagrams in the sidebar.
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
DBML to edit the diagram as DBML text
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.

What an import keeps, converts, and reports

An import never treats a successful parse as a faithful copy. What it understands it keeps; what it has to adapt for the target it converts and lists for review; what it cannot represent it reports rather than dropping quietly.

Types. Every SQL type the target warehouse supports is kept as written, including nested ARRAY<...>, STRUCT<...>, and MAP<...> on Databricks. Types from other databases that the import recognises (ENUM(...), serial, jsonb, uuid, varchar2, text, int4, and similar) are converted to the target’s equivalent and appear in the Conversion review with their original declaration. A type the import does not recognise is converted to the target’s default type for the column’s kind and listed as opaque. A declaration with impossible parameters, such as varchar(-1), decimal(2,5), or varchar(10,20), is refused with a message saying what to change.
Allowed values. ENUM(...) declarations, DBML Enum blocks, and CHECK (column IN ('a', 'b')) rules become the column’s allowed values. Other CHECK rules are reported as not represented.
Defaults. Quoted defaults stay text, so 'now()' remains the text now(), not a call. Numbers, booleans, NULL, and expressions keep their own meaning. See Default values.
Keys. Primary and unique keys declared inline, at table level, in DBML indexes blocks, or in later ALTER TABLE ... ADD CONSTRAINT statements are all applied. A composite unique key stays one rule over its columns; its members are not marked unique on their own.
Relationships. Foreign keys added by ALTER TABLE are drawn like inline ones. ON DELETE and ON UPDATE actions are kept on the relationship; generated DDL reports when the target warehouse does not enforce them. A DBML many-to-many reference (<>) is refused with a note to model a junction table, because a single foreign key cannot carry it.
Everything else. Plain indexes, other ALTER statements, and statements the parser cannot read are listed as skipped.

Findings from a DDL, database, or DBML import are written to the Reverse engineering report document under Diagram Artifacts once the diagram is saved; the toast after an import tells you how many there are. Type conversions open the Conversion review the first time you choose a warehouse for an imported diagram, or immediately when you edit DBML on a diagram that already has one.

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. You’ll see Generate model when setting up a run and Building your data model while generation 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 Source and Guidance

Use the Source and Guidance tabs to choose the input and add instructions.

Source

The Source tab shows two cards, Concepts and ERD model. Each card summarises what is selected in it; click a card to open its list underneath. Fill one card or both: generation needs at least one. When you open Generate Model from a diagram, the ERD model card is already filled with that diagram.

Concepts

Select which concepts to include (N of M selected). Use Select all / Clear, 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 alone, keep concepts that have that marker, link any missing tables, or also pick an ERD model. The Concepts card shows N not ready while a selected concept would block a concepts-only run. 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.

ERD model

Optionally select a source ERD (Search diagrams…); the diagram you started from is marked This diagram. After you pick a diagram, a Version row shows the version that will be used; click Change to pick Working draft or a saved snapshot. The Certified version is selected when one exists; otherwise the latest version. See Save and certify a version. You can generate from concepts alone when every selected concept has a ready linked table, from a diagram alone, or from both. The summary beside Generate Model states what the run will use, for example From 3 concepts, scoped to Orders · Version 5.

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.

How sources combine

Selection	What drives structure	How concepts are used
Diagram only	Tables and relationships from the source diagram	No concepts are selected.
Concepts only	Warehouse tables linked on your concepts (named Concept Model when there is no other source name)	Every selected concept needs a ready linked table for the chosen methodology. 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

Click Generate Model (shows Starting…, then progress with stage messages).
Use Cancel Generation to stop a run in progress.
Closing Building your data model does not stop generation. Open Generate Model again to follow progress. If generation is still starting, you may be asked to try again shortly.

Follow generation progress

The workflow graph shows which steps are running and which have finished. The generation context shows results as they become available, so you can inspect the model while work continues.

Understand the Data Vault design

During Designing Data Vault, the Data Vault design section can already show hubs, links, satellites, and reference tables. These establish the core structure. Generation then refines attribute groupings, satellite types, and how satellites attach to hubs and links. The detailed tables, including columns, data types, and keys, are generated after the design stage. Classification review and Design review run automatically. A review may request revisions, leading to another iteration. When multiple iterations are available, use the arrows beside Iteration to inspect earlier results and their reviews. Expand an item to see its details; changed fields show Before and Now values.

Follow table generation

For Data Vault, reference tables and hubs can generate at the same time, so both steps may be active together. Once both finish, generation continues with links, then satellites. references not needed means the design does not require reference tables. Table generation is followed by relationship building, documentation, and saving the result. Wait for the run to finish before opening the generated diagram.

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). A named source version is appended in parentheses — for example `Sales Model - Dimensional (Approved v2)`.
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 platform button (Physical location settings, or Set platform, namespace, and schema when incomplete) to open Configure Platform and set Platform, 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. If it is part of a selection, the whole selection moves with it.
Drag from one table to another	Create a relationship (you may be prompted to pick a key).
Click a table or relationship	Select it, replacing whatever was selected before.
Shift+drag on empty canvas	Draw a box and select everything it fully surrounds.
Shift, ⌘, or Ctrl + click a table	Add it to the current selection, or take it out if it is already in.
Double-click a table	Enter edit mode.
Click empty canvas, or press Escape	Clear the selection immediately when not editing text. While editing text, the first Escape exits edit mode and the second clears the selection.
Backspace / Delete	Delete everything that is selected.
Zoom / fit	Use the canvas zoom and fit-view controls.
Undo / Redo	Toolbar buttons, or ⌘Z / Ctrl+Z and ⇧⌘Z / Ctrl+Y.

Select several objects at once

Rather than working one table at a time, you can gather a group and act on all of it together.

Draw a box. Hold Shift and drag across empty canvas. Everything the box fully surrounds is selected, including areas and notes.
Add or remove one item. Hold Shift, ⌘, or Ctrl and click a table to add it to the selection. Click a selected table the same way to take it back out.
Move the group. Drag any table in the selection and the rest travels with it, keeping the arrangement. Dragging a table that is not in the selection selects that table on its own and moves only it.
Delete the group. Press Delete or Backspace to remove every selected table, area, and note, along with the relationships attached to them. A single Undo brings the whole group back.
Clear the selection. Click empty canvas or press Escape to clear it immediately when not editing text. While editing text, press Escape once to exit edit mode and again to clear the selection.

Relationships are still chosen one at a time. Clicking a relationship selects it alone and clears any tables you had selected. While a group is selected, the DBML drawer highlights each selected table together with the relationships that run between them. Relationships that lead outside the group are left unhighlighted, so the highlighted text is the part of the model your selection actually covers. With a single table selected, every relationship attached to it is highlighted instead.

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 from Data Platform — unavailable until the diagram has a platform 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.
Platform	Open physical location settings.

Allowed values

A text column can carry the finite list of values it accepts. Open the type settings (the gear beside the type) on a text column to add, remove, reorder, or clear values; the row shows an N values badge while the list is set. Values keep their exact spelling, case, spaces, and order. The list is independent of nullability, the default, and the length: a value list does not make the column NOT NULL and does not supply a default. When the default is not in the list, a value is longer than the length, or the column is no longer a text type, the settings show what conflicts and how to repair it; nothing is silently trimmed or dropped. How generated DDL uses the list depends on the warehouse, and the settings say so in plain words:

Warehouse	Generated DDL	Enforced by the warehouse
Databricks	`ALTER TABLE ... ADD CONSTRAINT ... CHECK (column IN (...))` after the table is created	Yes, on Delta tables. A NULL still passes unless the column is NOT NULL.
Snowflake	The values are recorded on a marked line at the end of the column comment	No. Snowflake excludes CHECK constraints from `CREATE OR ALTER TABLE`, which is the form Snap Data Studio generates.

Both forms re-import: the CHECK rule and the marked comment line each restore the list, and the comment line is never duplicated across repeated exports. In DBML the list is written as an Enum block that the column references.

Default values

A default is either a Value or an Expression, chosen in the attribute’s advanced options. A value is stored exactly as typed and generated as a literal of the column’s kind, so typing now() on a text column gives the text now(), not the current time. An expression is generated as SQL, for example CURRENT_TIMESTAMP(); NULL in expression mode is the explicit NULL default. Defaults imported from DBML or SQL keep whichever kind the source declared. Defaults saved before this distinction existed are read the way generated DDL always read them.

Conversion review

Choosing a warehouse for a diagram, or switching to another one, converts each column’s physical type to the target’s vocabulary. Columns whose meaning changed are flagged on the canvas and gathered in the Conversion review drawer (the pulsing toolbar button), grouped by mapping. Each group shows the original declaration, the result, and what changes on the target, with a Keep suggested action or a replacement type. The confidence of a mapping is one of:

Confidence	Meaning
Adapted	A type from another database, re-expressed on the target with its meaning kept, such as `ENUM(...)` to a text column with allowed values, or `serial` to an identity column. Review it to read how the target enforces it.
Widened	Precision, length, or element types were dropped; values fit but constraints are looser.
Lossy	The closest available equivalent; behaviour may differ.
Opaque	No equivalent exists; the target’s default type for the column’s kind was substituted.

A conversion that changes nothing is not listed. The full record, including every decision, lives in the Warehouse conversion report document.

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

Open Settings in the sidebar (a project must be open).
Choose Naming conventions. The modal title is Naming conventions plus your project name.
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

Open a diagram that has tables.
Click Naming (Apply naming conventions) on the toolbar.
Review Naming conventions preview — “Review the highlighted renames, then apply or reject.”
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, edit the model as text, and manage annotations in one place.

DBML

DBML shows the diagram as editable DBML text: tables, columns, keys, relationships, notes, table colors, and areas as table groups. Edits reach the canvas on their own a moment after you stop typing, so there is nothing to apply. A chip beside the drawer title shows where your text stands: Syncing, Synced, or Invalid. Text that cannot sync leaves the diagram exactly as it was and lists what to fix, with the line to look at. Warnings, such as a foreign key whose type differs from the key it points to, are listed beside the editor without holding the change back. On a diagram with a warehouse, a type you write that the warehouse lacks is converted the same way an import converts it and opens the Conversion review once the edit lands; a type with impossible parameters is refused with the reason. Selecting a table or relationship on the canvas highlights the DBML that describes it, and selecting several tables highlights all of them plus the relationships between them. See Select several objects at once. If the diagram changes elsewhere while you have unsynced text, a notice says the two no longer match and lets you pick which side survives: Use the diagram discards your edits and re-derives the text, and Use my DBML applies your text over the diagram. While your text has errors, Use my DBML stays disabled until you fix them. DBML names a table as schema.table and has no place for a database or catalog. If you paste text that quotes one into the schema, such as Table "SAMPLE_DATA.CRM".QUOTE, the drawer reads SAMPLE_DATA as the table’s database (or catalog) and CRM as its schema. A table already holding a database inside its schema name cannot be written as DBML; it is listed under canvas-only details until you set the database (or catalog) and schema separately in physical settings.

What DBML carries, and what stays on the canvas

DBML is a standard text format, so anything you copy from the DBML drawer works in dbdiagram.io and every other DBML tool. The trade-off is that the standard has no syntax for some of what your canvas holds. Editing DBML on the same diagram never loses those details (live sync preserves them); the limits only matter when you paste DBML into a different diagram, which recreates the model faithfully but not the picture. Carried fully through a paste:

On the canvas	In DBML
Tables, columns, data types, schemas	`Table` declarations
Primary key, unique, not null, identity, defaults	Column settings (`pk`, `unique`, `not null`, `increment`, `default`); a default keeps its kind (quoted text, number, boolean, `null`, or a backticked expression)
Composite keys in their declared order	`indexes { (a, b) [pk] }` and `indexes { (a, b) [unique] }` blocks
Allowed values	An `Enum` block named after the table and column, which the column references
Table and column comments	`note` settings
Relationships and their direction (one/many each side), with `ON DELETE` / `ON UPDATE` actions	`Ref:` lines with `<`, `>`, `-` and `[delete: ..., update: ...]` settings
Identifying relationships	Derived from primary key coverage, recomputed on paste
Table colors	`headercolor`
Logical names (two-tier naming)	Table alias (`Table orders as "Sales Orders"`)
Areas: membership and color	`TableGroup` blocks

Not carried (stays on the source canvas):

Detail	Why DBML cannot carry it
Positions, sizes, and layout	DBML has no geometry; a paste generates a fresh layout (areas are recreated with their members laid out inside)
Sticky notes	Not attached to any table, so no DBML statement can hold them
Exact cardinality markers (`0..`, `1..`, `0..1`, `1..1`)	DBML refs only say one or many per side; pasted edges reset to the plain marker
A foreign-key mark with no relationship drawn	DBML expresses foreign keys only as `Ref:` lines, so a mark without a relationship has nothing to carry it
Tables with no columns yet	The DBML grammar rejects an empty table
Names DBML cannot write	Double quotes or line breaks in a name, dots inside a table or schema name, or two tables that would share one qualified name
Attribute-level logical names	DBML aliases exist for tables only
Relationship labels and per-edge styling	No DBML syntax exists for edge presentation
The length of a column that also has allowed values	An `Enum` reference has no place for a length; editing the same diagram keeps it
Many-to-many references	A `<>` reference is refused rather than drawn as a single foreign key; model a junction table with two `>` references

For an exact copy of a diagram, picture included, use Duplicate diagram or share the project itself; use DBML when you want the model in text form.

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 you’re building

​Start a diagram

​Create a blank diagram

​Reverse engineer (import)

​What an import keeps, converts, and reports

​Import tables into an existing diagram

​Generate a data model

​Choose a methodology

​Configure Source and Guidance

​Source

Concepts

ERD model

​Guidance

​How sources combine

​Run, cancel, and reopen

​Follow generation progress

​Understand the Data Vault design

​Follow table generation

​What gets created

​Re-run, already-modeled tables

​How your conceptual model is used

​Canvas basics

​Navigate and select

​Select several objects at once

​Toolbar

​Allowed values

​Default values

​Conversion review

​Physical names and validation

​Naming conventions

​Configure rules

​Tabs and what they control

​Impact across all diagrams

​Apply naming conventions on a diagram

​Use the copilot

​Modes

​Attachments and context

​Review staged changes

​What works well to ask

​Helper drawers

​DBML

​What DBML carries, and what stays on the canvas

​Tables

​Relationships

​Annotations

​What’s next