Implementation:TobikoData Sqlmesh Tracker Plan Overview

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_UI, Data_Model, Plan_Management, State_Tracking
Last Updated	2026-02-07 20:00 GMT

Overview

A TypeScript class that tracks SQLMesh plan generation and categorizes model changes for review and application.

Description

ModelPlanOverviewTracker extends the base plan tracker to monitor plan generation progress and organize model changes into categorized lists: added, removed, direct modifications, indirect modifications, metadata-only changes, and backfills. It provides computed properties to determine update types (virtual update, metadata update, backfill update, or mixed) and exposes stage information for validation, changes, and backfills.

The tracker processes raw plan data from the backend into ModelSQLMeshChangeDisplay instances for UI consumption and provides boolean flags for update type detection (isVirtualUpdate, isMetadataUpdate, isBackfillUpdate, isLatest). It also respects plan options like skip_tests and skip_backfill to adjust UI behavior.

Usage

Use this tracker in the Plan page to display plan overview information before applying changes. It's updated via WebSocket messages from the backend plan-overview channel and provides the categorized change data needed for plan review interfaces.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/client/src/models/tracker-plan-overview.ts

Signature

export class ModelPlanOverviewTracker
  extends ModelPlanTracker<PlanOverviewTracker>
  implements InitialModelPlanOverviewTracker
{
  constructor(model?: ModelPlanOverviewTracker)

  // Stage accessors
  get stageValidation(): Optional<PlanStageValidation>
  get stageChanges(): Optional<PlanStageChanges>
  get stageBackfills(): Optional<PlanStageBackfills>

  // Raw stage data
  get validation(): Optional<PlanStageValidation>
  get changes(): Optional<PlanStageChanges>

  // Change detection
  get hasChanges(): Optional<boolean>
  get hasBackfills(): Optional<boolean>
  get hasUpdates(): boolean

  // Categorized changes
  get added(): ModelSQLMeshChangeDisplay[]
  get removed(): ModelSQLMeshChangeDisplay[]
  get direct(): ModelSQLMeshChangeDisplay[]
  get indirect(): ModelSQLMeshChangeDisplay[]
  get metadata(): ModelSQLMeshChangeDisplay[]
  get backfills(): ModelSQLMeshChangeDisplay[]

  // Update type detection
  get isVirtualUpdate(): boolean
  get isMetadataUpdate(): boolean
  get isBackfillUpdate(): boolean
  get isChangesAndBackfillUpdate(): boolean
  get isLatest(): boolean

  // Plan options
  get skipTests(): boolean
  get skipBackfill(): boolean

  // State management
  update(tracker: PlanOverviewTracker): void
  clone(): ModelPlanOverviewTracker
}

export interface PlanOverviewTracker extends PlanTracker {
  validation?: PlanStageValidation
  changes?: PlanStageChanges
  backfills?: PlanStageBackfills
}

Import

import { ModelPlanOverviewTracker } from '@models/tracker-plan-overview'

I/O Contract

Constructor Inputs

Name	Type	Required	Description
model	ModelPlanOverviewTracker	No	Existing tracker instance to clone

Key Properties

Name	Type	Description
stageValidation	PlanStageValidation	Validation stage metadata
stageChanges	PlanStageChanges	Changes stage with added/removed/modified models
stageBackfills	PlanStageBackfills	Backfills stage with models requiring data processing
hasChanges	undefined	True if any model changes exist
hasBackfills	undefined	True if any backfills are required
hasUpdates	boolean	True if changes or backfills exist
added	ModelSQLMeshChangeDisplay[]	Newly added models
removed	ModelSQLMeshChangeDisplay[]	Deleted models
direct	ModelSQLMeshChangeDisplay[]	Models with direct modifications
indirect	ModelSQLMeshChangeDisplay[]	Models with downstream dependency changes
metadata	ModelSQLMeshChangeDisplay[]	Models with metadata-only changes
backfills	ModelSQLMeshChangeDisplay[]	Models requiring data backfill
isVirtualUpdate	boolean	Only changes, no backfills (or backfills skipped)
isMetadataUpdate	boolean	Only metadata changes, no backfills
isBackfillUpdate	boolean	Only backfills, no model changes
isLatest	boolean	No changes or backfills (environment is up-to-date)
skipTests	boolean	Plan option to skip test execution
skipBackfill	boolean	Plan option to skip backfill execution

Methods

Name	Parameters	Description
update	tracker	Update tracker with new data from WebSocket
clone	-	Create deep copy of tracker

Usage Examples

// Initialize tracker in plan store
const planOverview = new ModelPlanOverviewTracker()

// Update from WebSocket channel
channel?.('plan-overview', (data: PlanOverviewTracker) => {
  planOverview.update(data)
  setPlanOverview(planOverview)
})

// Display plan changes by category
<div>
  <h3>Plan Changes</h3>

  {planOverview.added.length > 0 && (
    <ChangeSection title="Added Models" color="success">
      {planOverview.added.map(model => (
        <ModelItem key={model.name} model={model} />
      ))}
    </ChangeSection>
  )}

  {planOverview.removed.length > 0 && (
    <ChangeSection title="Removed Models" color="danger">
      {planOverview.removed.map(model => (
        <ModelItem key={model.name} model={model} />
      ))}
    </ChangeSection>
  )}

  {planOverview.direct.length > 0 && (
    <ChangeSection title="Direct Changes" color="primary">
      {planOverview.direct.map(model => (
        <ModelItem key={model.name} model={model} />
      ))}
    </ChangeSection>
  )}

  {planOverview.indirect.length > 0 && (
    <ChangeSection title="Indirect Changes" color="warning">
      {planOverview.indirect.map(model => (
        <ModelItem key={model.name} model={model} />
      ))}
    </ChangeSection>
  )}
</div>

// Conditional rendering based on update type
{planOverview.isVirtualUpdate && (
  <Alert type="info">
    This is a virtual update. No data backfill required.
  </Alert>
)}

{planOverview.isMetadataUpdate && (
  <Alert type="info">
    Only metadata changes. No model execution needed.
  </Alert>
)}

{planOverview.isBackfillUpdate && (
  <Alert type="warning">
    Data backfill required for {planOverview.backfills.length} models.
  </Alert>
)}

{planOverview.isLatest && (
  <Alert type="success">
    Environment is up to date. No changes to apply.
  </Alert>
)}

// Check plan options
if (planOverview.skipTests) {
  console.log('Tests will be skipped during apply')
}

if (planOverview.skipBackfill) {
  console.log('Backfills will be skipped (forward-only apply)')
}

// Display stage information
{planOverview.stageValidation && (
  <Stage
    name="Validation"
    status={planOverview.stageValidation.meta?.status}
    done={planOverview.stageValidation.meta?.done}
  />
)}

// Clone for comparison
const previousPlan = planOverview.clone()

// Check for updates
if (planOverview.hasUpdates) {
  console.log('Plan has changes or backfills')
} else {
  console.log('No updates required')
}

Update Type Decision Tree

isLatest: `isFinished && hasChanges === undefined && (hasBackfills === undefined || skipBackfill)`
isVirtualUpdate: `hasChanges && !hasBackfills || (hasChanges && skipBackfill)`
isMetadataUpdate: `metadata.length > 0 && !hasBackfills`
isBackfillUpdate: `!hasChanges && hasBackfills && !skipBackfill`
isChangesAndBackfillUpdate: `hasChanges && hasBackfills && !skipBackfill`

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment