@sqlrooms/pivot

Experimental: This package's API and behavior may change between releases.

Slice-driven pivot table UI for SQLRooms, inspired by react-pivottable and backed by DuckDB SQL plus Vega-Lite charts.

Setup

Compose createPivotSlice() with a room store that includes database state, persist PivotSliceConfig, ensure a pivot instance, then render it by ID:

import {PivotSliceConfig, PivotView, createPivotSlice} from '@sqlrooms/pivot';
import {
  RoomStateProvider,
  createRoomShellSlice,
  createRoomStore,
  persistSliceConfigs,
} from '@sqlrooms/room-shell';

const {roomStore} = createRoomStore(
  persistSliceConfigs(
    {
      name: 'pivot-workspace',
      sliceConfigSchemas: {
        pivot: PivotSliceConfig,
      },
    },
    (set, get, store) => ({
      ...createRoomShellSlice({})(set, get, store),
      ...createPivotSlice()(set, get, store),
    }),
  ),
);

roomStore.getState().pivot.ensurePivot('sales-pivot', {
  title: 'Sales by region',
  source: {kind: 'table', tableName: 'sales'},
});

<RoomStateProvider roomStore={roomStore}>
  <PivotView pivotId="sales-pivot" />
</RoomStateProvider>

The table must be available in the room database catalog before PivotView can render. See the Pivot example for artifact lifecycle and layout integration.

Selection model

• createPivotSlice manages pivot definitions and runtime state, but not host-level selection.
• Host apps should decide which pivot is visible, for example with layout tabs or an artifacts/workspace registry.
• PivotView now requires an explicit pivotId prop.

Stateful block adapter

createPivotBlockDefinition exposes pivot tables as stateful block implementations. Host apps can use this definition directly in block hosts or wrap it as a top-level artifact shell with @sqlrooms/artifacts.

import {createArtifactTypeFromStatefulBlock} from '@sqlrooms/artifacts';
import {createPivotBlockDefinition} from '@sqlrooms/pivot';

const pivotBlockDefinition = createPivotBlockDefinition();

export const pivotArtifactType =
  createArtifactTypeFromStatefulBlock(pivotBlockDefinition);

The adapter preserves pivot state in pivot.config.pivots and delegates creation, rename, and delete behavior to createPivotSlice.

See Blocks and Block Documents for embedding pivots in rich documents and choosing an ownership mode.

Type Aliases

• PivotBlockRenderProps
• CreatePivotBlockDefinitionOptions
• PivotBlockProps
• PivotAggregatorDefinition
• PivotCellData
• PivotCell
• PivotRendererName
• PivotRendererName
• PivotSortOrder
• PivotSortOrder
• PivotFilterMap
• PivotValueFilter
• PivotConfig
• PivotConfig
• PivotSource
• PivotSource
• PivotRelationViews
• PivotRelationViews
• PivotRunState
• PivotRunState
• PivotStatus
• PivotStatus
• PivotSliceItem
• PivotSliceItem
• PivotSliceConfig
• PivotDropZone
• PivotField
• PivotQuerySource
• PivotSliceState
• PivotInstanceSnapshot
• PivotInstanceState
• PivotInstanceStore
• PivotOutputCell

Variables

• PivotCellContent
• PivotEditor
• PivotResults
• PivotView
• PIVOT_AGGREGATORS
• DEFAULT_PIVOT_AGGREGATOR
• pivotCellRegistryEntry
• PivotCellData
• PivotCell
• PivotCellSchema
• PIVOT_RENDERER_NAMES
• PivotFilterMapSchema
• PivotValueFilterSchema
• PivotSliceConfig

Functions

• PivotBlock
• createPivotBlockDefinition
• createDefaultPivotConfig
• normalizePivotConfig
• setAttributeFilterValuesInConfig
• addAttributeFilterValuesInConfig
• removeAttributeFilterValuesInConfig
• clearAttributeFilterInConfig
• createPivotCoreStore
• createPivotSlice
• getPivotAggregator
• getAggregatorLabel
• getDefaultValuesForAggregator
• formatAggregatorValue
• isPivotCell
• createPivotRelationViews
• createOrReplacePivotRelations
• dropPivotRelations
• createPivotQuerySource
• createPivotQuerySourceFromTable
• buildCellsQuery
• buildRowTotalsQuery
• buildColTotalsQuery
• buildGrandTotalQuery
• buildDistinctValuesQuery
• buildPivotExportQuery
• buildRendererTitle

References

PivotConfigSchema

Renames and re-exports PivotConfig

---

PivotRelationViewsSchema

Renames and re-exports PivotRelationViews

---

PivotRunStateSchema

Renames and re-exports PivotRunState

---

PivotSourceSchema

Renames and re-exports PivotSource

---

PivotStatusSchema

Renames and re-exports PivotStatus