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