Query Execution
Analytics query workflow from catalog selection through metadata refresh to query execution and result handling.
Overview
This flow documents the analytics query workflow from initial catalog selection through query execution. It represents the core data analysis capability of the ironstar platform.
Catalog selection
Users select a DuckLake catalog from the available catalogs list. Catalog selection establishes the context for all subsequent query operations.
When a catalog is selected, the CatalogService emits a CatalogSelected event and triggers metadata refresh.
Metadata refresh
Catalog metadata refresh populates the dataset browser with available tables, schemas, and column information. This operation queries the DuckLake catalog’s information schema and caches results for the dataset browser UI.
Metadata is refreshed on catalog selection and may be manually triggered if the user expects schema changes.
Query execution lifecycle
Query execution follows a three-outcome pattern common in long-running operations.
Started indicates the query has been submitted for execution. The QuerySessionStarted event captures the SQL, target dataset, and initiating user.
Completed indicates successful query execution. The QuerySessionCompleted event includes result metadata (row count, execution time) but not result data. Results are streamed to the client via SSE as they become available.
Failed indicates query execution encountered an error. The QuerySessionFailed event captures the error type and message for display and debugging.
Cancelled indicates the user requested query termination. The QuerySessionCancelled event records the cancellation for audit purposes.
DuckDB execution
Queries execute against DuckDB with DuckLake catalog extensions. DuckDB’s columnar processing provides efficient analytical query execution.
Long-running queries may be cancelled via the CancelQuery command. Query timeout limits prevent runaway queries from exhausting resources.
Result streaming
Query results are streamed to the client as datastar SSE events. Large result sets are paginated to avoid memory exhaustion. The client UI updates incrementally as results arrive.