Skip to main content

​
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).

​
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):

​
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

​
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. 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.

​
Toolbar

​
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

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

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

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