LookML Deployment Guide

How to manage, validate, test, and deploy LookML projects in a team environment.

Git Workflow

Looker projects are backed by Git. Follow this branching strategy:

main (production)
├── develop (staging / QA)
│   ├── feature/add-marketing-attribution
│   ├── feature/new-customer-segments
│   └── fix/subscription-churn-calc

Branch Naming

• feature/{ticket-id}-short-description
• fix/{ticket-id}-what-was-broken
• refactor/{area}-{what-changed}

Development Flow

1. Create a branch from main in Looker IDE (Develop → New Branch)

2. Make changes in Development Mode

3. Validate LookML (Develop → Validate LookML) — fix all errors

4. Run Content Validator — checks for broken references in dashboards/looks

5. Test in Dev Mode — run explores, verify data accuracy

6. Open Pull Request — request review from analytics team

7. Review & Merge — reviewer checks logic, naming, performance

8. Deploy to Production — merge to main triggers production update

Validation Checklist

Before opening a PR, verify:

LookML Validation (automated)

• [ ] No syntax errors (red squiggles in IDE)
• [ ] All sql_on references resolve correctly
• [ ] No circular dependencies between views
• [ ] All datagroup triggers have valid SQL

Content Validation

• [ ] Run Content Validator (Develop menu)
• [ ] No broken dashboards (missing fields after rename/delete)
• [ ] No broken Looks referencing removed dimensions/measures

Logic Validation (manual)

• [ ] New measures return expected values for known data
• [ ] Join relationships produce correct row counts (no fan-out)
• [ ] Filters work as expected (test with specific known values)
• [ ] Derived tables materialize without error

Performance Validation

• [ ] Run EXPLAIN on complex derived table SQL
• [ ] Check query runtime in SQL Runner for new explores
• [ ] PDTs complete materialization within acceptable time (<30 min)
• [ ] No SELECT * in derived tables — only needed columns

Testing LookML

Data Tests (Built-in)

Add data tests to verify business logic:

test: revenue_is_never_negative {
  explore_source: orders {
    column: total_revenue { field: orders.total_revenue }
    filters: [orders.order_date: "30 days"]
  }
  assert: revenue_positive {
    expression: ${orders.total_revenue} >= 0 ;;
  }
}

test: customer_count_reasonable {
  explore_source: customers {
    column: count { field: customers.total_customers }
  }
  assert: count_above_minimum {
    expression: ${customers.total_customers} > 100 ;;
  }
}

Running Tests

• Looker IDE: Develop → Run Data Tests
• Schedule weekly test runs via Looker Admin API
• Integrate with CI/CD pipeline using Spectacles or lookml-tools

Environment Management

Connection per Environment

# In model file — use environment variable or connection name convention
connection: "production_warehouse"  # production
# connection: "staging_warehouse"  # uncomment for staging

Multi-Environment Strategy

Access Control

Model-Level Access

# Restrict model to specific user groups
access_grant: finance_data {
  user_attribute: department
  allowed_values: ["finance", "executive"]
}

Field-Level Access

dimension: salary {
  type: number
  sql: ${TABLE}.salary ;;
  required_access_grants: [hr_only]
}

Row-Level Security

access_filter: {
  field: orders.region
  user_attribute: allowed_regions
}

Performance Optimization

PDT Strategy

Incremental PDT Example

derived_table: {
  datagroup_trigger: revenue_daily_refresh
  increment_key: "order_date"
  increment_offset: 3  # rebuild last 3 days to catch late-arriving data
  sql:
    SELECT
      DATE(order_timestamp) AS order_date,
      SUM(order_total) AS daily_revenue
    FROM analytics.orders
    WHERE DATE(order_timestamp) >= {% date_start order_date %}
    GROUP BY 1
  ;;
}

Monitoring & Alerting

Query Performance

• Use System Activity explores: i__looker → History
• Alert if average query time exceeds 10 seconds
• Identify top-10 slowest queries weekly

PDT Health

• Monitor in Admin → Persistent Derived Tables
• Alert if any PDT fails to rebuild for >24 hours
• Check PDT build times trend weekly

Usage Monitoring

• Track explore usage to deprecate unused models
• Monitor dashboard load times
• Identify unused fields (candidates for hiding or removal)

Deprecation Process

When removing or renaming fields:

1. Add deprecation notice to the description:

   dimension: old_field_name {
     description: "DEPRECATED: Use new_field_name instead. Will be removed 2025-03-01."
     hidden: yes  # Hide from field picker
   }

2. Run Content Validator to find all references

3. Update dashboards/looks that use the old field

4. Wait one release cycle (give users time to update saved content)

5. Remove the field in the next release

LookML Naming Conventions

Consistent naming makes a Looker project navigable by anyone on the team. Follow these rules.

Views

File naming: snake_case.view.lkml — one view per file.

Dimensions

Avoid: Prefixing dimensions with the view name (order_order_id is redundant).

Measures

Explores

Models

One model per business domain:

• revenue_analytics.model.lkml
• marketing_analytics.model.lkml
• product_analytics.model.lkml
• customer_analytics.model.lkml

Datagroups

Pattern: {domain}_{frequency}_refresh

Examples:

• revenue_daily_refresh
• events_hourly_refresh
• marketing_daily_refresh

Parameters and Filters

Labels and Descriptions

• Labels: Title Case, human-readable. "Revenue (QTD)", "Cost per Click"
• Descriptions: One sentence explaining what, not how. End with period.
• Group Labels: Used to organize fields in the explorer sidebar. Keep to 5-8 groups per view.

Good description:

"Total revenue from completed orders after discounts, before tax."

Bad description:

"Sums the order_total field."

File Organization

project/
├── models/              # One .model.lkml per domain
├── views/
│   ├── {domain}/        # Grouped by business domain
│   └── shared/          # Cross-domain views (calendar, common)
├── explores/            # If explores are defined separately
├── derived_tables/      # PDTs and NDTs in their own files
├── refinements/         # Refinement files (never modify originals)
├── dashboards/          # LookML dashboards
└── tests/               # Data tests

Anti-Patterns to Avoid