Skip to main content
Version: dev

Dashboard Workspace Design

Dashboard turns a data-analysis request into a saved, editable and publishable workspace. This document describes its architecture, data contract, workflows and deployment requirements. It covers the workspace under /dashboards; the existing Chat Dashboard guide describes the older chat application.

The design separates Schema (what to query and display) from Snapshot (the result of an execution). An agent proposes a plan or a change; the server authorizes, validates, executes and persists it. The browser provides review and interaction, but does not authorize database access.

Architecture​

ComponentResponsibilityMain implementation
Agent and toolsExplore data, plan without SQL, obtain confirmation and propose changestools/dashboard.py, planner.py, confirmation.py
ContractValidate structure, cross-field references and version compatibilityschemas.py, schema/dashboard.schema.json, web/types/dashboard.ts
QueriesValidate SQL ASTs, table/column allowlists and parameters; enforce execution limitssql_security.py, query_executor.py, lineage.py
AssetsSave drafts, record revisions, detect conflicts, refresh and publishservice.py, models.py, api.py
Access and sharingResolve identity, check source permissions and manage public grantsidentity.py, access.py, publication.py, live_share.py, share_vault.py
UIEdit components, review AI changes, render results and publishDashboardEditor.tsx, DashboardRenderer.tsx, DashboardPublishDialog.tsx

Backend filenames are relative to the Dashboard backend; the tools directory is its sibling. UI filenames are relative to the Dashboard components.

Data contract​

The Pydantic model and server-side cross-field checks define the accepted contract. The checked-in JSON Schema is exposed by GET /api/v1/dashboards/schema for client validation; TypeScript describes the browser types. Passing client validation does not bypass server validation.

Schema fieldMeaning
schema_versionVersions 1.0–1.4; later versions add federation, metric context, publication presentation and theme capabilities.
dashboardIdentity, title, description, source, state, theme and refresh policy.
metric_contextGrain, time coverage, freshness, provenance and metric definitions.
filtersFilter type, field, options, defaults and query-parameter bindings.
widgetsComponent queries, output fields, visual encodings and public-filter aggregation.
layoutsGrid position, size and mobile presentation.
metadataConversation, generation, template and compatibility information.

The five base widget types are kpi, line, bar, pie and table; visualization settings express additional presentations. Filters support dates, single/multiple selections, text and numeric ranges. Their actual effect depends on query parameters and publication bindings. See the Schema definition for field-level rules.

Creation and AI changes​

  1. Select an authorized data source or attach files. The agent explores tables, fields, samples and time columns.
  2. Review a plan describing metrics, dimensions, filters and widgets without SQL, then confirm it.
  3. Generate the Schema and queries. The server checks permissions, structure, SQL and actual query results before accepting the result.
  4. Open the draft, inspect values and queries, adjust titles/layouts/filters, and save. Planning, query-preview and saved-asset events are separate states.
  5. To change an existing dashboard, describe the requested edit or add an AI annotation. The assistant reads the current object and returns a proposal for review before application. Explanation and anomaly analysis do not silently edit the draft.

A proposal that changes related widgets and filters must keep references, parameters and public aggregation consistent. Applying a proposal is not the same as publishing it.

Data templates offer preset, manual-mapping and AI-adaptation paths. For a built-in source with the default requirements, adaptation can reuse verified preset queries without calling a model; the resulting preview uses the preset creation path. Custom requirements retain model adaptation and validation. A successful preset preview is therefore not evidence of model-generation success.

Saving, revisions and publication​

Saving carries expected_revision; a stale revision returns a conflict instead of silently overwriting changes. Publishing also performs a conditional database update against the expected revision and checks the affected row count. This avoids relying on a row lock that SQLite does not provide. If a save commits after another session publishes the previously read revision, the save explicitly writes draft; the older publication remains attached to its own revision.

ObjectWhat changesReader behavior
DraftExplicit saves create revisionsEditing does not automatically replace published content.
Fixed historical publicationSchema and data are frozen for that publicationFilters recompute only over materialized dimensions; later source changes do not alter it.
Latest publication aliasFollows a later explicit publicationIts target can change; it is distinct from a fixed historical URL.
Live shareRe-materializes data using the published definitionExpiry, revocation and source authorization apply; polling does not guarantee real-time updates.

Publication validates access, Schema, queries and filter bindings. Public readers can view and use permitted filters, but cannot submit arbitrary SQL, replace the source or modify the draft. Project ZIP export contains Schema, Plan and SQL for inspection; it is not a standalone offline application.

Identity, authorization and execution​

Dashboard uses the upstream request identity, preferring a stable user ID rather than a display nickname. Object roles are viewer, editor and owner; having edit access to a dashboard does not itself grant access to its data sources. Source checks cover the primary source and all sources referenced by federated queries before connectors read metadata, including static validation.

SQL is parsed with the connector's supported dialect and restricted to allowed read-only ASTs. Table and column allowlists are checked within query scope. Qualified names require authorization for the full name; a same-named CTE or a table in another catalog does not grant access. If a connector supplies only unqualified names, queries should use those names. Filter values use bound parameters, with multi-value expansion handled by the executor.

Queries have row, timeout and total-wait limits. A refresh timeout prevents subsequent publication, with another check before the publication transaction commits. A running driver call cannot always be interrupted by Python: the scheduler keeps renewing its lease while waiting for the worker to exit, and lease loss cancels execution. Configure driver/database query timeouts as well.

Public-token lookup uses hashes. The encrypted token needed by an authorized publisher to recover a link is stored separately. Audit records redact sensitive details. Historical shares without a creator require a verifiable conversation owner; legacy files under pilot/data/<conv_uid> still require an ownership check. Display names are not used to infer ownership.

Deployment and upgrades​

Metadata database​

Entities are registered through the existing db_model_initialization.py. SQLite uses DB-GPT's startup table creation and migration entry point; there is no separate Dashboard Alembic revision chain. Do not depend on a request creating missing tables.

MySQL follows the existing versioned full/incremental SQL convention:

DeploymentScript under assets/schema/upgrade/v0_8_3/Procedure
New empty databasev0.8.3.sqlInitialize the full schema, equivalent to assets/schema/dbgpt.sql. Do not also run the incremental script.
Existing v0.8.2 databaseupgrade_to_v0.8.3.sqlStop the service, back up the database, run the script once, then start the new version. Upgrade older databases to v0.8.2 through the historical scripts first.

The incremental script uses ALTER TABLE ... ADD COLUMN, ADD INDEX / ADD UNIQUE INDEX for existing chat and scheduled-task tables, and CREATE TABLE IF NOT EXISTS for new tables. It does not delete business data or backfill owner IDs from display names.

Existing MySQL deployments must upgrade before starting the new version. Skipping the script leaves scheduled-task owner_id, resource_*, lease_* fields and run-idempotency indexes missing. This can cause Unknown column errors and break existing scheduled tasks as well as Dashboard features. Adjust the database name in the scripts if it is not dbgpt. The incremental script is not a repeatable initializer: if an older Dashboard script or manual DDL was already applied, compare existing columns/indexes and execute only missing changes.

Production services​

  • Use trusted authentication and enable DBGPT_DASHBOARD_PRODUCTION_MODE. The development fallback identity is rejected in this mode. A deployment-specific identity adapter can be provided through DBGPT_DASHBOARD_IDENTITY_PROVIDER.
  • Connect the deployment's data-source authorization policy through DBGPT_DASHBOARD_DATA_SOURCE_POLICY or the application integration hook. Production mode requires a policy; an object role alone is insufficient. Verify cross-user and external-connector access in the target environment.
  • Production collaboration requires Redis. Missing collaboration configuration makes that API unavailable without preventing ordinary chat and dashboard services from starting.
  • Preserve the share-encryption key. Automatic atomic key creation requires hard-link support; unsupported filesystems report an error. A deployment can instead supply DBGPT_SHARE_ENCRYPTION_KEY.
  • File analysis uses the configured SANDBOX_RUNTIME; Dashboard does not independently switch it to Lyric. Validate driver cancellation behavior and sustained load in the actual deployment.

Development and validation​

From web/, use yarn test:dashboard and yarn test for frontend tests, yarn build --webpack for a production build, and yarn compile for static export. Browser regressions use yarn test:e2e:dashboard with the environment expected by playwright.dashboard.config.ts. A build is not a substitute for browser interaction or strict type checking.

After installing backend test dependencies, run the following from the repository root in Bash. It keeps package paths and external-service markers explicit without adding another pytest configuration:

python -m pytest -c pyproject.toml --rootdir=. --import-mode=importlib -p no:cacheprovider \
-o addopts= \
-o "pythonpath=packages/dbgpt-app/src packages/dbgpt-client/src packages/dbgpt-core/src packages/dbgpt-ext/src packages/dbgpt-sandbox/src packages/dbgpt-serve/src" \
-o "markers=mysql_integration: requires DASHBOARD_TEST_MYSQL_URL and a disposable MySQL database
redis_integration: requires DASHBOARD_TEST_REDIS_URL and a disposable Redis database" \
packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/dashboard/tests \
packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tests/test_question_contract.py \
packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tests/test_share_privacy.py \
packages/dbgpt-serve/src/dbgpt_serve/scheduled_task/tests \
packages/dbgpt-app/src/dbgpt_app/tests/test_multi_file_tools.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_olist_dashboard_case.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_uploaded_dataset.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_uploaded_dataset_registry.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_python_upload_api.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_workspace_provisioning.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_dashboard_skill_orchestration.py \
examples/dashboard/tests

Set DASHBOARD_TEST_MYSQL_URL (database name must contain test) and DASHBOARD_TEST_REDIS_URL to run external-service integration tests. Without them, those tests explicitly skip. MySQL tests recreate tables: connect only to disposable test databases.

Validate the behavior being changed: manual dates must reach the query, save/publish interleavings must retain the right revision/state, revoked source permissions must prevent metadata reads, and template creation must be tested beyond its preview. Model generation, preset creation and frozen-publication filtering need separate checks. Record the tested commit and environment with results; historical screenshots are illustrations, not evidence for a newer commit.

Implementation and examples​

Capability boundaries​

AreaCurrent boundary
SQL dialectsWith SQLGlot 26.13.2, Vertica, MaxCompute, GaussDB, openGauss and OceanBase are rejected as unsupported_data_source before execution, without a generic-dialect fallback. Parser support alone does not certify a connector on a target database.
DuckDBQueries may use registered tables, not file paths or table functions that read arbitrary external files.
Unsaved inputsReloading the new-dashboard page loses inputs/options kept only in page memory. Saved assets remain accessible from the dashboard list.
AI semanticsA structurally valid result can still use the wrong business definition. Review metrics, grain, units and source values. Fixed prompts or preset runs do not establish a general generation success rate.
Layout presetslayout_templates is disabled in the checked-in release feature contract. It is not a deployment environment switch and is separate from the data-template gallery.
Style cardsThe style skills are bundled, but the home-page parameter handoff from the gallery is not connected. Treat these cards as presentation references, not a completed creation flow. Use the data-template setup or the dedicated creation page.
Filters and refreshFixed publications can only filter materialized dimensions. Live sharing needs an authorized source and offers periodic refresh, not a real-time guarantee.
Local preferencesTemplate favorites persist in the browser; account-wide, cross-device synchronization is not provided.
Demo dataSynthetic retail data and historical Walmart data are different sources. Synthetic totals are not real business totals; matching source files does not establish redistribution rights.