Implementation:TobikoData Sqlmesh Plan Hooks

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

Overview

Plan_Hooks provides custom React hooks for constructing plan and apply API payloads from user-selected options, dates, and change categorizations.

Description

The Plan_Hooks module exports two primary hooks that transform UI state into API request payloads for SQLMesh plan operations. The usePlanPayload hook constructs payloads for plan preview/run operations, implementing environment-specific logic where production environments exclude date ranges and initial production plans force specific options (include_unmodified, no_gaps). The useApplyPayload hook builds payloads for plan apply operations with similar logic but different option filtering. Both hooks use useMemo for performance optimization and handle change categorization mapping, converting UI categorization objects into the flat structure expected by the API. The hooks implement conditional date range logic based on environment type (prod vs non-prod) and initial environment state.

Usage

Use these hooks in plan workflow components to construct API request payloads. They centralize the complex logic of translating UI state into backend API parameters.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/client/src/library/components/plan/hooks.ts

Signature

export function usePlanPayload(options?: PlanOptions): {
  planDates?: PlanDates
  planOptions: PlanOptions
  categories: BodyInitiateApplyApiCommandsApplyPostCategories
}

export function useApplyPayload(): {
  planDates?: PlanDates
  planOptions: PlanOptions
  categories: BodyInitiateApplyApiCommandsApplyPostCategories
}

Import

import { usePlanPayload, useApplyPayload } from '@library/components/plan/hooks'

I/O Contract

Inputs

Name	Type	Required	Description
options	PlanOptions	No	Optional override options for plan payload

Outputs

Name	Type	Description
planDates	PlanDates	undefined	Date range for plan (omitted for production)
planOptions	PlanOptions	Combined plan configuration options
categories	Object	Change categorization mappings

Usage Examples

import { usePlanPayload, useApplyPayload } from '@library/components/plan/hooks'
import { useApiPlanRun, useApiPlanApply } from '~/api'

function PlanExecutor() {
  const planPayload = usePlanPayload()
  const applyPayload = useApplyPayload()

  const { refetch: runPlan } = useApiPlanRun('dev', planPayload)
  const { refetch: applyPlan } = useApiPlanApply('dev', applyPayload)

  const handleRun = () => {
    console.log('Plan payload:', planPayload)
    runPlan()
  }

  const handleApply = () => {
    console.log('Apply payload:', applyPayload)
    applyPlan()
  }

  return (
    <div>
      <button onClick={handleRun}>Run Plan</button>
      <button onClick={handleApply}>Apply Plan</button>
    </div>
  )
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment