Principle:TobikoData Sqlmesh Web UI

Knowledge Sources	SQLMesh SQLMesh Docs
Domains	Web_Development, Data_Engineering, Visualization
Last Updated	2026-02-07 00:00 GMT

Overview

The Web UI principle encompasses the browser-based graphical interface for interacting with SQLMesh, providing visual tools for model development, lineage exploration, plan management, environment switching, and data inspection without requiring command-line usage.

Description

SQLMesh provides a rich web-based user interface built with React and TypeScript that enables data engineers to interact with their SQLMesh projects through a browser. The UI consists of a client-side single-page application that communicates with a FastAPI backend via REST endpoints and Server-Sent Events (SSE) for real-time updates.

The architecture follows a state-management-driven design using Zustand stores for global application state, React Query for server state synchronization, and CodeMirror for SQL editing with SQLMesh-specific dialect support. The UI includes several major subsystems:

Editor System: A multi-tab SQL editor with syntax highlighting, auto-completion, model reference decorations, dialect selection, and integrated preview panels for rendered SQL, query results, and lineage visualization. The editor uses CodeMirror extensions custom-built for SQLMesh to provide model-aware highlighting and navigation.

Lineage Visualization: An interactive directed acyclic graph (DAG) viewer built on ReactFlow that renders model dependencies with column-level lineage. Uses Dagre for automatic hierarchical layout computation offloaded to Web Workers to prevent UI blocking. Supports gradient-colored edges, column port connections, and model node expansion.

Plan Workflow: Components for configuring, reviewing, and applying SQLMesh plans including change previews, backfill date selection, stage-by-stage progress tracking, and confirmation dialogs. Integrates with the server-side plan generation and application APIs.

Environment Management: Tools for creating, selecting, comparing, and deleting virtual data environments. Displays pending changes per environment and supports environment-specific plan operations.

File Explorer: A tree-based file browser with drag-and-drop support, multi-selection, keyboard navigation, and file CRUD operations for managing SQLMesh project files directly from the browser.

Component Library: A set of shared UI components including buttons, modals, tables, virtual lists, tooltips, badges, and typography elements used across all subsystems. Some components are implemented as Lit web components wrapped for React consumption.

Usage

The Web UI should be used when data engineers prefer a visual interface for working with SQLMesh projects, particularly for lineage exploration, plan review and approval, and model development with live SQL previews. It is launched via the `sqlmesh ui` command and is especially valuable for teams that need collaborative plan review workflows or prefer graphical DAG exploration over CLI-based inspection.

Theoretical Basis

The Web UI architecture follows several established frontend engineering principles:

State Management Architecture:

1. Global state divided into domain-specific stores (editor, project, plan, graph)
2. Server state synchronized via React Query with automatic caching and invalidation
3. Real-time updates pushed via SSE channels for plan progress and file changes
4. Optimistic updates where appropriate for responsive user experience

Component Architecture:

1. Shared component library in `web/common` consumed by the client application
2. Compound component patterns for complex UI elements (editor, plan workflow)
3. Context-based dependency injection for subsystem state (lineage, file explorer, graph)
4. Factory patterns for dynamic component generation (edge and node factories for ReactFlow)

Performance Optimization:

1. Virtual list rendering for large model catalogs and source lists
2. Web Worker offloading for graph layout computation and SQL parsing
3. Dagre hierarchical layout algorithm for automatic DAG positioning
4. Memoization and selective re-rendering for graph node updates

Data Flow:

1. Unidirectional data flow from stores to components
2. API hooks encapsulate all server communication with error handling
3. Apache Arrow format support for efficient binary data transfer from query results
4. Pyodide-based SQLGlot integration for client-side SQL formatting and validation

Related Pages

Implemented By

• Implementation:TobikoData_Sqlmesh_Api_Hooks
• Implementation:TobikoData_Sqlmesh_Api_Channels
• Implementation:TobikoData_Sqlmesh_Api_Instance
• Implementation:TobikoData_Sqlmesh_App_Context
• Implementation:TobikoData_Sqlmesh_Editor_Context
• Implementation:TobikoData_Sqlmesh_Project_Context
• Implementation:TobikoData_Sqlmesh_Theme_Context
• Implementation:TobikoData_Sqlmesh_UseLocalStorage
• Implementation:TobikoData_Sqlmesh_Client_Utils
• Implementation:TobikoData_Sqlmesh_Additional_Components
• Implementation:TobikoData_Sqlmesh_Lineage_Worker
• Implementation:TobikoData_Sqlmesh_Sqlglot_Worker
• Implementation:TobikoData_Sqlmesh_Routes
• Implementation:TobikoData_Sqlmesh_Editor_Container
• Implementation:TobikoData_Sqlmesh_EditorCode
• Implementation:TobikoData_Sqlmesh_EditorInspector
• Implementation:TobikoData_Sqlmesh_EditorFooter
• Implementation:TobikoData_Sqlmesh_EditorPreview
• Implementation:TobikoData_Sqlmesh_EditorTab
• Implementation:TobikoData_Sqlmesh_EditorTabs
• Implementation:TobikoData_Sqlmesh_SQLMeshDialect
• Implementation:TobikoData_Sqlmesh_SQLMeshModel_Extension
• Implementation:TobikoData_Sqlmesh_Editor_Extensions_Help
• Implementation:TobikoData_Sqlmesh_Editor_Extensions
• Implementation:TobikoData_Sqlmesh_Editor_Hooks
• Implementation:TobikoData_Sqlmesh_EnvironmentChanges
• Implementation:TobikoData_Sqlmesh_EnvironmentChangesPreview
• Implementation:TobikoData_Sqlmesh_EnvironmentDetails
• Implementation:TobikoData_Sqlmesh_SelectEnvironment
• Implementation:TobikoData_Sqlmesh_FileExplorer_Directory
• Implementation:TobikoData_Sqlmesh_FileExplorer_Context
• Implementation:TobikoData_Sqlmesh_FileExplorer_DragLayer
• Implementation:TobikoData_Sqlmesh_ModelColumns
• Implementation:TobikoData_Sqlmesh_ModelLineage
• Implementation:TobikoData_Sqlmesh_Graph_Context
• Implementation:TobikoData_Sqlmesh_Graph_Help
• Implementation:TobikoData_Sqlmesh_ModelLineageDetails
• Implementation:TobikoData_Sqlmesh_ModelLineageSearch
• Implementation:TobikoData_Sqlmesh_ModelNode
• Implementation:TobikoData_Sqlmesh_ModelNodeHeaderHandles
• Implementation:TobikoData_Sqlmesh_PlanApplyStageTracker
• Implementation:TobikoData_Sqlmesh_PlanChangePreview
• Implementation:TobikoData_Sqlmesh_PlanOptions
• Implementation:TobikoData_Sqlmesh_Plan_Context
• Implementation:TobikoData_Sqlmesh_Plan_Component
• Implementation:TobikoData_Sqlmesh_PlanActions
• Implementation:TobikoData_Sqlmesh_Plan_Hooks
• Implementation:TobikoData_Sqlmesh_Banner
• Implementation:TobikoData_Sqlmesh_Button
• Implementation:TobikoData_Sqlmesh_Documentation_Component
• Implementation:TobikoData_Sqlmesh_Input_Component
• Implementation:TobikoData_Sqlmesh_Selector
• Implementation:TobikoData_Sqlmesh_ListboxShow
• Implementation:TobikoData_Sqlmesh_Loading
• Implementation:TobikoData_Sqlmesh_Spinner
• Implementation:TobikoData_Sqlmesh_Modal
• Implementation:TobikoData_Sqlmesh_ModalConfirmation
• Implementation:TobikoData_Sqlmesh_ModuleNavigation
• Implementation:TobikoData_Sqlmesh_ReportErrors
• Implementation:TobikoData_Sqlmesh_SourceList
• Implementation:TobikoData_Sqlmesh_SplitPane
• Implementation:TobikoData_Sqlmesh_Tab
• Implementation:TobikoData_Sqlmesh_Table
• Implementation:TobikoData_Sqlmesh_TableDiff
• Implementation:TobikoData_Sqlmesh_TableDiff_Help
• Implementation:TobikoData_Sqlmesh_Toggle
• Implementation:TobikoData_Sqlmesh_SearchList
• Implementation:TobikoData_Sqlmesh_TasksOverview
• Implementation:TobikoData_Sqlmesh_Root_Page
• Implementation:TobikoData_Sqlmesh_NotificationCenter
• Implementation:TobikoData_Sqlmesh_Model_Environment
• Implementation:TobikoData_Sqlmesh_Tracker_Plan_Apply
• Implementation:TobikoData_Sqlmesh_Tracker_Plan_Overview
• Implementation:TobikoData_Sqlmesh_Model_Artifact
• Implementation:TobikoData_Sqlmesh_Model_Directory
• Implementation:TobikoData_Sqlmesh_Model_File
• Implementation:TobikoData_Sqlmesh_Model_ModuleController
• Implementation:TobikoData_Sqlmesh_Model_PlanAction
• Implementation:TobikoData_Sqlmesh_Model_SqlmeshModel
• Implementation:TobikoData_Sqlmesh_Model_TrackerPlan
• Implementation:TobikoData_Sqlmesh_DataCatalog_Page
• Implementation:TobikoData_Sqlmesh_Editor_Page
• Implementation:TobikoData_Sqlmesh_Errors_Page
• Implementation:TobikoData_Sqlmesh_Models_Page
• Implementation:TobikoData_Sqlmesh_ColumnLevelLineageContext
• Implementation:TobikoData_Sqlmesh_FactoryColumn
• Implementation:TobikoData_Sqlmesh_ColumnLevel_Help
• Implementation:TobikoData_Sqlmesh_UseColumnLevelLineage
• Implementation:TobikoData_Sqlmesh_UseColumns
• Implementation:TobikoData_Sqlmesh_LineageContext
• Implementation:TobikoData_Sqlmesh_LineageLayout
• Implementation:TobikoData_Sqlmesh_EdgeWithGradient
• Implementation:TobikoData_Sqlmesh_FactoryEdgeWithGradient
• Implementation:TobikoData_Sqlmesh_Lineage_Help
• Implementation:TobikoData_Sqlmesh_DagreLayout
• Implementation:TobikoData_Sqlmesh_Layout_Worker_Help
• Implementation:TobikoData_Sqlmesh_NodePort
• Implementation:TobikoData_Sqlmesh_NodePorts
• Implementation:TobikoData_Sqlmesh_Lineage_Utils
• Implementation:TobikoData_Sqlmesh_LineageLayoutBase
• Implementation:TobikoData_Sqlmesh_Story_ModelLineage
• Implementation:TobikoData_Sqlmesh_Story_ModelNode
• Implementation:TobikoData_Sqlmesh_Common_Badge
• Implementation:TobikoData_Sqlmesh_Common_Button
• Implementation:TobikoData_Sqlmesh_CopyButton
• Implementation:TobikoData_Sqlmesh_Common_Input
• Implementation:TobikoData_Sqlmesh_LoadingContainer
• Implementation:TobikoData_Sqlmesh_LoadingIcon
• Implementation:TobikoData_Sqlmesh_MessageContainer
• Implementation:TobikoData_Sqlmesh_Metadata_Component
• Implementation:TobikoData_Sqlmesh_ModelName
• Implementation:TobikoData_Sqlmesh_Common_Tooltip
• Implementation:TobikoData_Sqlmesh_Information
• Implementation:TobikoData_Sqlmesh_FilterableList
• Implementation:TobikoData_Sqlmesh_VirtualList
• Implementation:TobikoData_Sqlmesh_Common_Types
• Implementation:TobikoData_Sqlmesh_Common_Utils
• Implementation:TobikoData_Sqlmesh_Tbk_Components