CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-lightdash--cli

Command-line interface for managing dbt projects and integrating with Lightdash

Overview
Eval results
Files

validation.mddocs/

Project Validation

Validate Lightdash projects by running validation jobs on tables, charts, and dashboards.

Capabilities

Validate

Runs validation jobs to check the integrity of tables, charts, and dashboards in a Lightdash project.

lightdash validate [options]

Inherits all compilation options (see dbt Compilation), plus:

Validation Options:

  • --project <project uuid> - Project UUID to validate (overrides active project)
  • --preview - Validate last preview project (default: false)
  • --only <elems...> - Specify elements to validate (multiple values allowed)
    • Choices: tables, charts, dashboards (from ValidationTarget enum in @lightdash/common)
    • Default: All three (tables, charts, dashboards)
  • --use-dbt-list [true|false] - Use dbt list instead of dbt compile to generate dbt manifest.json (default: true)

Usage Examples:

# Validate all elements in active project
lightdash validate

# Validate specific project by UUID
lightdash validate --project abc-123-def-456

# Validate last preview project
lightdash validate --preview

# Validate only tables
lightdash validate --only tables

# Validate tables and charts (not dashboards)
lightdash validate --only tables charts

# Validate only dashboards
lightdash validate --only dashboards

# Validate with model selection
lightdash validate --select customers orders

# Validate with verbose output
lightdash validate --verbose

# CI/CD: Validate preview in pipeline
export CI=true
lightdash validate --preview --only tables charts

Validation Types

Table Validation

Validates table/model definitions and explores:

lightdash validate --only tables

Checks:

  • Table schema is valid
  • Fields are correctly defined
  • Metrics are properly configured
  • Dimensions have valid types
  • Joins are correctly specified
  • No circular dependencies
  • SQL compiles successfully

Common Issues Detected:

  • Missing or invalid field references
  • Type mismatches
  • Invalid metric SQL
  • Broken dimension references
  • Invalid join conditions

Example Output:

Validating tables...
✓ customers - 15 fields validated
✓ orders - 12 fields validated
✗ payments - Error: Invalid field reference 'amount_cents'

Chart Validation

Validates saved charts in the project:

lightdash validate --only charts

Checks:

  • Chart queries are valid
  • Referenced fields exist
  • Filters are properly configured
  • Metrics are accessible
  • Dimensions are valid
  • Sort configurations are correct
  • Chart type is supported
  • All chart tiles load successfully

Common Issues Detected:

  • Deleted or renamed fields used in charts
  • Invalid filter values
  • Broken metric references
  • Removed dimensions in queries
  • Invalid aggregation types

Example Output:

Validating charts...
✓ Monthly Revenue - Valid
✓ Customer Segmentation - Valid
✗ Order Analysis - Error: Field 'orders.total_amount' not found
✗ Sales Dashboard Chart - Error: Invalid filter on 'status'

Dashboard Validation

Validates dashboards and their tiles:

lightdash validate --only dashboards

Checks:

  • Dashboard structure is valid
  • All tiles are properly configured
  • Referenced charts exist and are valid
  • Filters are compatible across tiles
  • Dashboard queries execute successfully
  • Layout configuration is correct

Common Issues Detected:

  • Broken chart references in tiles
  • Invalid dashboard filters
  • Incompatible filter configurations
  • Missing or deleted charts
  • Invalid tile configurations

Example Output:

Validating dashboards...
✓ Executive Dashboard - 8 tiles validated
✗ Sales Overview - Error: Chart 'regional-sales' not found
✓ Marketing Metrics - 5 tiles validated

Validation Process

1. Compilation Phase

If validation includes tables:

  • Compiles dbt project (unless --skip-dbt-compile)
  • Fetches warehouse catalog (unless --skip-warehouse-catalog)
  • Generates Lightdash explores
  • Validates explore structure

2. Validation Job Creation

  • Creates validation job in Lightdash
  • Specifies validation targets (tables, charts, dashboards)
  • Applies model selection if specified

3. Job Execution

Lightdash server:

  • Runs validation checks in parallel
  • Tests queries against warehouse (for charts/dashboards)
  • Verifies schema integrity
  • Checks reference validity

4. Results Collection

  • Polls job status
  • Collects validation results
  • Identifies errors and warnings
  • Generates summary report

5. Exit Code

  • Exit 0 - All validations passed
  • Exit 1 - One or more validations failed

Validation Targets

Validate Everything (Default)

lightdash validate

Validates:

  • All tables/explores
  • All saved charts
  • All dashboards

Use when:

  • Comprehensive project health check
  • Before major releases
  • After significant model changes
  • In CI/CD pipelines

Selective Validation

# Only tables
lightdash validate --only tables

# Only charts
lightdash validate --only charts

# Only dashboards
lightdash validate --only dashboards

# Multiple targets
lightdash validate --only tables charts

Use when:

  • Focused validation needed
  • Faster validation cycle
  • Testing specific changes
  • Debugging specific issues

Project Selection

Active Project (Default)

# Validates project from config
lightdash validate

Uses project from:

  1. --project option (highest priority)
  2. LIGHTDASH_PROJECT environment variable
  3. Active project in config file

Specific Project

# Validate by UUID
lightdash validate --project abc-123-def-456

Use when:

  • Validating different project than active
  • Running validation scripts
  • CI/CD for multiple projects

Preview Project

# Validate last preview
lightdash validate --preview

Uses preview project from:

  • Last preview or start-preview command
  • Saved in config as previewProject

Use when:

  • Testing changes in preview
  • CI/CD preview validation
  • Before merging pull requests

Compilation Options

Validation inherits all compilation options:

Model Selection

# Validate specific models
lightdash validate --select customers orders

# Validate with tag
lightdash validate --select tag:production

# Validate excluding models
lightdash validate --exclude test_*

# Validate using predefined dbt selector
lightdash validate --selector my_selector

Effect:

  • Only validates tables/charts/dashboards related to selected models
  • Faster validation for focused changes

dbt Execution Options

# Use more threads for faster compilation
lightdash validate --threads 8

# Skip dbt version check
lightdash validate --no-version-check

# Use state directory for dbt state comparison
lightdash validate --state ./prod-state

# Use predefined dbt selector
lightdash validate --selector my_selector

# Full refresh for incremental models
lightdash validate --full-refresh

Fast Validation

# Skip warehouse catalog
lightdash validate --skip-warehouse-catalog

# Use existing manifest
lightdash validate --skip-dbt-compile

# No warehouse credentials (tables only)
lightdash validate --only tables --no-warehouse-credentials

Trade-offs:

  • Faster validation
  • May miss warehouse-specific issues
  • Good for CI/CD

CI/CD Integration

GitHub Actions Example

name: Validate Lightdash

on:
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Lightdash CLI
        run: npm install -g @lightdash/cli

      - name: Create Preview
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_PROJECT: ${{ secrets.LIGHTDASH_PROJECT }}
          CI: true
        run: lightdash start-preview --name pr-${{ github.event.pull_request.number }}

      - name: Validate Preview
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          CI: true
        run: lightdash validate --preview --only tables charts

      - name: Cleanup
        if: always()
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          CI: true
        run: lightdash stop-preview --name pr-${{ github.event.pull_request.number }}

Validation Script

#!/bin/bash
set -e

echo "Running Lightdash validation..."

# Set environment
export LIGHTDASH_API_KEY="${SECRET_TOKEN}"
export LIGHTDASH_PROJECT="${PROJECT_UUID}"
export CI=true

# Validate tables first (fast)
echo "Validating tables..."
if ! lightdash validate --only tables --no-warehouse-credentials; then
  echo "Table validation failed!"
  exit 1
fi

# Validate charts and dashboards
echo "Validating charts and dashboards..."
if ! lightdash validate --only charts dashboards; then
  echo "Content validation failed!"
  exit 1
fi

echo "All validations passed!"

Validation Workflows

Pre-Deployment Validation

# Before deploying to production
lightdash compile
lightdash validate --only tables
lightdash validate --only charts dashboards
lightdash deploy

Preview Validation

# Test changes in preview
lightdash preview --name test-feature

# In another terminal:
lightdash validate --preview

# If valid, deploy to production
lightdash deploy

# Cleanup
lightdash stop-preview --name test-feature

Scheduled Validation

# Daily cron job to check project health
0 6 * * * lightdash validate --project prod-uuid >> /var/log/lightdash-validate.log 2>&1

Post-Deployment Validation

# After deployment, verify integrity
lightdash deploy
lightdash validate --only charts dashboards

Error Handling

Validation Failures

When validation fails, CLI provides:

  • List of failed items
  • Error messages for each failure
  • Summary of pass/fail counts
  • Non-zero exit code

Example Error Output:

Validating tables...
✓ customers
✓ orders
✗ payments
  Error: Field 'amount_cents' referenced but not defined

Validating charts...
✓ Monthly Revenue
✗ Order Analysis
  Error: Field 'orders.total_amount' not found

Validating dashboards...
✓ Executive Dashboard
✗ Sales Overview
  Error: Chart 'regional-sales' not found in project

Validation failed: 3 errors found

Exit Codes

Exit Code 0:

lightdash validate
echo $?  # 0
# All validations passed

Exit Code 1:

lightdash validate
echo $?  # 1
# One or more validations failed

Performance Considerations

Validation Speed

Factors affecting speed:

  • Number of tables/charts/dashboards
  • Complexity of queries
  • Warehouse performance
  • Model selection scope

Typical Times:

  • Tables only: 1-5 minutes
  • Charts: 2-10 minutes
  • Dashboards: 2-10 minutes
  • All: 5-20 minutes

Optimization Strategies

1. Use Model Selection:

# Only validate changed models
lightdash validate --select customers

2. Skip Warehouse Operations:

# Tables only, no warehouse
lightdash validate --only tables --skip-warehouse-catalog

3. Validate in Stages:

# Fast table check first
lightdash validate --only tables

# Then content
if [ $? -eq 0 ]; then
  lightdash validate --only charts dashboards
fi

4. Use Preview for Testing:

# Validate in preview, not production
lightdash validate --preview

Validation vs. Compilation

Compilation

lightdash compile
  • Checks dbt models compile
  • Validates SQL syntax
  • Verifies warehouse connections
  • Generates explores
  • Does NOT check charts/dashboards

Validation

lightdash validate
  • Checks explores are valid
  • Validates charts work
  • Verifies dashboards load
  • Tests saved content integrity
  • Includes compilation step for tables

Use both:

# Check models compile
lightdash compile

# Check content works
lightdash validate

Permission Requirements

Project Access

Required permissions:

  • Viewer or higher role on project
  • Read access to project

Validation Execution

Required permissions:

  • Ability to create validation jobs
  • Developer role recommended
  • Warehouse credentials (for chart/dashboard validation)

Error if insufficient permissions:

ForbiddenError: You don't have permission to validate this project

Troubleshooting

Authentication Errors

Error: "AuthorizationError"

  • Not logged in or token expired
  • Solution: lightdash login

Project Not Found

Error: "Project not found"

  • Invalid project UUID
  • Project was deleted
  • Solution: Check project UUID or use lightdash config set-project

Preview Not Found

Error: "No preview project found"

  • No preview created yet
  • Preview was manually deleted
  • Solution: Create preview with lightdash preview or lightdash start-preview

Validation Timeout

Error: "Validation job timeout"

  • Large project taking too long
  • Warehouse performance issues
  • Solution: Use --only to validate subsets, optimize warehouse

Chart Validation Fails

Error: "Chart query failed"

  • Invalid field references
  • Warehouse connection issues
  • SQL errors in metrics
  • Solution: Check chart in UI, verify field definitions, test query manually

Table Validation Fails

Error: "Table compilation failed"

  • dbt compilation errors
  • Invalid SQL in models
  • Missing dependencies
  • Solution: Run dbt compile manually, check model SQL, verify dependencies

Best Practices

1. Validate Early and Often

# In development workflow
git checkout -b feature-branch
# Make changes...
lightdash validate --preview

2. Use CI/CD Validation

# Always validate in pull requests
on: pull_request
  steps:
    - run: lightdash validate --preview

3. Validate Before Deployment

# Pre-deployment checklist
lightdash validate
if [ $? -eq 0 ]; then
  lightdash deploy
else
  echo "Fix validation errors before deploying"
  exit 1
fi

4. Target Validation to Changes

# If changing orders model
lightdash validate --select orders

5. Separate Table and Content Validation

# Fast table validation in CI
lightdash validate --only tables --no-warehouse-credentials

# Slower content validation on schedule
lightdash validate --only charts dashboards

6. Monitor Validation Health

# Regular scheduled validation
# Alert on failures
# Track validation trends over time

7. Document Validation Requirements

# Project Guidelines

## Pre-Merge Checklist
- [ ] Run `lightdash validate --preview`
- [ ] All validations pass
- [ ] No errors in tables, charts, or dashboards

Validation Reports

Success Report

Validating project: Production Analytics

Validating tables... (25 tables)
✓ All tables validated successfully

Validating charts... (87 charts)
✓ All charts validated successfully

Validating dashboards... (12 dashboards)
✓ All dashboards validated successfully

Summary:
  Tables: 25 passed, 0 failed
  Charts: 87 passed, 0 failed
  Dashboards: 12 passed, 0 failed

Validation completed successfully!

Failure Report

Validating project: Production Analytics

Validating tables... (25 tables)
✓ customers
✓ orders
✗ payments
  Error: Field 'amount_cents' not defined
✓ products
... (21 more tables)

Validating charts... (87 charts)
✓ Monthly Revenue
✗ Payment Analysis
  Error: Field 'payments.amount_cents' not found
✓ Customer Segmentation
... (84 more charts)

Validating dashboards... (12 dashboards)
✓ Executive Dashboard
✓ Sales Overview
✗ Finance Dashboard
  Error: Chart 'Payment Analysis' contains errors
... (9 more dashboards)

Summary:
  Tables: 24 passed, 1 failed
  Charts: 86 passed, 1 failed
  Dashboards: 11 passed, 1 failed

Validation failed with 3 errors

Validation in Different Environments

Development

# Validate frequently during development
lightdash validate --preview --only tables

Staging

# Full validation before production
lightdash validate --project staging-uuid

Production

# Regular health checks
lightdash validate --project prod-uuid

CI/CD

# Fast validation in pipelines
lightdash validate --only tables --no-warehouse-credentials

Install with Tessl CLI

npx tessl i tessl/npm-lightdash--cli

docs

additional.md

authentication.md

code-management.md

compilation.md

deployment.md

generation.md

index.md

preview.md

refactoring.md

validation.md

tile.json