Getting Started with Modality

This guide will help you get up and running with Modality, from signing up to creating your first data model.

Prerequisites

Before you begin:

• A modern web browser (Chrome, Firefox, Safari, or Edge)
• A GitHub account (for authentication and Git integration)
• Basic familiarity with data modeling concepts

Sign Up

Create Your Account

1. Navigate to https://app.getmodality.io/
2. Click Sign in with GitHub to authenticate
3. Authorize Modality to access your GitHub account
4. Complete your profile setup

Modality uses GitHub OAuth for authentication, which also enables seamless Git integration for version control.

Creating Your First Project

Initialize a New Project

When you first log in, Modality will create a default project for you. You can also create additional projects:

1. Click the Projects tab in the navigation
2. Click New Project
3. Enter your project details:
   • Project Name: A descriptive name for your data model
   • Description: Brief overview of what this model represents

Projects are automatically saved to Modality's backend with auto-save every 2 seconds as you work.

Set Up Git Integration (Recommended)

Git integration is a powerful feature that enables version-controlled management of your MML files. Your models are stored as human-readable YAML-based MML files that can be tracked in Git.

Connect Your Repository

1. In your project, navigate to the Git integration settings
2. Click Connect Repository
3. Select an existing repository or create a new one
4. Choose the branch you want to sync with (typically main)
5. Click Connect

Benefits of Git Integration

• Version Control: Track every change to your data model with full Git history
• Collaboration: Review changes via pull requests with your team
• Smart Merge: Modality's intelligent merge preserves local changes when pulling updates
• Rollback: Revert to previous versions when needed
• Import/Export: Import existing MML files from your repo or push changes back

Understanding Modality's Interface

Modality has seven main sections accessible via the navigation tabs:

1. Dashboard - Overview of your models and recent activity
2. Conceptual - Design your business-level data architecture
3. Logical - Map conceptual entities to source systems
4. Data Products - Define consumption-ready datasets and metrics
5. Evaluations - Analyze model complexity and semantic drift
6. Estimating - Plan development effort and costs
7. Roadmapping - Create project timelines and task dependencies

Building Your Data Model

Modality uses a visual interface to build data models, automatically generating MML files behind the scenes. As you work, your changes are auto-saved every 2 seconds.

1. Conceptual Model

Start by defining your high-level data architecture with domains and entities.

Create a Domain

1. Navigate to the Conceptual tab
2. Add a new domain to organize your entities
3. Configure the domain:
   • Name: "Sales"
   • Description: "Sales and revenue tracking"
   • Color: Choose a color for visual organization

Domains help organize entities by business area and appear as colored groups in the visual interface.

Add Entities

Add entities to your domain:

1. Within a domain, add a new entity
2. Set the entity details:
   • Name: "customer"
   • Type: "entity" (base entity)
   • Description: "Customer master data"

Entity types include:

• entity: Base entities from source systems
• derived: Calculated or transformed entities
• aggregate: Aggregated metrics and KPIs

Define Relationships

Use the visual relationship builder to connect entities:

• belongs-to: Assigns an entity to a domain
• has-many: Defines one-to-many relationships
• derived-from: Shows which entities a metric or derivation depends on

The visual interface uses ReactFlow to display these relationships as an interactive graph that you can zoom, pan, and filter.

Behind the scenes, this generates MML:

domain sales {
  name = "Sales"
  description = "Sales and revenue tracking"
  color = "#2E7D32"
}

entity customer {
  type = "entity"
  description = "Customer master data"
  belongs-to domain.sales
}

entity order {
  type = "entity"
  description = "Sales orders and transactions"
  belongs-to domain.sales
  has-many entity.customer
}

entity total_revenue {
  type = "derived"
  description = "Total revenue from all orders"
  business_logic = "SUM(order.total_amount)"
  belongs-to domain.sales
  derived-from entity.order
}

2. Logical Model

Map your conceptual entities to actual source systems.

Add Source Systems

1. Navigate to the Logical tab
2. Add a new source system
3. Configure the source:
   • Name: "salesforce"
   • Type: Select from postgres, mysql, bigquery, snowflake, api, csv, etc.
   • Description: "Salesforce CRM"

Create Entity Mappings

Map source tables/objects to your conceptual entities:

1. Within a source, create entity mappings
2. Specify which source table maps to which conceptual entity
3. Add transformation logic if needed

This establishes data lineage, showing where conceptual entities originate in your source systems. The logical view visualizes these mappings.

Example MML:

source salesforce {
  type = "api"
  description = "Salesforce CRM"

  entity account {
    description = "Salesforce Account object"
    maps-to entity.customer
  }

  entity opportunity {
    description = "Salesforce Opportunity object"
    maps-to entity.order
  }
}

3. Data Products

Define consumption-ready data products for your stakeholders.

Create a Data Product

1. Navigate to the Data Products tab
2. Create a new data product
3. Configure the product:
   • Name: "Customer Analytics"
   • Type: dataset, metric, api, report, or ml_feature
   • Description: "Customer behavior and revenue analytics"
   • Owner: Assign an owner
   • Refresh Schedule: hourly, daily, or custom

Define Fields and Metrics

For dataset products, define fields:

• Field name and data type
• Source mapping (which entity it comes from)
• Transformation logic
• PII marking for governance

For metric products, define:

• Calculation (SUM, AVG, COUNT, etc.)
• Dimensions (group by fields)
• Filters (WHERE conditions)

Example MML:

product customer_analytics {
  name = "Customer Analytics"
  type = "dataset"
  description = "Customer behavior and revenue analytics"
  owner = "data-team"
  refresh_schedule = "daily"

  field customer_id {
    type = "string"
    source = "entity.customer.id"
    description = "Unique customer identifier"
  }

  field total_revenue {
    type = "decimal"
    source = "entity.total_revenue"
    description = "Lifetime customer revenue"
  }
}

Visualization

Modality automatically generates interactive visualizations of your model:

Conceptual View

• See all domains and their entities as a graph
• Color-coded by domain
• Interactive with zoom, pan, and filtering
• Click entities to see details and relationships

Logical View

• Visualize data lineage from sources to conceptual entities
• See all source system mappings
• Trace where data originates

Data Products Portfolio

• View all data products and their dependencies
• See which entities each product uses
• Understand product relationships

Evaluation and Quality

Navigate to the Evaluations tab to analyze your model:

Semantic Entropy Analysis

• Measures model complexity and stability
• Tracks semantic drift over time
• Identifies areas of high complexity
• Charts showing entropy metrics

Model Quality Metrics

• Entity count and relationship density
• Naming consistency
• Documentation completeness
• Relationship patterns

Estimation and Planning

Estimate Development Effort

Navigate to the Estimating tab to plan implementation:

1. Select entities, sources, or reports to estimate
2. Set effort estimates in hours or days
3. Configure data quality level (bronze, silver, gold)
4. Add infrastructure cost projections
5. View total effort and cost summaries

Modality includes sophisticated estimation models that consider:

• Entity complexity
• Data volume projections
• Transformation logic
• Integration requirements
• Infrastructure costs (BigQuery, Snowflake, etc.)

Example MML:

estimate customer_analytics_build {
  description = "Build customer analytics data product"

  entity customer {
    effort_hours = 40
    data_quality_level = "gold"
    notes = "Complex entity with PII considerations"
  }

  entity order {
    effort_hours = 24
    data_quality_level = "silver"
  }

  infrastructure {
    platform = "bigquery"
    storage_tb = 0.5
    queries_per_day = 100
    estimated_monthly_cost = 150
  }
}

Create Roadmaps

Navigate to the Roadmapping tab to plan your project:

1. Create tasks for building entities and data products
2. Set task durations and effort
3. Define dependencies between tasks
4. Assign tasks to sprints or phases
5. View Gantt chart timeline
6. Export roadmap for stakeholder communication

The roadmap view provides:

• Visual Gantt chart of all tasks
• Critical path analysis
• Sprint planning support
• Timeline visualization
• Dependency tracking

Working with Git

Import Existing MML Files

If you have existing MML files in a repository:

1. Connect your repository (see Git Integration section)
2. Modality will automatically discover and import MML files
3. Your models will appear in the visual interface
4. Edit visually or directly in MML

Push Changes to Git

As you work in the visual interface:

1. Changes are auto-saved to Modality's backend every 2 seconds
2. When ready, push your changes to Git
3. MML files are generated and committed to your repository
4. Create pull requests for team review

Pull Updates from Git

When team members make changes:

1. Pull updates from your Git repository
2. Modality uses smart merge to preserve your local changes
3. Conflicts are detected and highlighted
4. You can review and resolve any conflicts before accepting changes

This workflow enables true version control for data models with Git as the source of truth.

Collaboration

Team Workflows

Modality is built for team collaboration:

• Shared Projects: Multiple team members can work on the same project
• Git Integration: Use pull requests for peer review
• Owner Assignment: Assign owners to entities and data products
• Change Tracking: Full Git history of who changed what and when
• Smart Merge: Work simultaneously without losing changes

Best Practices for Teams

1. Use Feature Branches: Create branches for major model changes
2. Pull Request Reviews: Have peers review conceptual model changes
3. Clear Commit Messages: Describe what changed and why
4. Regular Syncs: Pull updates frequently to stay in sync
5. Document Decisions: Add descriptions explaining design choices

Exporting and Integration

Export Your Model

Modality supports multiple export formats:

• MML Files: Native YAML-based format stored in Git
• JSON: Programmatic access via JSON export
• GraphQL: Query your model structure
• HTML Documentation: Auto-generated documentation
• Visual Diagrams: Interactive diagrams and static exports
• Mermaid: Diagram format for embedding in docs

Integration Options

Modality can integrate with:

BI Tools:

• Looker
• Tableau
• Power BI
• dbt (generate dbt models from your design)

Data Catalogs:

• Alation
• Collibra

Cloud Data Warehouses:

• BigQuery
• Snowflake
• PostgreSQL
• MySQL

APIs:

• REST APIs for programmatic access
• Real-time streaming integrations

Tips for Success

1. Start Conceptual, Then Logical

Begin with high-level business concepts before diving into implementation:

1. Define domains and entities (business view)
2. Add source mappings (technical view)
3. Design data products (consumption view)

2. Leverage Auto-Save

Modality auto-saves every 2 seconds, so:

• Don't worry about losing work
• Make small, incremental changes
• Experiment freely - you can always pull from Git

3. Use Git Strategically

• Commit when you reach logical milestones
• Pull regularly to stay in sync with your team
• Trust the smart merge algorithm
• Use branches for experimental designs

4. Document as You Build

Add descriptions to everything:

• Domains: Explain business area scope
• Entities: Describe what they represent
• Relationships: Note why entities are connected
• Transformations: Document business logic

5. Plan Before Building

Use the Estimating and Roadmapping features before implementation:

• Estimate effort realistically
• Identify dependencies early
• Communicate timelines with stakeholders
• Track progress against plan

Next Steps

Now that you understand Modality's workflow:

1. Explore Conceptual Modeling - Deep dive into domains and entities
2. Learn Logical Modeling - Map to source systems
3. Design Data Products - Create consumption-ready outputs
4. Master MML Syntax - Understand the underlying language
5. View Examples - Learn from real-world models

Getting Help

Documentation

• Complete MML Reference
• Core Concepts guide
• Entity Types reference
• Examples Gallery

Community

• GitHub Discussions for questions
• Community Discord (join via website)
• Blog posts and best practices

Support

Need help? Reach out:

• GitHub Issues for bug reports
• Email: support@getmodality.io
• In-app feedback system

Welcome to Modality! Start building better data models today.