# @kepler.gl/sqlrooms
Kepler.gl integration for SQLRooms.
Use this package when you want a **map-first analytics experience** in a SQLRooms app, backed by DuckDB tables and SQL.
## What this package provides
- `createKeplerSlice()` to add Kepler state/actions to your Room store
- `KeplerMapContainer` and `KeplerPlotContainer` for rendering maps/overlays
- `KeplerSidePanels` for layer/filter/interaction UI
- utilities for map config persistence, dataset synchronization, and migration
from legacy Kepler-owned tabs to artifact-backed tabs
## Selection model
- `createKeplerSlice()` manages Kepler map documents and runtime state keyed by
map id, but it does not own host-level map selection.
- Render maps with explicit ids, for example ``.
- Use `@sqlrooms/artifacts` when an app needs multiple user-managed map tabs;
artifact state should own the selected map artifact.
## Installation
```bash
npm install @kepler.gl/sqlrooms @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui
```
## Quick start
```tsx
import {useEffect} from 'react';
import {createKeplerSlice, KeplerMapContainer, KeplerSliceState} from '@kepler.gl/sqlrooms';
import {
createRoomShellSlice,
createRoomStore,
RoomShell,
RoomShellSliceState
} from '@sqlrooms/room-shell';
type RoomState = RoomShellSliceState & KeplerSliceState;
export const {roomStore, useRoomStore} = createRoomStore((set, get, store) => ({
...createRoomShellSlice({
config: {
dataSources: [
{
type: 'url',
tableName: 'earthquakes',
url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet'
}
]
}
})(set, get, store),
...createKeplerSlice()(set, get, store)
}));
function MapPanel() {
const mapId = useRoomStore(state => state.kepler.config.maps[0]?.id);
const addTableToMap = useRoomStore(state => state.kepler.addTableToMap);
const isTableReady = useRoomStore(state => Boolean(state.db.findTable('earthquakes')));
useEffect(() => {
if (!isTableReady || !mapId) return;
void addTableToMap({
mapId,
tableName: 'earthquakes',
options: {
autoCreateLayers: true,
centerMap: true
}
});
}, [isTableReady, mapId, addTableToMap]);
if (!mapId) return null;
return ;
}
export function App() {
return (
);
}
```
## Adding tables to maps
Use `state.kepler.addTableToMap()` to load a DuckDB table into a Kepler map. The
preferred API is an object parameter:
```ts
await state.kepler.addTableToMap({
mapId,
tableName: 'earthquakes',
options: {
autoCreateLayers: true,
centerMap: true
}
});
```
`tableName` is the SQL table reference to load. It can also be a saved Kepler
dataset id when the configured table-selection policy can resolve that id back
to a DuckDB table.
For normal add-table flows, omit `datasetId`. SQLRooms derives the persisted
Kepler dataset id from the table-selection policy:
```ts
await state.kepler.addTableToMap({
mapId,
tableName: 'main.places'
});
```
Only pass `datasetId` when you need to load a table under an existing Kepler
`dataId`, such as when restoring a saved map config:
```ts
await state.kepler.addTableToMap({
mapId,
tableName: savedDataId,
options: {
autoCreateLayers: false,
centerMap: false
},
datasetId: savedDataId
});
```
The older positional signature is still accepted for compatibility, but new code
should use the object form so the table reference, Kepler options, config, and
dataset-id override remain clear at the call site.
An optional `signal: AbortSignal` lets a caller discard a load's results if it
is cancelled before they are applied. The promise resolves without adding data;
the underlying database query is not cancelled. Overrides of `addTableToMap`
should forward or honor this signal. The positional form accepts it in its final
load-options argument.
## Common customization
### Restoring saved maps
Use `kepler.setConfig(savedConfig)` to replay configuration received after room
initialization, then `await kepler.waitForConfigRestore()` to wait for the
restore operation. Initial configuration and later restores both load datasets
referenced by pending layers, filters, and tooltips for every registered map;
mounting a map component is not required.
A newer restore cancels results from earlier dataset-sync requests. Explicit
`addTableToMap` calls remain independent of restores unless the caller supplies
a cancellation signal; restoring another map does not discard a requested table.
If a referenced table is unavailable or fails to load, the map's saved config is
preserved. Deferred Kepler actions cannot replace it with a partially restored
config. Refresh the available tables and call `await kepler.syncKeplerDatasets()`
to retry. Other, fully restored maps continue to autosave normally, including
intentional deletion of all their layers.
`waitForConfigRestore()` does not guarantee that unavailable datasets have loaded.
Persistence protection is based on each map's pending config, so it remains in
effect after that promise resolves. Edits to an incomplete map do not replace
its saved config until its pending config is resolved.
Use `kepler.isMapConfigPending(mapId)` to observe that per-map condition without
inspecting Kepler's internal merge fields. It reads current state and returns a
boolean, so it can be used directly in a Zustand selector inside a React component:
```ts
import {useStoreWithKepler} from '@kepler.gl/sqlrooms';
const configPending = useStoreWithKepler(state => state.kepler.isMapConfigPending(mapId));
// Show a warning that changes to this map are not being saved while pending.
```
The result stays `true` if required data remains unavailable after
`waitForConfigRestore()` resolves, and becomes `false` once the pending config
and dataset merges are resolved. Other maps are checked independently. Unknown,
unregistered, and deleted maps return `false`; that does not mean they are ready
to render. This status does not include the slice's temporary persistence pause
or guarantee completion of all async work, and it does not itself disable editing.
`duplicateMap` copies a pending map's last preserved saved config, including
unresolved layers and settings. It does not wait for missing datasets. If no
saved config is available, it returns `success: false` with code
`source-map-config-pending` without creating a copy. Fully restored maps are
duplicated from their current runtime state, including unsaved edits.
Hosts that override dataset synchronization can reuse the same discovery and
persistence checks from the public package:
```ts
import {
getReferencedKeplerDatasetIds,
hasPendingKeplerConfig
} from '@kepler.gl/sqlrooms';
const map = roomStore.getState().kepler.map[mapId];
if (map) {
const referencedIds = getReferencedKeplerDatasetIds(map.visState);
const missingIds = [...referencedIds].filter(id => !map.visState.datasets[id]);
const configPending = hasPendingKeplerConfig(map.visState);
// Use missingIds in custom loading logic and configPending in host UI.
}
```
Dataset discovery includes live and pending layers/filters and pending tooltip
references. Split-map state references layer ids rather than dataset ids; its
pending state is included in `hasPendingKeplerConfig`. That boolean reports
pending config and dataset merges, not the slice's temporary persistence pause
or completion of all async work. The helpers do not expose the base sync's
restore cancellation signal; custom sync implementations still own cancellation.
`getReferencedKeplerDatasetIds` returns a new set. With Zustand, select the raw
`visState` and derive that set outside the selector. The boolean helper can be
used directly in a selector to observe whether a map has pending config.
### Appearance
Pass options to `createKeplerSlice()`:
```ts
import {createKeplerTheme, type KeplerThemeOverrides} from '@kepler.gl/sqlrooms';
createKeplerSlice({
basicKeplerProps: {
mapboxApiAccessToken: import.meta.env.VITE_MAPBOX_TOKEN
},
keplerTheme: createKeplerTheme({
modalOverLayZ: 40
} satisfies KeplerThemeOverrides),
modalPortalTarget: 'body',
actionLogging: false
});
```
Notes:
- `basicKeplerProps` is for base Kepler registration/component props.
- `keplerTheme` (optional) sets the theme passed to Kepler `ThemeProvider`.
- `modalPortalTarget` controls modal portal placement: `'container'` (default)
or `'body'`.
### Table selection and dataset ids
`tableSelection` controls which DuckDB tables Kepler exposes and how those
tables are represented in persisted Kepler layer and filter config.
```ts
createKeplerSlice({
tableSelection: {
defaultDbSchema: {
database: 'project',
schema: 'main'
},
includeTable: table => table.table.database === 'project'
}
});
```
By default, tables in `defaultDbSchema` use bare dataset ids such as `places`.
Tables outside that database/schema use qualified SQL table references. This
keeps common main-schema project tables readable while preserving enough
identity for tables from other schemas.
Use `includeTable` to hide tables from Kepler's Add Layer UI and to skip matching
saved dataset ids during dataset synchronization. Host apps commonly use this to
hide attached databases that will not be available when a project is reopened.
If the default dataset-id policy is not right for your app, provide both
`getDatasetIdForTable` and `findTableForDatasetId` so new layers and restored
layers agree on the same identity scheme:
```ts
createKeplerSlice({
tableSelection: {
getDatasetIdForTable: table => `${table.table.schema}:${table.table.table}`,
findTableForDatasetId: (tables, datasetId) => {
const [schema, tableName] = datasetId.split(':');
return tables.find(table => table.table.schema === schema && table.table.table === tableName);
},
getTableLabel: table => [table.table.schema, table.table.table].filter(Boolean).join('.')
}
});
```
`getTableLabel` only affects display labels in Kepler table selectors. It does
not change persisted dataset ids.
## Related packages
- `@sqlrooms/artifacts` for artifact-backed map tabs
- `@kepler.gl/sqlrooms/config` is a lightweight entry point in this package for persisted config schemas and migrations
- `@sqlrooms/room-shell` for Room store composition and UI shell
- `@sqlrooms/duckdb` for DuckDB-backed table loading/querying
## Examples
- Experimental SQLRooms demo: [examples/demo-app-sqlrooms](../../examples/demo-app-sqlrooms)
- Original demo and deployed `/demo` application: [examples/demo-app](../../examples/demo-app)
## Migration and package boundaries
This package incorporates the implementation of `@sqlrooms/kepler` and
`@sqlrooms/kepler-config` from SQLRooms commit
`26d8e78e086cebdfc4eb6b4047c9035c5704a068` under its MIT license. The original
license is included in `LICENSE`.
It also includes the saved-map hydration and per-map pending-status changes from
SQLRooms [#920](https://github.com/sqlrooms/sqlrooms/pull/920)
(`a986e5e0a2745973254a335b605907d179251cb5`) and
[#922](https://github.com/sqlrooms/sqlrooms/pull/922)
(`104011c4b174b93fc7c0d2c731b28bc9786c428f`).
Replace runtime imports from `@sqlrooms/kepler` with `@kepler.gl/sqlrooms`.
Replace schema-only imports from `@sqlrooms/kepler-config` with:
```ts
import {
KeplerMapSchema,
KeplerSliceConfig,
migrateKeplerTabsToArtifacts
} from '@kepler.gl/sqlrooms/config';
```
The `/config` entry point does not import React, Kepler rendering, or the
SQLRooms runtime. The same schemas remain re-exported from the main entry point.
The serialized map envelope and legacy tab migration retain their original
format; moving the package does not require rewriting saved maps.
The adapter depends on Kepler and SQLRooms. Kepler's foundational packages must
not depend on this adapter. SQLRooms packages are pinned to the tested release
`0.29.0`; Kepler packages follow this repository's version. Keep React,
React Redux, React Intl, styled-components, and the deck.gl/luma.gl stack shared
within the host application. SQLRooms room-store, room-shell, and UI contexts must
also resolve to one copy (see the SQLRooms demo esbuild aliases).
Do not force all third-party versions of Immer to
one version; older Redux Toolkit dependencies require their own supported copy.
Use the SQLRooms connector as the application's database owner. Do not also
initialize a separate Kepler DuckDB adapter for the same project. This adapter
loads Arrow results into Kepler datasets; it does not promise SQL filter
pushdown or automatic refresh of datasets already loaded in a map.
Factory recipes and Kepler application configuration currently have global
scope. Configure them before rendering. Host storage, project save/reopen, and
locale policy are separate from the config schemas. The SQLRooms demo retains its
existing implementations of these features while migrating its shell.
The SQLRooms repository's old packages are intentionally not removed by this
Kepler PR. After this package is published, a coordinated SQLRooms change can
update consumers and deprecate or re-export the old package names.
## Development
From the repository root:
```sh
yarn install --immutable
yarn workspaces foreach -At run stab
yarn workspace @kepler.gl/sqlrooms build
yarn workspace @kepler.gl/sqlrooms test
yarn start:sqlrooms
```
`build` produces CommonJS and ESM output. Run `build:types` after building the
workspace dependencies and their declarations, as in the repository release workflow.
`test` includes config entry-point checks and adapter/task runtime regressions.
The upstream hydration regressions run with the repository Jest suite:
```sh
yarn jest --runInBand --runTestsByPath src/sqlrooms/test/KeplerSlice.hydration.spec.ts
```
The SQLRooms demo uses local Kepler sources and published SQLRooms packages, so no
sibling SQLRooms checkout is required. The original demo and website remain unchanged for comparison.
## Experimental application shell
`@kepler.gl/sqlrooms/shell` exports `KeplerAppShell` and `SqlroomsSidebarFactory`.
Pair the shell with the original injected Kepler application and `sidePanelWidth={0}`.
The shell reserves sidebar space; the recipe portals the original sidebar content
into it, preserving provider, localization, Redux, and drag-and-drop contexts.
The existing logo/version, data and layer panels, and export/storage menus remain
Kepler components. The SQLRooms demo uses SQLRooms `LayoutRenderer` and a room layout
slice for map, SQL, and assistant panels, with a ChordShell-style sidebar toggle.
This migrates application composition first. The SQLRooms demo keeps its existing
Redux map store, data loading, saved-map format, URLs, cloud providers, and query
integration. It does not convert all maps to `KeplerSlice` or to DuckDB tables.
Applications designed around SQLRooms-owned maps can still compose `KeplerSlice`
and the smaller map/panel components exported from the package root.