Implementation:TobikoData Sqlmesh Api Hooks

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

Overview

Concrete tool for React Query-based API hooks with timeout management provided by the SQLMesh web client.

Description

This module provides custom React hooks for interacting with the SQLMesh backend API using TanStack React Query. It wraps API endpoints with automatic timeout handling, error management, and loading states. The hooks implement a consistent pattern with configurable delays (1, 5, and 10 minute defaults), automatic request cancellation, and integration with the notification system for error reporting.

Key features include:

• useQueryWithTimeout wrapper that adds timeout and error handling to all API queries
• Hooks for fetching metadata (modules, models, files, environments)
• Hooks for lineage queries (model and column lineage)
• Hooks for plan operations (plan run, apply, cancel)
• Hooks for SQL execution (fetchdf, render, evaluate, table diff)
• Mutation hooks for write operations (save files)

Usage

Developers should use these hooks in React components that need to fetch data from or send data to the SQLMesh backend. The hooks automatically manage loading states, error handling, and request cancellation. Each hook returns an extended query result with a cancel function and isTimeout flag.

Code Reference

Source Location

• Repository: TobikoData_Sqlmesh
• File: web/client/src/api/index.ts

Signature

// Main hooks for metadata
function useApiModules(options?: ApiOptions): UseQueryWithTimeoutOptions<Modules[]>
function useApiMeta(options?: ApiOptions): UseQueryWithTimeoutOptions<Meta>
function useApiModels(options?: ApiOptions): UseQueryWithTimeoutOptions<GetModelsApiModelsGet200>
function useApiModel(modelName: string, options?: ApiOptions): UseQueryWithTimeoutOptions<Model>

// File system hooks
function useApiFiles(options?: ApiOptions): UseQueryWithTimeoutOptions<Directory>
function useApiFileByPath(path: string, options?: ApiOptions): UseQueryWithTimeoutOptions<File>

// Lineage hooks
function useApiModelLineage(modelName: string, options?: ApiOptions): UseQueryWithTimeoutOptions<ModelLineageApiLineageModelNameGet200>
function useApiColumnLineage(model: string, column: string, options?: ApiOptions, params?: ColumnLineageApiLineageModelNameColumnNameGetParams): UseQueryWithTimeoutOptions<ColumnLineageApiLineageModelNameColumnNameGet200>

// Environment hooks
function useApiEnvironments(options?: ApiOptions): UseQueryWithTimeoutOptions<Environments>

// Plan operations
function useApiPlanRun(environment: string, inputs?: PlanInputs, options?: ApiOptions): UseQueryWithTimeoutOptions<PlanOverviewStageTracker>
function useApiPlanApply(environment: string, inputs?: PlanInputs, options?: ApiOptions): UseQueryWithTimeoutOptions<PlanApplyStageTracker>
function useApiCancelPlan(options?: ApiOptions): UseQueryWithTimeoutOptions

// SQL execution hooks
function useApiFetchdf(inputs: FetchdfInput, options?: ApiOptions): UseQueryWithTimeoutOptions<unknown>
function useApiRender(inputs: RenderInput, options?: ApiOptions): UseQueryWithTimeoutOptions<Query>
function useApiEvaluate(inputs: EvaluateInput, options?: ApiOptions): UseQueryWithTimeoutOptions<unknown>
function useApiTableDiff(inputs: GetTableDiffApiTableDiffGetParams, options?: ApiOptions): UseQueryWithTimeoutOptions<TableDiff>

// Mutation hooks
function useMutationApiSaveFile(client: QueryClient): UseMutationResult<File, unknown, { path: string; body: BodyWriteFileApiFilesPathPost }, void>

Import

import {
  useApiModels,
  useApiFiles,
  useApiPlanRun,
  useMutationApiSaveFile
} from '~/api'

I/O Contract

Inputs

Name	Type	Required	Description
options	ApiOptions	No	Configuration for delay, trigger name, and timeout error removal
options.delay	number	No	Timeout duration in milliseconds (defaults: 5 min standard, 10 min for long operations)
options.trigger	string	No	String identifier for logging/debugging
options.removeTimeoutErrorAfter	number	No	Auto-remove timeout error after N milliseconds
modelName / path / etc.	string	Varies	Resource identifier for specific queries

Outputs

Name	Type	Description
data	T (generic)	The fetched data when query succeeds
isLoading	boolean	True while query is in progress
isFetching	boolean	True while query is fetching (includes background refetch)
error	ApiExceptionPayload	Error object if query fails
refetch	function	Function to manually trigger query
cancel	function	Function to cancel ongoing request and clear timeout
isTimeout	boolean	True if request exceeded configured timeout

Usage Examples

import { useApiModels, useApiPlanRun, useMutationApiSaveFile } from '~/api'
import { useQueryClient } from '@tanstack/react-query'

function MyComponent() {
  const queryClient = useQueryClient()

  // Fetch models with auto-timeout after 5 minutes
  const {
    data: models,
    isLoading,
    refetch: getModels,
    cancel: cancelGetModels
  } = useApiModels({
    delay: 60000, // 1 minute timeout
    trigger: 'MyComponent.loadModels'
  })

  // Run a plan with 10 minute timeout
  const {
    refetch: runPlan,
    isFetching: isPlanRunning,
    cancel: cancelPlan
  } = useApiPlanRun('dev', {
    planDates: { start: '2024-01-01', end: '2024-01-31' }
  })

  // File save mutation
  const saveFile = useMutationApiSaveFile(queryClient)

  const handleRunPlan = async () => {
    const result = await runPlan()
    if (result.data) {
      console.log('Plan completed:', result.data)
    }
  }

  const handleSaveFile = () => {
    saveFile.mutate({
      path: 'models/my_model.sql',
      body: { content: 'SELECT * FROM table' }
    })
  }

  return (
    <div>
      {isLoading && <p>Loading models...</p>}
      {models && <ModelList models={models} />}
      <button onClick={handleRunPlan}>Run Plan</button>
      {isPlanRunning && <button onClick={cancelPlan}>Cancel</button>}
    </div>
  )
}

Related Pages

• Environment:TobikoData_Sqlmesh_Web_UI_Stack