Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

10.1 KB
Raw Blame

SQLRooms Demo App

An experimental version of the Kepler demo for testing SQLRooms 0.29.0. It runs beside the original examples/demo-app. The website serves the original app at /demo and this app at /demo-next as separate bundles.

Run both apps

Install the root workspace dependencies and initialize the workspace packages with yarn bootstrap as described in the development guide. Then run these commands from the repository root in separate terminals:

yarn start           # original demo: http://localhost:8080
yarn start:sqlrooms  # SQLRooms demo: http://localhost:8083

The launcher installs each example's dependencies if needed. To install or build this app directly:

cd examples/demo-app-sqlrooms
yarn install --immutable
yarn start:local
# Or generate the production bundle:
yarn build

In standalone development, both apps support /demo and sample routes such as /demo/earthquakes. On the website, the SQLRooms preview uses /demo-next and /demo-next/earthquakes. Different local ports keep browser storage separate. Provider credentials use the same repository environment configuration as the original demo. Cloud login and AI requests require credentials; local OAuth testing also requires registering this app's origin with the provider.

What to compare

  • Initial Add Data dialog, file/tileset/URL/storage loading, and sample gallery.
  • Logo/version, data/layer/filter/style panels, and export/storage actions.
  • Map controls: split view, 3D, drawing, annotations, locale, legend, effects, assistant, and zoom.
  • Sidebar collapse/reopen without losing edits, map resizing, and SQL/assistant panel resizing and visibility.

The SQLRooms version retains the existing Kepler Redux store, loaders, saved-map format, and provider integrations. Its application shell uses @kepler.gl/sqlrooms/shell, and src/components/sqlrooms-demo-layout.tsx owns the SQLRooms layout and panel registry. New features can register panels there. It keeps Kepler's colors and font stack and removes the obsolete DuckDB preview callout. Sample fixtures are imported from the original demo to avoid duplicating the datasets; application code and dependency installation are separate.

Use this preview to establish feature parity before replacing the main app.

Website deployment

The root yarn install:web installs both examples and the website, including this example's locked dependencies via yarn install:sqlrooms. The root yarn deploy runs that install step followed by the website's yarn build, which builds both apps and copies this example's --demo-next output into website/dist/demo-next/. To build locally, first run yarn install:web from the repository root, then cd website && yarn build. The website's yarn esbuild only rebuilds the original website bundle; yarn build:demo-next builds and copies the preview without installing dependencies. Netlify continues publishing the same website/dist directory. No dashboard, domain, or new environment variable configuration is required for this addition to an existing deployment.

The website's _redirects routes /demo-next and its child routes to the new entry point before the website catch-all. Assets use /demo-next/ URLs, and sample and cloud-share links stay under /demo-next. This example's regular yarn build and local development retain /demo routes and root asset URLs. To try the deployed paths locally, run yarn start:local --demo-next from this directory. The flag controls both routing and asset paths through a dedicated build identifier; setting DEMO_BASE_PATH in the environment or .env does not change the route. The preview remains unlisted in the marketing site's navigation.

Assistant sessions/settings use kepler-sqlrooms-ai-assistant-state, separate from the original demo. Provider login storage remains shared on the same origin. Existing OAuth callback URLs are retained, including the website's /auth popup handler for Dropbox; no new callback registration is introduced. Live login still depends on the existing provider configuration, and preview origins must already be allowed by the provider to support login.

After building the website, run the deployment browser check from the repository root with node --test website/test/demo-next.browser.cjs. It serves the combined publish directory using its SPA rewrites and checks both entry points, nested sample routes, asset URLs, and assistant storage isolation. It requires Chromium (or PUPPETEER_EXECUTABLE_PATH) and access to public sample data and DuckDB assets.

Component overrides

See Component overrides and possible core migration for the app and adapter override inventory and proposed migration into Kepler core.

SQL panel

Use the map's bottom-left SQL panel button to open the full-width bottom panel. It uses SQLRooms' standard schema tree and SqlCodeMirrorEditor from @sqlrooms/sql-editor and SQLRooms' paginated Arrow result table. SQLRooms owns one DuckDB-Wasm 1.32.0 database shared by map imports, the SQL panel, and the assistant. Apache Arrow is pinned to SQLRooms' 17.0.0 peer. The app's room borrows the connector; closing a panel does not destroy the database. Layout, the SQL panel, and the assistant all use that room and its database slice.

  • Run the selection or full query with ⌘/Ctrl+Enter or Run query.
  • Use Add to Map to load all rows of the last query result from its existing DuckDB table, without re-importing Arrow.
  • Previews transfer at most 1,000 rows. Export CSV downloads the full result.
  • Cancel a running query with the stop button. SQLRooms handles cancellation.
  • Import files through the existing Add Data dialog; the schema tree refreshes automatically.
  • Editor text and results survive closing/reopening the panel; ?sql= links retain the SQL text.

On the website, open /demo-next/earthquakes?sql=SELECT%20*%20FROM%20%22California%20Earthquakes%22%20LIMIT%20100. For standalone development, use /demo/earthquakes?sql=SELECT%20*%20FROM%20%22California%20Earthquakes%22%20LIMIT%20100.

From the repository root, run the query execution and CSV export checks with:

node --test examples/demo-app-sqlrooms/test/*.test.cjs

The SQLRooms demo CI workflow runs these unit tests for PRs targeting master or feat/sqlrooms-integration. Browser checks remain manual.

The query runner keeps a database snapshot so mapping and exporting never rerun preceding SQL writes. Unmapped snapshots are dropped on the next query or app unmount. Mapped snapshots are retained as query_result_* tables for the page's lifetime. Kepler datasets are Arrow snapshots; subsequent SQL edits do not implicitly update an already-loaded map. The assistant's spatial analysis tools still create transformed tbl_* tables when they need their legacy geometry shape. Ordinary AI SQL queries read the existing tables directly.

AI assistant

The demo composes createAiSlice, createAiSettingsSlice, and createCommandSlice into its layout room, following SQLRooms' AI example. src/components/assistant.tsx supplies standard Chat and AiSettingsPanel components, Kepler instructions, skill tools, and chart renderers. Kepler map commands still access the existing Redux store through explicit accessors. Closing the assistant unmounts its UI without destroying the room or interrupting its database. Sessions and provider settings use the demo-owned kepler-sqlrooms-ai-assistant-state storage key, preserving settings migration while keeping the original demo's state separate.

The stock SQLRooms query tool shares five result rows with the model and accepts read-only queries. It no longer materializes every map dataset into tbl_* copies before a query. Table discovery uses the shared SQLRooms catalog. Use the SQL panel or the existing map/data commands for writes and derived datasets. Only model-output formatting is customized: the existing roughly 1,000-character preview cap prevents large geometry/object values from flooding model context. Map, geographic, GeoDa, skill, and chart capabilities remain provided by @openassistant/kepler-assistant.

Assistant integration package

The demo uses the published @openassistant/[email protected] integration API. The /integration, /chat, and /tool-surface entry points expose the map bridge, command catalog, skill factories, and chart renderers without constructing a standalone room. The demo owns persistence, slice composition, command registration, connector binding, and the chat UI.

No Yarn patch or DuckDB import interception is needed. Keep all assistant imports on these headless subpaths: importing the root initializes the standalone room. The package's single-map Redux/analysis bridge remains page-scoped; this is not a multi-room assistant API. Run the browser test below when upgrading the package.

OpenAI models use the native AI SDK Responses provider for chat, skill discovery, and skill subagents, so reasoning models can call tools. The resolver reads the current model, API key, and base URL at request time. It disables server-side response storage; the room retains conversation history and the SDK carries encrypted reasoning between tool steps. Other providers keep their existing resolution. The demo uses AI SDK 6 to match SQLRooms 0.29's model interface. The skill factories accept the same resolver without a dependency patch.

The model tests exercise Responses requests, tool-result and reasoning replay, model/settings changes, and the fallback for other providers with mocked HTTP. Run them alongside the SQL/export tests using the unit-test command above.

The browser integration test exercises the actual WASM engine, shared assistant lifecycle, stock chat and chart rendering, session/settings persistence across reloads, table discovery, bounded previews, full map/export results, spatial metadata, and query cancellation. Skill discovery uses a mocked model response; live provider requests require manual verification with credentials. It needs Chromium (or PUPPETEER_EXECUTABLE_PATH) and network access to the versioned DuckDB CDN assets:

node --test examples/demo-app-sqlrooms/test/duckdb.browser.cjs