Semantic Layer

semantic/
├── catalog.yml              # Index of all entities with use_for guidance
├── glossary.yml             # Business term definitions and disambiguation
├── entities/                # One YAML per table or view
│   ├── customers.yml
│   ├── orders.yml
│   └── products.yml
├── metrics/                 # Metric definitions per entity
│   ├── customers.yml
│   └── orders.yml
└── warehouse/               # Per-source directory (multi-datasource)
    └── entities/
        └── events.yml

# semantic/entities/orders.yml
name: Orders
type: fact_table                      # dimension_table, fact_table, or view
table: orders                         # Database table name (can be schema-qualified: analytics.orders)
grain: one row per order
description: |
  Customer orders with line items, totals, and fulfillment status.
  Each row represents a single order placed by a customer.

dimensions:
  - name: id
    sql: id
    type: integer
    description: Unique order identifier
    primary_key: true
    sample_values: [1001, 1002, 1003]

  - name: status
    sql: status
    type: string
    description: Current order status
    sample_values: [pending, shipped, delivered, cancelled]

  - name: order_month
    sql: "DATE_TRUNC('month', created_at)"
    type: date
    description: Month the order was placed
    virtual: true                     # Computed column (not a raw DB column)

measures:
  - name: order_count
    sql: id
    type: count_distinct
    description: Total number of unique orders

  - name: total_revenue
    sql: total_amount
    type: sum
    description: Sum of order totals

joins:
  - target_entity: Customers
    relationship: many_to_one
    join_columns:
      from: customer_id
      to: id
    description: orders.customer_id → customers.id

virtual_dimensions:
  - name: order_size_bucket
    sql: |
      CASE
        WHEN total_amount < 50 THEN 'small'
        WHEN total_amount < 200 THEN 'medium'
        ELSE 'large'
      END
    type: string
    description: Order size category based on total amount

query_patterns:
  - description: Revenue by month
    sql: |
      SELECT DATE_TRUNC('month', created_at) AS month,
             SUM(total_amount) AS revenue
      FROM orders
      GROUP BY 1
      ORDER BY 1

use_cases:
  - Revenue analysis and forecasting
  - Order fulfillment tracking

cross_source_joins:                   # Optional: joins to other datasources
  - source: warehouse
    target_table: events
    on: "orders.id = events.order_id"
    relationship: one_to_many
    description: Join orders to event stream in warehouse

version: "1.0"
name: Acme Analytics
description: Sales and customer analytics for Acme Corp

entities:
  - name: Orders
    file: entities/orders.yml
    grain: one row per order
    description: Customer orders with line items and totals
    use_for:
      - Revenue analysis
      - Order volume tracking
    common_questions:
      - What was last month's revenue?
      - How many orders were placed this week?

  - name: Customers
    file: entities/customers.yml
    grain: one row per customer
    description: Customer profiles and account information
    use_for:
      - Customer segmentation
      - Churn analysis
    common_questions:
      - How many active customers do we have?

glossary: glossary.yml

metrics:
  - file: metrics/orders.yml
    description: Order and revenue metrics

terms:
  revenue:
    status: defined
    definition: |
      Total order amount after discounts, before tax.
      Calculated as SUM(orders.total_amount).
    tables:
      - orders

  status:
    status: ambiguous
    note: |
      "Status" appears in multiple tables with different meanings.
      Ask the user which entity they mean.
    tables:
      - orders
      - customers
      - shipments
    possible_mappings:
      - orders.status
      - customers.account_status
      - shipments.delivery_status

  active_customer:
    status: defined
    definition: A customer with at least one order in the last 90 days.
    tables:
      - customers
      - orders

metrics:
  - id: total_revenue
    label: Total Revenue
    description: Sum of all order totals after discounts
    type: atomic
    unit: USD
    sql: |
      SELECT SUM(total_amount) AS total_revenue
      FROM orders
    aggregation: sum
    objective: maximize

  - id: revenue_by_month
    label: Revenue by Month
    description: Monthly revenue breakdown
    type: breakdown
    unit: USD
    sql: |
      SELECT DATE_TRUNC('month', created_at) AS month,
             SUM(total_amount) AS revenue
      FROM orders
      GROUP BY 1
      ORDER BY 1
    aggregation: sum
    objective: maximize
    source:
      entity: Orders
      measure: total_revenue

  - id: average_order_value
    label: Average Order Value
    description: Average revenue per order
    type: derived
    unit: USD
    sql: |
      SELECT AVG(total_amount) AS avg_order_value
      FROM orders
    aggregation: avg
    objective: maximize

bun run atlas -- init                    # Profile all tables and views
bun run atlas -- init --tables t1,t2     # Profile specific tables
bun run atlas -- init --enrich           # Add LLM-generated descriptions
bun run atlas -- init --schema analytics # Profile a non-public schema

bun run atlas -- diff                    # Compare DB schema vs YAML files