Apache Superset — User Guide

1. Quick Start

Apache Superset is a modern, enterprise-ready business intelligence web application. It provides an intuitive interface for data exploration and visualization, a feature-rich SQL editor (SQL Lab), and the ability to build interactive dashboards — all without writing code.

Key features:

• 40+ built-in visualization types (ECharts, deck.gl, D3, pivot tables, and more)
• SQL Lab — a full-featured SQL IDE with autocomplete, query history, and cost estimation
• Interactive dashboards with cross-filtering and native filter controls
• Connect to any SQL-speaking database (PostgreSQL, MySQL, BigQuery, Snowflake, Trino, and dozens more)
• Scheduled reports and alerts delivered via email or Slack
• Row-level security for multi-tenant data access
• Embedded dashboard SDK for integrating charts into external applications
• Tagging, annotation layers, and CSS template customization

Prerequisites: Docker and Docker Compose installed on your machine.

Fastest path to a running instance:

git clone https://github.com/apache/superset.git
cd superset
docker compose -f docker-compose-image-tag.yml up -d

Creating network "superset_default" with the default driver
Creating superset_db_1     ... done
Creating superset_redis_1  ... done
Creating superset_app_1    ... done
Creating superset_worker_1 ... done
Creating superset_beat_1   ... done

Open http://localhost:8088 in your browser. Log in with admin / admin.

Tip

To load example dashboards and datasets on first launch, set SUPERSET_LOAD_EXAMPLES=yes in your environment before starting the containers.

What to try next:

• Create your first chart: navigate to Charts > + Chart, pick a dataset and visualization type
• Explore SQL Lab: click SQL Lab > SQL Editor and write a query against any connected database
• Build a dashboard: go to Dashboards > + Dashboard and drag charts onto the canvas
• See the Admin Guide for full configuration, deployment, and security guidance

2. Installation

System Requirements

Important

SQLite is supported only for local development and testing. Production deployments must use PostgreSQL or MySQL as the metadata database.

Installation Methods

Docker Compose (Recommended)

git clone https://github.com/apache/superset.git
cd superset
docker compose -f docker-compose-image-tag.yml up -d

The compose file starts PostgreSQL, Redis, the Superset web app, a Celery worker, and a Celery beat scheduler.

pip (PyPI)

pip install apache-superset
superset db upgrade
superset fab create-admin
superset init
superset run -p 8088 --with-threads --reload

Helm (Kubernetes)

helm repo add superset https://apache.github.io/superset
helm install my-superset superset/superset

The Helm chart (v0.15.4, appVersion 5.0.0) bundles PostgreSQL and Redis as sub-charts from Bitnami.

From Source

git clone https://github.com/apache/superset.git
cd superset

# Backend
python -m venv venv && source venv/bin/activate
pip install -e .

# Frontend
cd superset-frontend
npm ci
npm run build
cd ..

# Initialize
superset db upgrade
superset fab create-admin
superset init
superset run -p 8088 --with-threads --reload

Post-Install Verification

curl http://localhost:8088/health

OK

Additional health endpoints: /healthcheck, /ping, /version.

Warning

On first launch, change the default admin password immediately. The default credentials (admin/admin) are well-known and must not be used in any environment accessible outside localhost.

Install Troubleshooting

Error: No module named 'superset'

Cause: The package is not installed in the active Python environment.

Solution:

1. Activate your virtual environment: source venv/bin/activate
2. Install: pip install apache-superset

Prevention: Always work inside a virtual environment.

Error: sqlalchemy.exc.OperationalError: unable to open database file

Cause: The metadata database path does not exist or lacks write permissions.

Solution:

1. Set SUPERSET_HOME to a writable directory
2. Or configure SQLALCHEMY_DATABASE_URI to point to PostgreSQL

Prevention: Use PostgreSQL for all non-trivial deployments.

Error: Container fails with FATAL: role "superset" does not exist

Cause: The PostgreSQL container has not been initialized with the expected user.

Solution:

1. Remove existing volumes: docker compose down -v
2. Restart: docker compose up -d

Prevention: Do not reuse database volumes from incompatible Superset versions.

Error: Error: Could not locate a Flask application

Cause: The FLASK_APP environment variable is not set.

Solution:

export FLASK_APP=superset

Prevention: Set this in your shell profile or .env file.

Error: Node.js version must be >= 18

Cause: Frontend build requires Node.js 18+.

Solution:

nvm install 18
nvm use 18

Prevention: Use nvm or fnm to manage Node versions.

Error: Helm upgrade fails — psycopg2 is no longer bundled (#31026)

Cause: Lean Superset Docker images removed psycopg2 from the base image.

Solution:

1. Use the full image tag (not -lean)
2. Or add psycopg2-binary to your custom requirements

Prevention: Pin image tags and test upgrades in a staging namespace first. (Community issue #31026, 25 comments)

Error: SUPERSET_SECRET_KEY must be set

Cause: Production mode requires an explicit secret key.

Solution:

export SUPERSET_SECRET_KEY=$(openssl rand -base64 42)

Prevention: Store the key in your .env file or Kubernetes Secret.

Error: Permission denied when writing to /app/superset_home

Cause: Container user does not own the home directory.

Solution:

docker compose exec superset chown -R superset:superset /app/superset_home

Prevention: Set runAsUser in Helm values to match the volume owner.

Error: Frontend build fails with JavaScript heap out of memory

Cause: Webpack requires significant memory for the build.

Solution:

export NODE_OPTIONS="--max-old-space-size=8192"
npm run build

Prevention: Allocate at least 8 GB to Node.js during builds.

Error: redis.exceptions.ConnectionError: Error connecting to redis

Cause: Redis is not running or misconfigured.

Solution:

1. Verify Redis is accessible: redis-cli ping
2. Check REDIS_HOST and REDIS_PORT in your config

Prevention: Always start Redis before the Superset application.

3. Configuration

Superset configuration is done through a Python module. By default, Superset loads superset.config, but you can override this by setting the SUPERSET_CONFIG environment variable.

export SUPERSET_CONFIG=my_custom_config

Essential Settings

Common Environment Variables

Tip

For the complete configuration reference including all feature flags, caching options, Celery settings, and security configuration, see the Admin Guide.

Feature Flags

Superset uses feature flags to control optional functionality. Set them in your superset_config.py:

FEATURE_FLAGS = {
    "ALERT_REPORTS": True,       # Enable scheduled reports and alerts
    "TAGGING_SYSTEM": True,      # Enable the tagging system
    "THUMBNAILS": True,          # Enable chart/dashboard thumbnails
    "DYNAMIC_PLUGINS": True,     # Enable the plugin manager
    "ENABLE_EXTENSIONS": True,   # Enable the extension system
}

Database Connections

Add new database connections through the UI (Settings > Database Connections > + Database) or via the REST API. Superset supports 70+ database engines through SQLAlchemy. Common connection string formats:

Note

Each database engine may require installing an additional Python driver package. The superset/db_engine_specs/ directory contains 73 engine specification files covering supported databases, each with connection validation, time grain handling, and engine-specific query optimizations.

4. Core Usage

Exploring Data with Charts

Superset's Explore view is the primary interface for building visualizations.

Creating a new chart:

1. Navigate to Charts > + Chart
2. Select a dataset (table/view from a connected database)
3. Choose a visualization type from the 40+ available options
4. Configure metrics (what to measure) and dimensions (how to group)
5. Adjust time range, filters, and display options
6. Click Run to preview
7. Click Save to persist the chart

Visualization types include:

Chart controls and options:

• Metrics: Aggregation functions (SUM, AVG, COUNT, etc.) or custom SQL expressions
• Dimensions: Columns to group by (categories, time columns)
• Filters: Ad-hoc WHERE clauses to slice data
• Time grain: Aggregation granularity (second, minute, hour, day, week, month, year)
• Row limit: Maximum rows returned (default: 50,000)
• Advanced analytics: Rolling window, time comparison, resample, and percentage calculations
• Conditional formatting: Apply color rules to table cells based on values
• Annotation layers: Overlay time-based events on timeseries charts
• Cross-filtering: Enable click-to-filter behavior in dashboards

Tip

Use the Time Comparison feature on timeseries charts to compare current values against a prior period (day, week, month, or custom offset) directly within the chart.

Result formats:

Charts can output data in multiple formats:

• JSON — structured column-based results (default)
• CSV — comma-separated values for download
• XLSX — Excel spreadsheet format

SQL Lab

SQL Lab is a full-featured SQL IDE built into Superset.

Key capabilities:

• Write and execute SQL queries against any connected database
• Autocomplete for table names, columns, and SQL keywords
• Query cost estimation (for supported databases) before executing
• Tab-based workspace — run multiple queries in parallel
• Export results as CSV or XLSX
• Save queries for reuse
• Create datasets directly from query results
• Jinja template support for parameterized queries
• SQL formatting with template variable interpolation

Writing your first query:

1. Go to SQL Lab > SQL Editor
2. Select a database and schema from the dropdowns
3. Write your SQL in the editor
4. Click Run (or press Ctrl+Enter)
5. View results in the table below
6. Optionally click Save to store the query

Using Jinja templates in SQL:

SELECT *
FROM orders
WHERE order_date >= '{{ from_dttm }}'
  AND order_date < '{{ to_dttm }}'
LIMIT {{ row_limit }}

Query result types:

Query status tracking:

Warning

SQL Lab respects database-level permissions. Ensure your database connection has appropriate read/write access configured. DML operations (INSERT, UPDATE, DELETE) are only allowed when allow_dml is enabled on the database connection.

Dashboards

Dashboards combine multiple charts into interactive views.

Building a dashboard:

1. Go to Dashboards > + Dashboard
2. Enter a title
3. Click Edit to enter edit mode
4. Drag charts from the chart panel onto the canvas
5. Resize and arrange charts using the grid layout
6. Add Markdown components for text, headers, or dividers
7. Add tabs to organize sections
8. Configure native filters for interactive filtering
9. Click Save

Dashboard features:

• Cross-filtering: Click on a chart element to filter all other charts on the same dataset
• Native filters: Add dropdown, range, or time filters that apply across charts
• Permalinks: Share specific dashboard states (filters, time ranges) via URL
• Favorites: Star dashboards for quick access
• Thumbnails: Auto-generated previews for dashboard listings
• Copy: Duplicate a dashboard with all its charts
• PDF export: Export dashboard snapshots as PDF
• Chart customizations: Per-dashboard chart display overrides
• Color configuration: Custom color schemes per dashboard
• Tab support: Organize charts into named tabs

Note

Dashboard cross-filtering works across all charts that share the same dataset. Charts from different datasets will not respond to cross-filter selections.

Reports and Alerts

When the ALERT_REPORTS feature flag is enabled, you can schedule automated report delivery and data-driven alerts.

Creating a report:

1. Go to Settings > Alerts & Reports > + Report
2. Select a dashboard or chart to report on
3. Configure the schedule using cron syntax (timezone-aware)
4. Add recipients (email addresses or Slack channels)
5. Choose the output format: PNG screenshot, PDF, or CSV data
6. Optionally set a grace period and timeout
7. Add a custom email subject and context markdown

Creating an alert:

1. Go to Settings > Alerts & Reports > + Alert
2. Write a SQL query that returns a value to evaluate
3. Configure the alert condition using the validator
4. Set the schedule for how often to check
5. Add notification recipients
6. Configure the validator type and threshold

Important

Reports and alerts require a running Celery worker and beat scheduler. The beat schedule fires the reports.scheduler task every minute and prunes logs daily at 00:10.

Tags

When the TAGGING_SYSTEM feature flag is enabled, you can organize charts, dashboards, and datasets with custom tags.

Tag operations:

• Create, read, update, and delete tags
• Associate tags with charts, dashboards, and datasets
• Bulk-create tags with multi-object association
• Filter list views by tag
• Favorite tags for quick access
• View all objects tagged with a specific tag

Annotations

Annotation layers allow you to overlay time-based events on timeseries charts:

1. Go to Settings > Annotation Layers > + Annotation Layer
2. Create a layer with a name and description
3. Add individual annotations with start/end dates and descriptions
4. Reference the layer in any timeseries chart's annotation configuration

CSS Templates

CSS templates allow you to customize the appearance of dashboards:

1. Go to Settings > CSS Templates
2. Create a template with custom CSS
3. Apply the template to specific dashboards

Themes

Superset supports system-level theme definitions with dark mode support. Themes can be configured by administrators and applied globally.

5. Common Tasks

Connect a New Database

Goal: Add a PostgreSQL database as a data source.

Steps:

1. Navigate to Settings > Database Connections > + Database
2. Select "PostgreSQL" from the database type list
3. Enter connection details:

   Host: db.example.com
   Port: 5432
   Database: analytics
   Username: readonly_user
   Password: ********
   

4. Click Test Connection to verify
5. Click Connect

Verify: The new database appears in the database list and in SQL Lab's database dropdown.

If it fails: Check that the database host is reachable from the Superset server and that the credentials are correct. Ensure the required Python driver (e.g., psycopg2) is installed.

Create a Dataset from a SQL Query

Goal: Save a complex query as a reusable dataset for charts.

Steps:

1. Open SQL Lab > SQL Editor
2. Write and run your query
3. Click Save > Save Dataset
4. Enter a name and select the target schema
5. Click Save

Verify: The dataset appears under Datasets and is available when creating new charts.

Build a Dashboard with Filters

Goal: Create an interactive dashboard with a date and category filter.

Steps:

1. Create 3-4 charts from the same dataset
2. Go to Dashboards > + Dashboard
3. Drag your charts onto the canvas
4. Click the filter icon to add a Native Filter
5. Add a "Time Range" filter targeting the date column
6. Add a "Value" filter targeting the category column
7. Map each filter to the relevant charts
8. Click Save

Verify: Changing filter values updates all mapped charts in real time.

Export and Import Dashboards

Goal: Move dashboards between Superset instances.

Export via CLI:

superset export_dashboards -f dashboards_backup.zip

Import via CLI:

superset import_dashboards -p dashboards_backup.zip -u admin

Export via API:

curl -X GET "http://localhost:8088/api/v1/assets/export/" \
  -H "Authorization: Bearer $TOKEN" \
  -o assets.zip

Import via API:

curl -X POST "http://localhost:8088/api/v1/assets/import/" \
  -H "Authorization: Bearer $TOKEN" \
  -F "bundle=@assets.zip" \
  -F "passwords={}" \
  -F "ssh_tunnel_passwords={}"

Tip

The import/export format is a ZIP file containing YAML definitions for databases, datasets, charts, dashboards, and saved queries. You can version-control these files for infrastructure-as-code workflows.

Embed a Dashboard in an External Application

Goal: Display a Superset dashboard inside your web application.

Steps:

1. Configure an embedded dashboard via the API:

   curl -X POST "http://localhost:8088/api/v1/dashboard/<id>/embedded" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"allowed_domains": ["https://yourapp.com"]}'
   

2. Install the SDK in your frontend:

   npm install @superset-ui/embedded-sdk
   

3. Embed the dashboard:

   import { embedDashboard } from '@superset-ui/embedded-sdk';
   
   embedDashboard({
     id: '<embedded-uuid>',
     supersetDomain: 'https://superset.example.com',
     mountPoint: document.getElementById('dashboard-container'),
     fetchGuestToken: () => fetchGuestTokenFromBackend(),
     dashboardUiConfig: {
       hideTitle: true,
       hideChartControls: true,
       hideTab: false,
     },
   });
   

4. The SDK handles automatic guest token refresh before expiry

Verify: The dashboard renders inside your application with the specified UI configuration.

Embedded dashboard query parameters:

Schedule a Weekly Report

Goal: Send a PDF of a dashboard to the team every Monday morning.

Steps:

1. Go to Settings > Alerts & Reports > + Report
2. Set name: "Weekly Sales Report"
3. Select the target dashboard
4. Set schedule: 0 9 * * 1 (every Monday at 9:00 AM)
5. Select timezone
6. Add email recipients
7. Choose format: PDF
8. Activate the report

Verify: Check the report log after the next scheduled run to confirm delivery.

Upload Data from a CSV File

Goal: Load a CSV file as a new dataset.

Steps:

1. Navigate to Settings > Database Connections
2. Select a database that allows file upload (allow_file_upload: true)
3. Click Upload > CSV
4. Select the file and configure column types
5. Choose the target table name and schema
6. Click Upload

Verify: The new table appears in the database and is queryable in SQL Lab.

Note

Superset supports CSV, Excel (.xlsx), and Parquet file uploads through the CSVReader, ExcelReader, and ColumnarReader upload handlers.

Set Up Row-Level Security

Goal: Restrict data access so each team sees only their own data.

Steps:

1. Go to Settings > Row Level Security > + Rule
2. Enter a name and description
3. Select the filter type
4. Choose the target tables
5. Assign roles (e.g., "Sales Team")
6. Define the SQL clause: team_id = 'sales'
7. Optionally set a group key for organization
8. Save the rule

Verify: Users with the "Sales Team" role only see rows where team_id = 'sales'.

Use the Extensions CLI

Goal: Create a custom Superset extension.

pip install superset-extensions-cli
superset-extensions-cli init \
  --publisher my-org \
  --name dashboard-widgets \
  --display-name "Dashboard Widgets" \
  --version 0.1.0 \
  --license Apache-2.0 \
  --frontend \
  --backend

Build and bundle the extension:

superset-extensions-cli build
superset-extensions-cli bundle -o my-extension.zip

Validate the extension:

superset-extensions-cli validate

Load Example Data

Goal: Populate Superset with example datasets and dashboards for exploration.

superset load_examples

Test a Database Connection

Goal: Validate a database URI before adding it to Superset.

superset test_db "postgresql+psycopg2://user:pass@host:5432/db"

Pass additional connection arguments as JSON:

superset test_db "postgresql+psycopg2://user:pass@host:5432/db" \
  -c '{"connect_timeout": 10}'

Use the MCP Service

Goal: Access Superset programmatically via the Model Context Protocol.

Start the MCP server:

superset mcp run --host 0.0.0.0 --port 5008

Environment variables:

• FASTMCP_TRANSPORT — transport mode: stdio (default) or http
• FASTMCP_HOST — host override (default: 127.0.0.1)
• FASTMCP_PORT — port override (default: 5008)

6. Troubleshooting

Use this diagnostic flow to narrow down issues:

Is Superset running?
+--> No --> Check container logs: docker compose logs superset
|           Check process: ps aux | grep superset
+--> Yes --> Can you reach the UI?
             +--> No --> Check port binding (8088)
             |           Check reverse proxy / firewall
             +--> Yes --> Is your issue with...
                          +--> A chart? --> Check dataset, query, viz type
                          +--> SQL Lab? --> Check database connection
                          +--> A dashboard? --> Check chart dependencies
                          +--> Reports? --> Check Celery worker + beat
                          +--> Performance? --> Check cache config + query complexity

Error: ERROR:superset:Refusing to start due to insecure SECRET_KEY

Cause: Superset detected a default or missing secret key in a non-debug environment.

Solution:

export SUPERSET_SECRET_KEY=$(openssl rand -base64 42)

Prevention: Set SUPERSET_SECRET_KEY in your .env or Kubernetes Secret before first startup.

Error: Chart displays "No data" when data exists

Cause: Time range filter excludes all rows, or the metric/dimension configuration is incorrect.

Solution:

1. Verify the time range includes dates present in the dataset
2. Check that the metric column contains non-null values
3. Preview data in SQL Lab with the same filters

Prevention: Use "No filter" time range during initial chart development.

Error: celery.exceptions.NotRegistered

Cause: The Celery worker cannot find the task module.

Solution:

1. Ensure the worker starts with --app=superset.tasks.celery_app:app
2. Verify superset.tasks is importable from the worker's Python environment

Prevention: Use the Docker Compose setup, which configures workers correctly.

Error: SQL Lab query runs indefinitely

Cause: The query is too complex or the database is under heavy load.

Solution:

1. Cancel the query from SQL Lab
2. Add LIMIT to reduce result set size
3. Check database-side query timeout settings

Prevention: Use query cost estimation before running expensive queries. Configure SQLLAB_TIMEOUT in superset_config.py.

Error: OSError: [Errno 99] Cannot assign requested address

Cause: The bind address is not available on the host.

Solution:

superset run --host 0.0.0.0 -p 8088

Prevention: Use 0.0.0.0 instead of 127.0.0.1 when running inside Docker.

Error: Dashboard filters do not affect certain charts

Cause: The filter is not mapped to those charts, or the charts use different datasets.

Solution:

1. Edit the native filter and verify the "Scoping" tab includes the affected charts
2. Ensure charts share the same dataset or have compatible column names

Prevention: Map filters explicitly to all target charts when creating them.

Error: ReportScheduleNotFoundError when running reports

Cause: The report schedule was deleted or the ID is invalid.

Solution:

1. Verify the report exists in Settings > Alerts & Reports
2. Re-create the schedule if it was deleted

Prevention: Do not delete reports that are referenced by external integrations.

Error: TimeoutError during CSV upload

Cause: The file is too large for the default upload timeout.

Solution:

1. Increase upload-related timeout settings in configuration
2. Use SQL Lab to COPY data directly into the database for very large files

Prevention: For files larger than 100 MB, use direct database import tools instead of the UI uploader.

Error: Embedded dashboard shows blank iframe

Cause: The embedding domain is not in the allowed_domains list, or the guest token is expired.

Solution:

1. Verify allowed_domains includes your application's origin
2. Check that the fetchGuestToken function returns a valid, non-expired token

Prevention: Implement automatic token refresh using the SDK's built-in refresh mechanism.

Error: Leftover Debug Statement Polluting Console in ZoomConfigControl (#39622)

Cause: A debug console.log statement was left in the ZoomConfigControl component.

Solution: This is a known issue (community issue #39622). It does not affect functionality — only console output.

Prevention: This will be fixed in a future release.

Error: QueryClauseValidationException

Cause: A SQL clause (WHERE, HAVING) contains disallowed syntax.

Solution:

1. Review the query clause for syntax errors
2. Remove any statements not allowed by the SQL validator (e.g., sub-selects in WHERE if restricted)

Prevention: Use the SQL Lab query preview to validate clauses before using them in chart configurations.

Error: SupersetGenericDBErrorException when connecting to a database

Cause: The SQLAlchemy URI is malformed or the database is unreachable.

Solution:

1. Use superset test_db <uri> to validate the connection
2. Verify network connectivity to the database host
3. Check that the correct driver package is installed

Prevention: Always test connections before saving database configurations.

Error: OAuth2 authentication fails for database connections

Cause: OAuth2 configuration is incomplete or tokens are expired.

Solution:

1. Verify the OAuth2 configuration for the database connection
2. Check token expiry and refresh token availability
3. Re-authenticate through the database connection's OAuth2 flow

Prevention: Monitor token expiry and configure automatic refresh where supported.

Caution

When troubleshooting database connections, never share SQLAlchemy URIs in plain text — they contain credentials. Use superset re_encrypt_secrets if you suspect key exposure.

7. FAQ

Q: What databases does Superset support?

Superset supports any database with a SQLAlchemy-compatible driver. This includes PostgreSQL, MySQL, SQLite, BigQuery, Snowflake, Trino, Presto, ClickHouse, DuckDB, Apache Druid, Apache Hive, Databricks, Microsoft SQL Server, Oracle, Redshift, and 60+ others. The superset/db_engine_specs/ directory contains 73 engine specification modules. Each database engine may require its own Python driver package.

Q: Can I use Superset without Docker?

Yes. Install via pip (pip install apache-superset) and run directly with Python. You will need to set up PostgreSQL and Redis separately for production use.

Q: How do I reset the admin password?

Use the Flask-AppBuilder CLI:

superset fab reset-password --username admin --password new_password

Q: Can I create charts without writing SQL?

Yes. Superset's Explore view provides a no-code chart builder. Select a dataset, choose metrics and dimensions using drag-and-drop controls, and the query is generated automatically.

Q: How do I add a custom visualization plugin?

Use the Yeoman generator to scaffold a new plugin:

npm install -g yo @superset-ui/generator-superset
mkdir superset-plugin-chart-custom
cd superset-plugin-chart-custom
yo @superset-ui/superset

Build the plugin and register it in MainPreset.js. Alternatively, use the newer superset-extensions-cli init command to scaffold an extension with both frontend and backend components.

Q: What is the difference between a dataset and a database?

A database is a connection to an external data source (PostgreSQL, MySQL, etc.). A dataset is a specific table, view, or saved query within a database that Superset uses as the basis for charts.

Q: How do I enable dark mode?

Superset supports theme configuration including dark mode. Configure themes through the admin settings. The embedded SDK also supports themeMode options: "default", "dark", or "system".

Q: Can I version-control my dashboards?

Yes. Use superset export_dashboards to export dashboards as ZIP files containing YAML definitions. These can be committed to Git and imported into other instances with superset import_dashboards.

Q: How do I upgrade Superset?

1. Back up your metadata database
2. Update the Superset package: pip install --upgrade apache-superset
3. Run database migrations: superset db upgrade
4. Re-initialize: superset init
5. Restart the application

For Docker deployments, update the image tag and restart containers.

Q: What is the superset init command?

superset init creates default roles and permissions. Run it after installation and after database migrations to ensure all security metadata is current.

Q: How do I connect to a database that requires SSH tunneling?

Superset supports SSH tunnel configuration when adding database connections. Provide the SSH host, port, username, and private key in the database connection form or via the import API's ssh_tunnel_passwords and ssh_tunnel_private_keys parameters.

Q: Can I use template variables in SQL queries?

Yes. SQL Lab supports Jinja templating. Use {{ var }} syntax to reference template variables. Built-in variables include {{ from_dttm }}, {{ to_dttm }}, and {{ row_limit }}.

Q: How do I re-encrypt secrets after changing the SECRET_KEY?

Use the CLI command:

superset re_encrypt_secrets --previous_secret_key "old_key_here"

This re-encrypts all stored database passwords and other encrypted fields with the new key.

Q: What ports does Superset use?

Q: Can multiple users edit a dashboard simultaneously?

Dashboard editing is not collaborative in real time. Only one user should edit a dashboard at a time to avoid overwriting changes. The WebSocket service provides real-time event streaming for dashboard viewing, not editing.

Q: How do I migrate legacy chart types to ECharts?

Use the visualization migration CLI:

superset migrate_viz upgrade --viz_type <type>

To migrate specific charts by ID:

superset migrate_viz upgrade --viz_type <type> --id 42 --id 43

To revert a migration:

superset migrate_viz downgrade --viz_type <type>

Q: How do I factory-reset a Superset instance?

superset factory_reset --username admin --silent

Optionally exclude specific users or roles:

superset factory_reset --username admin --exclude-users "service_account" --exclude-roles "Custom_Role"

Caution

factory_reset is destructive and irreversible. It removes all dashboards, charts, datasets, and associated data. Back up your metadata database before running this command.

Q: How do I sync tags across objects?

Use the CLI command:

superset sync_tags

This synchronizes tag associations across all tagged objects in the metadata database.

Q: What is the Superset Meta Database?

When ENABLE_SUPERSET_META_DB feature flag is enabled, Superset registers itself as a data source via Shillelagh and the superset:// SQLAlchemy dialect. This allows querying Superset's own metadata as if it were an external database.