Entity Block

The entity block is the core building block of MML, used to define data entities and their characteristics within your data model.

Purpose

Entities represent the fundamental data objects in your model. They can be:

• Base entities (primary substances in your domain)
• Reference entities (entities with foreign key relationships)
• Calculated metrics
• Derived datasets
• Business KPIs

Entities help you document:

• What data exists in your system
• How data relates to other data
• How metrics are calculated
• The business meaning of your data

Syntax

entity identifier {
  type = "entity_type"
  description = "Entity description"
  business_logic = "Calculation or definition"

  belongs-to domain.domain_name
  derived-from entity.source_entity
  contains entity.related_entity
}

Entity Types

Entities are categorized by type to indicate their role in the ontological model.

entity

Base entities represent primary substances in your domain model - the fundamental objects that exist independently in source systems.

Characteristics:

• Represent core domain objects from source systems
• Contain both descriptive attributes and quantitative measures
• Can be primary substances (independent entities) or contain predicate properties
• Relationships to other entities are defined through contains and relationship syntax

Examples: customers, products, orders, sessions, transactions

entity customer {
  type = "entity"
  description = "Customer profiles and attributes"

  belongs-to domain.sales
}

entity order {
  type = "entity"
  description = "Sales order transactions with line items and totals"

  belongs-to domain.sales
  contains entity.customer
  contains entity.product
}

metric

Metric entities represent calculated business measures and KPIs.

Characteristics:

• Derived from other entities
• Contain business logic for calculation
• Represent aggregated or computed values
• Used for reporting and dashboards

Examples: total_revenue, conversion_rate, customer_lifetime_value

entity total_revenue {
  type = "metric"
  description = "Total revenue from all sales orders"
  business_logic = "SUM(order.total_amount)"

  belongs-to domain.sales
  derived-from entity.order
}

derivation

Derivation entities are datasets created by transforming or combining other entities.

Characteristics:

• Built from other entities through transformations
• May involve joins, filters, or aggregations
• Create intermediate or specialized datasets
• Document data transformation logic

Examples: customer cohorts, aggregated reports, enriched datasets

entity customer_cohort_analysis {
  type = "derivation"
  description = "Customer segmentation by acquisition date and behavior"
  business_logic = "GROUP customers BY acquisition_month, WITH revenue metrics"

  belongs-to domain.analytics
  derived-from entity.customer
  derived-from entity.order
}

Attributes

Required Attributes

type

The type of entity (entity, metric, or derivation).

• Type: String
• Required: Yes
• Valid values: "entity", "metric", "derivation"

entity customer {
  type = "entity"
}

Optional Attributes

description

A clear description of what the entity represents and its purpose.

• Type: String
• Required: No (but highly recommended)

entity customer {
  type = "entity"
  description = "Customer master data including contact information and preferences"
}

business_logic

The calculation, formula, or definition for how the entity is computed or derived.

• Type: String
• Required: No (but required for metrics)
• Use for: Metrics and derivations

entity monthly_recurring_revenue {
  type = "metric"
  description = "Monthly recurring revenue from active subscriptions"
  business_logic = "SUM(subscription.monthly_amount) WHERE subscription.status = 'active'"

  belongs-to domain.revenue
  derived-from entity.subscription
}

Relationships

Relationships define how entities connect to domains and other entities.

belongs-to

Indicates which domain an entity belongs to.

Syntax:

belongs-to domain.domain_identifier

Example:

entity order {
  type = "entity"

  belongs-to domain.sales
}

derived-from

Indicates which entities are used to calculate or derive this entity.

Syntax:

derived-from entity.source_entity

Example:

entity average_order_value {
  type = "metric"
  business_logic = "SUM(order.total_amount) / COUNT(order.id)"

  derived-from entity.order
}

Multiple sources:

entity customer_lifetime_value {
  type = "metric"
  business_logic = "SUM(order.total_amount) GROUP BY customer.id"

  derived-from entity.order
  derived-from entity.customer
}

contains

Indicates that this entity contains or references another entity through foreign key relationships.

Syntax:

contains entity.related_entity

Example:

entity order {
  type = "entity"
  description = "Sales order with customer and product references"

  contains entity.customer
  contains entity.product
  contains entity.order_date
}

Examples

Basic Entity

entity product {
  type = "entity"
  description = "Product catalog with SKUs, names, and categories"

  belongs-to domain.product
}

Entity with References

entity purchase_transaction {
  type = "entity"
  description = "Individual purchase transactions with customer and product details"

  belongs-to domain.sales
  contains entity.customer
  contains entity.product
  contains entity.transaction_date
}

Simple Metric

entity total_sales {
  type = "metric"
  description = "Total sales revenue across all transactions"
  business_logic = "SUM(purchase_transaction.amount)"

  belongs-to domain.sales
  derived-from entity.purchase_transaction
}

Derivation

entity high_value_customers {
  type = "derivation"
  description = "Customers with lifetime value above $10,000"
  business_logic = """
    SELECT customer.*
    FROM customer
    WHERE lifetime_value > 10000
  """

  belongs-to domain.analytics
  derived-from entity.customer
}

Complete Entity Ecosystem

domain ecommerce {
  name = "E-commerce"
  description = "Online store sales and customer data"
  color = "#1976D2"
}

// Base Entities
entity customer {
  type = "entity"
  description = "Customer profiles and contact information"

  belongs-to domain.ecommerce
}

entity product {
  type = "entity"
  description = "Product catalog with categories and pricing"

  belongs-to domain.ecommerce
}

entity order_date {
  type = "entity"
  description = "Date entity for time-based analysis"

  belongs-to domain.ecommerce
}

// Entities with References
entity order {
  type = "entity"
  description = "Customer orders with line items and totals"

  belongs-to domain.ecommerce
  contains entity.customer
  contains entity.order_date
}

entity order_line {
  type = "entity"
  description = "Individual products within an order"

  belongs-to domain.ecommerce
  contains entity.order
  contains entity.product
}

// Metrics
entity total_revenue {
  type = "metric"
  description = "Total revenue from all orders"
  business_logic = "SUM(order.total_amount)"

  belongs-to domain.ecommerce
  derived-from entity.order
}

entity average_order_value {
  type = "metric"
  description = "Average value per order"
  business_logic = "SUM(order.total_amount) / COUNT(DISTINCT order.id)"

  belongs-to domain.ecommerce
  derived-from entity.order
}

entity customer_lifetime_value {
  type = "metric"
  description = "Total revenue generated per customer"
  business_logic = "SUM(order.total_amount) GROUP BY customer.id"

  belongs-to domain.ecommerce
  derived-from entity.order
  contains entity.customer
}

// Derivations
entity monthly_revenue_by_category {
  type = "derivation"
  description = "Revenue aggregated by month and product category"
  business_logic = """
    SELECT
      order_date.month,
      product.category,
      SUM(order_line.amount) as revenue
    FROM order_line
    GROUP BY order_date.month, product.category
  """

  belongs-to domain.ecommerce
  derived-from entity.order_line
  derived-from entity.product
  derived-from entity.order_date
}

Best Practices

1. Choose the correct entity type: Use types that accurately reflect the entity's role

   // Good
   entity customer { type = "entity" }
   entity order { type = "entity" }
   entity revenue { type = "metric" }
   entity customer_cohort { type = "derivation" }
   
   // Avoid mixing types
   entity customer { type = "metric" } // Wrong - customer is a base entity

2. Always add descriptions: Help users understand what the entity represents

   entity churn_rate {
     type = "metric"
     description = "Percentage of customers who cancelled in the last 30 days"
   }

3. Document business logic: Clearly explain how metrics and derivations are calculated

   entity net_promoter_score {
     type = "metric"
     description = "NPS calculated from customer satisfaction surveys"
     business_logic = "(COUNT(promoters) - COUNT(detractors)) / COUNT(responses) * 100"
   }

4. Use meaningful names: Choose clear, descriptive identifiers

   // Good
   entity monthly_recurring_revenue
   
   // Avoid
   entity mrr

5. Define relationships: Always specify domain membership and derivation sources

   entity customer_retention_rate {
     type = "metric"
   
     belongs-to domain.analytics
     derived-from entity.customer
     derived-from entity.subscription
   }

6. Group related entities: Use domains to organize entities logically

   domain marketing { name = "Marketing" }
   
   entity campaign { belongs-to domain.marketing }
   entity lead { belongs-to domain.marketing }
   entity conversion { belongs-to domain.marketing }