0
# Apache Superset
1

2
Apache Superset is a modern, enterprise-ready business intelligence web application for data visualization and exploration. Built on Flask and React, it provides an intuitive interface for creating interactive dashboards, running SQL queries, and exploring datasets from diverse data sources including traditional databases, cloud data warehouses, and modern analytics engines like Druid.
3

4
## Package Information
5

6
- **Package Name**: superset
7
- **Language**: Python (Backend), JavaScript/React (Frontend)
8
- **Installation**: `pip install superset`
9
- **Version**: 0.28.0
10

11
## Core Imports
12

13
```python
14
import superset
15
from superset import app, db, security_manager
16
```
17

18
Common for CLI operations:
19

20
```python
21
from superset.cli import superset
22
```
23

24
For extending Superset functionality:
25

26
```python
27
from superset import appbuilder
28
from superset.models import core as models
29
from superset.connectors.sqla import models as sqla_models
30
from superset.connectors.druid import models as druid_models
31
```
32

33
## Basic Usage
34

35
```python
36
# Initialize Superset application
37
from superset import app, db
38

39
# Create the application context
40
with app.app_context():
41
    # Initialize database
42
    db.create_all()
43
    
44
    # Load sample data
45
    from superset.data import load_birth_names
46
    load_birth_names()
47
    
48
    # Start the web server
49
    app.run(host='0.0.0.0', port=8088, debug=True)
50
```
51

52
CLI usage for administration:
53

54
```bash
55
# Initialize the database and create default roles/permissions
56
superset init
57

58
# Create an admin user
59
superset fab create-admin
60

61
# Load example data
62
superset load-examples
63

64
# Start the web server
65
superset runserver --host 0.0.0.0 --port 8088 --debug
66
```
67

68
## Architecture
69

70
Superset follows a modular architecture designed for scalability and extensibility:
71

72
- **Web Application Layer**: Flask-based web server with React frontend providing the user interface
73
- **Security Framework**: Role-based access control system managing users, permissions, and data access
74
- **Data Layer**: Connector framework supporting SQL databases, Druid clusters, and custom data sources
75
- **Visualization Engine**: Pluggable visualization framework with 50+ chart types and map visualizations
76
- **SQL Lab**: Interactive SQL editor with async query execution and result management
77
- **Cache Layer**: Multi-tier caching system for query results, metadata, and application data
78

79
This architecture enables Superset to handle enterprise workloads while providing flexibility for customization and integration with existing data infrastructure.
80

81
## Capabilities
82

83
### CLI Interface
84

85
Complete command-line interface for administration, data management, and server operations. Includes commands for initialization, data loading, import/export operations, and worker management.
86

87
```python { .api }
88
def init(): ...
89
def runserver(): ...
90
def load_examples(): ...
91
def import_dashboards(): ...
92
def export_dashboards(): ...
93
def refresh_druid(): ...
94
def worker(): ...
95
```
96

97
[CLI Interface](./cli-interface.md)
98

99
### Web Application
100

101
Flask-based web application with comprehensive REST API endpoints for dashboard management, data exploration, and administrative functions. Includes both synchronous and asynchronous view handlers.
102

103
```python { .api }
104
class Superset:
105
    def datasources(self): ...
106
    def explore_json(self): ...
107
    def slice_json(self): ...
108
    def save_dash(self): ...
109
    def copy_dash(self): ...
110
    def testconn(self): ...
111
```
112

113
[Web Application](./web-application.md)
114

115
### Data Models
116

117
Core data models representing databases, tables, charts, dashboards, and user activity. Built on SQLAlchemy ORM with comprehensive relationship mapping and business logic methods.
118

119
```python { .api }
120
class Database:
121
    def get_sqla_engine(self): ...
122
    def fetch_metadata(self): ...
123
    def all_table_names(self): ...
124

125
class Slice:
126
    def datasource(self): ...
127
    def viz(self): ...
128

129
class Dashboard:
130
    def clone(self): ...
131
    def data(self): ...
132
```
133

134
[Data Models](./data-models.md)
135

136
### Database Connectors
137

138
Connector framework supporting SQL databases through SQLAlchemy and Druid through native APIs. Provides unified interface for data source registration, metadata discovery, and query execution.
139

140
```python { .api }
141
class ConnectorRegistry:
142
    def register_sources(self, datasource_config): ...
143
    def get_datasource(self, datasource_type, datasource_id, session): ...
144
    def get_all_datasources(self, session): ...
145

146
class SqlaTable:
147
    def query(self): ...
148
    def fetch_metadata(self): ...
149
    def values_for_column(self): ...
150
```
151

152
[Database Connectors](./database-connectors.md)
153

154
### Visualization Framework
155

156
Comprehensive visualization system with 50+ chart types including tables, time series, geospatial maps, statistical plots, and specialized visualizations. Based on D3.js, NVD3, and deck.gl.
157

158
```python { .api }
159
class BaseViz:
160
    def process_metrics(self): ...
161
    def get_df(self): ...
162
    def cache_key(self): ...
163
    def get_json_data(self): ...
164

165
class TableViz(BaseViz): ...
166
class NVD3TimeSeriesViz(BaseViz): ...
167
class MapboxViz(BaseViz): ...
168
```
169

170
[Visualization](./visualization.md)
171

172
### Security Framework
173

174
Role-based access control system with fine-grained permissions for databases, schemas, tables, and individual metrics. Supports multiple authentication methods and custom security policies.
175

176
```python { .api }
177
class SupersetSecurityManager:
178
    def can_access(self, permission_name, view_name, user=None): ...
179
    def database_access(self, database, user=None): ...
180
    def datasource_access(self, datasource, user=None): ...
181
    def get_schema_perm(self, database, schema): ...
182
```
183

184
[Security](./security.md)
185

186
### SQL Lab Interface
187

188
Interactive SQL editor with syntax highlighting, auto-completion, query history, and async execution capabilities. Supports saved queries, query sharing, and result export functionality.
189

190
```python { .api }
191
def get_sql_results(ctask, query_id, rendered_query, return_results=True, store_results=False, user_name=None, start_time=None): ...
192
def execute_sql(ctask, query_id, rendered_query, return_results, store_results, user_name, session, start_time): ...
193

194
class SqlLabView:
195
    def runsql(self): ...
196
    def sql_json(self): ...
197
    def results(self): ...
198
```
199

200
[SQL Lab](./sql-lab.md)
201

202
### Configuration Management
203

204
Comprehensive configuration system with settings for database connections, security, caching, feature flags, and UI customization. Supports environment-based configuration and runtime customization.
205

206
```python { .api }
207
SECRET_KEY: str
208
SQLALCHEMY_DATABASE_URI: str
209
CACHE_CONFIG: dict
210
FEATURE_FLAGS: dict
211
CORS_OPTIONS: dict
212
CELERY_CONFIG: object
213
```
214

215
[Configuration](./configuration.md)
216

217
### Utility Functions
218

219
Core utilities for data processing, caching, JSON serialization, time handling, database management, and Celery integration. Provides essential functionality used throughout the application.
220

221
```python { .api }
222
def flasher(msg, severity=None): ...
223
def parse_human_datetime(s): ...
224
def json_dumps(obj, default=None, ignore_nan=False, encoding=None, sort_keys=False): ...
225
def setup_cache(app, cache_config): ...
226
def get_or_create_main_db(): ...
227
def merge_extra_filters(form_data, extra_filters): ...
228
```
229

230
[Utilities](./utilities.md)