Implementation:Apache Druid ExploreState

Knowledge Sources	Apache Druid
Domains	Visual_Exploration, State_Management
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete immutable state class for managing visual exploration session state with URL hash serialization.

Description

The ExploreState class (353 lines) is an immutable value object that represents the complete state of the Explore view. It provides:

fromJS(js): Deserializes state from a parsed URL hash object
valueOf(): Serializes state to a plain object for URL hash encoding
changeSource(source): Creates a new state with a different datasource
restrictToQuerySource(querySource): Validates state against available columns
addInitTimeFilterIfNeeded(): Adds a default time filter for time-based datasources

The class defines 14 layout options for tile arrangements and provides a LAYOUT_TO_NUM_TILES mapping for determining how many visualization tiles each layout supports.

Usage

Create ExploreState instances via fromJS() when parsing the URL hash. Use immutable modifier methods (change*, restrict*, add*) to create new states. Serialize via valueOf() when updating the URL hash.

Code Reference

Source Location

Repository: Apache Druid
File: web-console/src/views/explore-view/models/explore-state.ts
Lines: L91-L353

Signature

export type ExploreModuleLayout = 'single' | 'two-by-two' | 'two-rows' | 'two-columns' |
  'three-rows' | 'three-columns' | 'top-row-two-tiles' | 'bottom-row-two-tiles' |
  'left-column-two-tiles' | 'right-column-two-tiles' | 'top-row-three-tiles' |
  'bottom-row-three-tiles' | 'left-column-three-tiles' | 'right-column-three-tiles';

export class ExploreState {
  static DEFAULT_STATE: ExploreState;
  static LAYOUTS: ExploreModuleLayout[];
  static LAYOUT_TO_NUM_TILES: Record&lt;ExploreModuleLayout, number&gt;;

  static fromJS(js: any): ExploreState

  public readonly source: string;
  public readonly where?: SqlExpression;
  public readonly moduleStates: Readonly&lt;Record&lt;string, ModuleState&gt;&gt;;
  public readonly layout?: ExploreModuleLayout;

  valueOf(): any
  changeSource(source: string): ExploreState
  restrictToQuerySource(querySource: QuerySource): ExploreState
  addInitTimeFilterIfNeeded(): ExploreState
}

Import

import { ExploreState } from './models/explore-state';

I/O Contract

Inputs

Name	Type	Required	Description
js	any	Yes	Parsed URL hash object (for fromJS)
source	string	Yes	Datasource name or SQL subquery

Outputs

Name	Type	Description
ExploreState	ExploreState	Immutable state object with all exploration parameters
valueOf result	any	Serializable plain object for URL hash encoding

Usage Examples

URL Hash Round-Trip

import { ExploreState } from './models/explore-state';

// Deserialize from URL hash:
const hashParams = parseHashParams(window.location.hash);
const state = ExploreState.fromJS(hashParams);

// Modify state immutably:
const newState = state
  .changeSource('"new_datasource"')
  .addInitTimeFilterIfNeeded();

// Serialize back to URL:
window.location.hash = encodeHashParams(newState.valueOf());

// Layout configuration:
const numTiles = ExploreState.LAYOUT_TO_NUM_TILES['two-by-two']; // 4

Related Pages

Implements Principle

Principle:Apache_Druid_Explore_State_Management

Requires Environment

Uses Heuristic

Heuristic:Apache_Druid_Explore_Compare_Query_Strategy

Page Connections

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

Principle

Implementation

Heuristic

Environment