> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snaplabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/create-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](/get-started/connect-to-data-warehouse) 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](/guides/create-conceptual-model#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](#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

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](/guides/create-conceptual-model#use-the-copilot).

## 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](/get-started/connect-to-data-warehouse)
* [Create an artifact](/guides/create-artifact)
* [Create a conceptual model](/guides/create-conceptual-model)