Principle:Apache Druid Explore State Management
| Knowledge Sources | |
|---|---|
| Domains | Visual_Exploration, State_Management |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
An immutable state management principle that serializes the complete exploration context to URL hash for bookmarkable, shareable visual data exploration sessions.
Description
Explore State Management maintains the complete state of a visual exploration session as an immutable ExploreState object that is bidirectionally synced with the browser URL hash. This enables:
- Bookmarkability: Any exploration state can be saved as a URL
- Shareability: URLs can be shared with colleagues who see the exact same view
- Browser history: Back/forward navigation works naturally with exploration steps
- Multi-tile layouts: Up to 14 different tile arrangements (single, two-by-two, three-rows, etc.) with independent module configurations per tile
The state includes the datasource, WHERE filters, module configurations (type, parameters), layout arrangement, timezone, and helper columns.
Usage
Use this principle throughout the visual exploration workflow. Every user interaction (filter change, module switch, parameter update) creates a new immutable ExploreState that is serialized to the URL hash.
Theoretical Basis
Explore state management follows an immutable state with URL serialization pattern:
ExploreState = {
source: string, // Datasource name or SQL
where: SqlExpression, // Global filter
moduleStates: Record<string, ModuleState>, // Per-tile module configs
layout: ExploreModuleLayout, // Tile arrangement
timezone?: Timezone, // Display timezone
helpers: ExpressionMeta[], // Helper columns
}
Serialization:
ExploreState → valueOf() → JSON → URL hash
URL hash → JSON → fromJS() → ExploreState
Layouts: 'single' | 'two-by-two' | 'two-rows' | 'two-columns' |
'three-rows' | 'three-columns' | ... (14 total)