or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

additional.mdauthentication.mdcode-management.mdcompilation.mddeployment.mdgeneration.mdindex.mdpreview.mdrefactoring.mdvalidation.md
tile.json

refactoring.mddocs/

Content Refactoring

Rename models and fields across all charts and dashboards in a project.

Capabilities

Rename

Renames models or fields in saved charts and dashboards, automatically updating all references.

lightdash rename [options]

Options:

Required:

  • -t, --type <type> - [REQUIRED] Type of rename operation: model or field
  • --from <from> - [REQUIRED] Current name to replace (lowercase + underscores only)
  • --to <to> - [REQUIRED] New name (lowercase + underscores only)

Conditional:

  • -m, --model <model> - Model name (required when --type field)

Project Selection:

  • -p, --project <project uuid> - Project UUID (overrides active project)

Execution Control:

  • -y, --assume-yes - Auto-confirm prompts (default: false)
  • --dry-run - Test run without committing changes (default: false)
  • --list - List all affected charts/dashboards (default: false)
  • --verbose - Enable debug logging (default: false)

Usage Examples:

# Rename a model
lightdash rename --type model --from customers --to dim_customers

# Rename a field in a model
lightdash rename --type field --model orders --from total --to total_amount

# Dry run to preview changes
lightdash rename --type model --from orders --to fact_orders --dry-run

# List affected charts and dashboards
lightdash rename --type field --model customers --from name --to customer_name --list

# Auto-confirm (non-interactive)
lightdash rename --type model --from products --to dim_products --assume-yes

# Rename in specific project
lightdash rename --type model --from orders --to fact_orders --project abc-123

# Rename with verbose output
lightdash rename --type model --from orders --to fact_orders --verbose

Rename Types

Model Rename

Renames a dbt model across all charts and dashboards.

lightdash rename --type model --from <old_name> --to <new_name>

What Gets Updated:

  1. Chart Queries:

    • Explore names
    • Table references
    • Join references
    • Field prefixes

  2. Dashboard Filters:

    • Table targets
    • Field references

  3. Saved Filters:

    • Model references

Example:

# Rename "orders" to "fact_orders"
lightdash rename --type model --from orders --to fact_orders

Before:

metricQuery:
  exploreName: orders
  dimensions:
    - orders_order_date
  metrics:
    - orders_total_revenue

After:

metricQuery:
  exploreName: fact_orders
  dimensions:
    - fact_orders_order_date
  metrics:
    - fact_orders_total_revenue

Field Rename

Renames a field within a specific model.

lightdash rename --type field --model <model_name> --from <old_field> --to <new_field>

What Gets Updated:

  1. Chart Queries:

    • Dimension references
    • Metric references
    • Sort fields
    • Filter targets

  2. Dashboard Filters:

    • Field targets
    • Filter configurations

  3. Chart Configurations:

    • Axis field references
    • Series field references
    • Pivot fields

Example:

# Rename "total" to "total_amount" in orders model
lightdash rename --type field --model orders --from total --to total_amount

Before:

metricQuery:
  exploreName: orders
  dimensions:
    - orders_order_date
  metrics:
    - orders_total
  sorts:
    - fieldId: orders_total
      descending: true

After:

metricQuery:
  exploreName: orders
  dimensions:
    - orders_order_date
  metrics:
    - orders_total_amount
  sorts:
    - fieldId: orders_total_amount
      descending: true

Name Validation

Naming Rules

Names must follow strict validation:

Pattern: /^[a-z_]+$/

Valid characters:

  • Lowercase letters: a-z
  • Underscores: _
  • No spaces, hyphens, or uppercase

Valid names:

# Good
lightdash rename --type model --from orders --to fact_orders
lightdash rename --type field --model customers --from name --to customer_name
lightdash rename --type model --from my_model --to my_new_model

Invalid names:

# Bad - uppercase
lightdash rename --type model --from Orders --to FactOrders

# Bad - hyphens
lightdash rename --type model --from orders --to fact-orders

# Bad - spaces
lightdash rename --type field --model customers --from "first name" --to "customer name"

# Bad - numbers anywhere (not allowed by validation pattern)
lightdash rename --type model --from orders --to orders_2024

# Bad - special characters
lightdash rename --type model --from orders --to orders!

Rename Process

1. Validation Phase

  • Validates --from and --to names match pattern
  • Checks model exists (for field rename)
  • Verifies user has permissions
  • Authenticates to Lightdash

2. Discovery Phase

  • Searches all charts in project
  • Searches all dashboards in project
  • Identifies affected content
  • Counts references to rename

Output:

Searching for references to "orders"...
Found 25 charts using "orders"
Found 8 dashboards using "orders"
Total: 33 items to update

3. Preview Phase (if --list or --dry-run)

With --list:

lightdash rename --type model --from orders --to fact_orders --list

Output:

Affected Charts:
  - Monthly Revenue (monthly-revenue)
  - Order Analysis (order-analysis)
  - Customer Orders (customer-orders)
  ... (22 more)

Affected Dashboards:
  - Executive Dashboard (executive-dashboard)
  - Sales Overview (sales-overview)
  ... (6 more)

With --dry-run:

lightdash rename --type model --from orders --to fact_orders --dry-run

Output:

DRY RUN - No changes will be committed

Would update 25 charts:
  ✓ Monthly Revenue
  ✓ Order Analysis
  ✓ Customer Orders
  ... (22 more)

Would update 8 dashboards:
  ✓ Executive Dashboard
  ✓ Sales Overview
  ... (6 more)

Total: 33 items would be updated

4. Confirmation Phase (Interactive)

Without --assume-yes:

Found 33 items to update.
This will modify:
  - 25 charts
  - 8 dashboards

Are you sure you want to rename "orders" to "fact_orders"? (y/N)

With --assume-yes:

  • Skips confirmation
  • Proceeds directly to execution
  • Suitable for CI/CD

5. Execution Phase

  • Updates each chart
  • Updates each dashboard
  • Commits changes to Lightdash
  • Reports progress and results

Output:

Renaming "orders" to "fact_orders"...

Updating charts... (25/25)
✓ Monthly Revenue
✓ Order Analysis
✓ Customer Orders
... (22 more)

Updating dashboards... (8/8)
✓ Executive Dashboard
✓ Sales Overview
... (6 more)

Successfully renamed "orders" to "fact_orders"
Updated 25 charts and 8 dashboards

Dry Run Mode

Test rename without making changes:

lightdash rename --type model --from orders --to fact_orders --dry-run

Behavior:

  • Searches for references
  • Shows what would be updated
  • Does NOT commit changes
  • Safe for testing

Use when:

  • Testing rename scope
  • Verifying impact
  • Planning refactoring
  • Documenting changes

Output shows:

  • Number of affected items
  • List of charts/dashboards
  • References that would change
  • NO actual updates made

List Mode

Show affected content without details:

lightdash rename --type field --model customers --from name --to customer_name --list

Behavior:

  • Lists all affected charts
  • Lists all affected dashboards
  • Does NOT show change details
  • Does NOT make changes

Use when:

  • Want quick overview
  • Need affected item list
  • Planning refactoring
  • Documenting dependencies

Use Cases

1. Model Naming Conventions

Standardize model names:

# Apply naming convention: prefix with fact_ or dim_
lightdash rename --type model --from orders --to fact_orders
lightdash rename --type model --from customers --to dim_customers
lightdash rename --type model --from products --to dim_products

2. Field Clarity

Make field names more descriptive:

# Improve field names
lightdash rename --type field --model orders --from total --to total_amount
lightdash rename --type field --model customers --from name --to customer_name
lightdash rename --type field --model orders --from date --to order_date

3. dbt Refactoring

Keep Lightdash in sync with dbt changes:

# After renaming in dbt
# 1. Rename in dbt
# models/orders.sql → models/fact_orders.sql

# 2. Rename in Lightdash
lightdash rename --type model --from orders --to fact_orders

# 3. Redeploy
lightdash deploy --select fact_orders

4. Database Migration

Update after database schema changes:

# Database column renamed: customer_id → user_id
lightdash rename --type field --model customers --from customer_id --to user_id

5. Cleanup Legacy Names

Remove outdated naming:

# Update old abbreviations
lightdash rename --type field --model orders --from cust_id --to customer_id
lightdash rename --type field --model orders --from amt --to amount

Refactoring Workflow

Safe Refactoring Process

# 1. List affected content
lightdash rename --type model --from orders --to fact_orders --list

# 2. Dry run to preview
lightdash rename --type model --from orders --to fact_orders --dry-run

# 3. Review impact
# (Check list of affected charts/dashboards)

# 4. Execute rename
lightdash rename --type model --from orders --to fact_orders

# 5. Validate results
lightdash validate --only charts dashboards

# 6. Test affected charts manually

Batch Refactoring

Rename multiple items:

#!/bin/bash
# Script: refactor_models.sh

# Rename all models to follow convention
lightdash rename --type model --from orders --to fact_orders -y
lightdash rename --type model --from customers --to dim_customers -y
lightdash rename --type model --from products --to dim_products -y

# Validate after all renames
lightdash validate

Coordinated dbt + Lightdash Refactoring

# 1. Rename in dbt
# Edit dbt files...
git add models/
git commit -m "Rename orders to fact_orders"

# 2. Rename in Lightdash (before deploying!)
lightdash rename --type model --from orders --to fact_orders

# 3. Deploy updated dbt models
lightdash deploy --select fact_orders

# 4. Validate
lightdash validate

# 5. Commit Lightdash changes (if using code management)
lightdash download --nested
git add lightdash/
git commit -m "Update Lightdash after model rename"

CI/CD Integration

Automated Refactoring

name: Refactor Models

on:
  workflow_dispatch:
    inputs:
      rename_type:
        description: 'Type (model or field)'
        required: true
      from_name:
        description: 'Current name'
        required: true
      to_name:
        description: 'New name'
        required: true
      model_name:
        description: 'Model name (if field rename)'
        required: false

jobs:
  rename:
    runs-on: ubuntu-latest
    steps:
      - name: Install Lightdash CLI
        run: npm install -g @lightdash/cli

      - name: Rename
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_PROJECT: ${{ secrets.LIGHTDASH_PROJECT }}
          CI: true
        run: |
          if [ "${{ github.event.inputs.rename_type }}" == "field" ]; then
            lightdash rename \
              --type field \
              --model ${{ github.event.inputs.model_name }} \
              --from ${{ github.event.inputs.from_name }} \
              --to ${{ github.event.inputs.to_name }} \
              --assume-yes
          else
            lightdash rename \
              --type model \
              --from ${{ github.event.inputs.from_name }} \
              --to ${{ github.event.inputs.to_name }} \
              --assume-yes
          fi

      - name: Validate
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_PROJECT: ${{ secrets.LIGHTDASH_PROJECT }}
          CI: true
        run: lightdash validate --only charts dashboards

Error Handling

Invalid Name Format

Error: "Invalid name format"

Error: Name must contain only lowercase letters and underscores

Solution:

  • Use only a-z and _
  • Remove spaces, hyphens, uppercase
  • Follow pattern: /^[a-z_]+$/

Model Not Found

Error: "Model not found"

Error: Model "orders" not found in project

Solution:

  • Check model name spelling
  • Verify model exists in dbt
  • Deploy model first if new

Field Not Found

Error: "Field not found"

Error: Field "total" not found in model "orders"

Solution:

  • Check field name spelling
  • Verify field exists in model
  • Deploy updated model

Permission Denied

Error: "ForbiddenError"

ForbiddenError: You don't have permission to modify charts

Solution:

  • Need Developer or Admin role
  • Contact project administrator
  • Check project permissions

Rename Conflicts

Error: "Target name already exists"

Error: Model "fact_orders" already exists

Solution:

  • Choose different target name
  • Or rename existing model first
  • Check for naming conflicts

Permission Requirements

Required Permissions

  • Developer or Admin role on project
  • Write access to charts
  • Write access to dashboards

Without permissions:

  • Cannot rename models/fields
  • Cannot modify charts
  • Cannot update dashboards

Return Values

Exit Code 0: Rename succeeded Exit Code 1: Rename failed

Success Output:

Renaming "orders" to "fact_orders"...

Updated 25 charts
Updated 8 dashboards

Successfully renamed "orders" to "fact_orders"

Dry Run Output:

DRY RUN - No changes committed

Would update 25 charts
Would update 8 dashboards

Use without --dry-run to apply changes

Impact Assessment

Check Impact Before Renaming

# 1. List affected items
lightdash rename --type model --from orders --to fact_orders --list

# 2. Count references
# (Check output count)

# 3. Assess risk
# - High usage = higher risk
# - Low usage = lower risk

# 4. Plan validation
# - Test affected charts
# - Validate dashboards
# - Check with users

High-Impact Renames

For models/fields used in many charts:

# 1. Communicate with team
# (Notify users of upcoming change)

# 2. Do dry run
lightdash rename --type model --from orders --to fact_orders --dry-run

# 3. Schedule during off-hours
# (Minimize disruption)

# 4. Execute rename
lightdash rename --type model --from orders --to fact_orders

# 5. Validate immediately
lightdash validate --only charts dashboards

# 6. Test critical charts
# (Manual testing)

# 7. Monitor for issues
# (Check for errors)

Best Practices

1. Always Dry Run First

# Test before executing
lightdash rename --type model --from orders --to fact_orders --dry-run

2. Use List to Assess Impact

# Check what will be affected
lightdash rename --type model --from orders --to fact_orders --list

3. Validate After Rename

# Ensure nothing broke
lightdash rename --type model --from orders --to fact_orders
lightdash validate --only charts dashboards

4. Coordinate with dbt Changes

# Rename in Lightdash BEFORE deploying dbt changes
lightdash rename --type model --from orders --to fact_orders
lightdash deploy --select fact_orders

5. Test in Preview First

# Test rename in preview environment
export LIGHTDASH_PROJECT="preview-uuid"
lightdash rename --type model --from orders --to fact_orders
lightdash validate --only charts

# If good, apply to production
export LIGHTDASH_PROJECT="prod-uuid"
lightdash rename --type model --from orders --to fact_orders

6. Document Renames

# Keep changelog of renames
echo "$(date): Renamed orders to fact_orders" >> REFACTORING.log

7. Communicate with Team

# Before major renames
# Post in team chat:
"🔄 Renaming 'orders' model to 'fact_orders' at 2pm
- 25 charts will be updated
- 8 dashboards will be updated
- All references will be automatically updated
- Please report any issues after 2pm"

8. Backup Before Large Renames

# Download current state
lightdash download --nested --path ./backup-$(date +%Y%m%d)

# Execute rename
lightdash rename --type model --from orders --to fact_orders

# If issues, can restore from backup

Troubleshooting

Rename Incomplete

Issue: Some references not updated

  • Check for custom SQL references
  • Check for hardcoded strings
  • Manually review affected charts

Chart Errors After Rename

Error: Charts showing errors

  • Run validation: lightdash validate --only charts
  • Check for case sensitivity issues
  • Verify field names in dbt

Dashboard Filters Broken

Error: Dashboard filters not working

  • Check filter field references
  • Verify dimension availability
  • Manually fix filter configurations

Performance Issues

Issue: Rename taking too long

  • Large project with many charts
  • Rename happens server-side
  • Wait for completion or contact support