0
# Data Models
1

2
Core data models representing databases, tables, charts, dashboards, and user activity. Built on SQLAlchemy ORM with comprehensive relationship mapping and business logic methods for managing Superset's data layer.
3

4
## Capabilities
5

6
### Core Models
7

8
Primary entities that form the foundation of the Superset data architecture.
9

10
```python { .api }
11
class Database:
12
    """
13
    Database connection configuration and management.
14
    
15
    Key Fields:
16
    - database_name: str, connection display name
17
    - sqlalchemy_uri: str, database connection string
18
    - password: str, encrypted database password
19
    - cache_timeout: int, default query cache duration in seconds
20
    - expose_in_sqllab: bool, availability in SQL Lab interface
21
    - allow_run_async: bool, asynchronous query execution support
22
    - allow_csv_upload: bool, CSV file upload capability
23
    - allow_ctas: bool, CREATE TABLE AS SELECT support
24
    - allow_dml: bool, data modification language support
25
    - force_ctas_schema: str, default schema for CTAS operations
26
    """
27
    
28
    def get_sqla_engine(self):
29
        """
30
        Get SQLAlchemy engine instance.
31
        Creates configured database engine with connection pooling.
32
        
33
        Returns:
34
        SQLAlchemy Engine object with proper configuration
35
        """
36
    
37
    def get_reserved_words(self):
38
        """
39
        Get database-specific reserved words.
40
        
41
        Returns:
42
        Set of reserved keywords for SQL generation
43
        """
44
    
45
    def get_quoter(self):
46
        """
47
        Get identifier quoter function.
48
        
49
        Returns:
50
        Function for quoting database identifiers
51
        """
52
    
53
    def db_engine_spec(self):
54
        """
55
        Get database engine specification.
56
        
57
        Returns:
58
        Engine-specific configuration and capabilities class
59
        """
60
    
61
    def grains(self):
62
        """
63
        Get available time grains for grouping.
64
        
65
        Returns:
66
        List of supported time grain definitions
67
        """
68
    
69
    def fetch_metadata(self):
70
        """
71
        Fetch and update database metadata.
72
        Discovers tables, columns, and relationships.
73
        """
74
    
75
    def all_table_names(self):
76
        """
77
        List all table names in database.
78
        
79
        Returns:
80
        List of table names across all schemas
81
        """
82
    
83
    def all_view_names(self):
84
        """
85
        List all view names in database.
86
        
87
        Returns:
88
        List of view names across all schemas
89
        """
90

91
class Slice:
92
    """
93
    Chart/visualization definition and configuration.
94
    
95
    Key Fields:
96
    - slice_name: str, display name for chart
97
    - datasource_type: str, type of underlying datasource
98
    - datasource_id: int, identifier of datasource
99
    - viz_type: str, visualization type identifier
100
    - params: str, JSON-encoded chart configuration parameters
101
    - cache_timeout: int, chart-specific cache duration
102
    
103
    Relationships:
104
    - owners: User[], chart owners with edit permissions (many-to-many)
105
    - dashboards: Dashboard[], associated dashboards (many-to-many)
106
    """
107
    
108
    def datasource(self):
109
        """
110
        Get associated datasource object.
111
        
112
        Returns:
113
        Datasource instance (SqlaTable or DruidDatasource)
114
        """
115
    
116
    def viz(self):
117
        """
118
        Create visualization object from configuration.
119
        
120
        Returns:
121
        Configured visualization instance for rendering
122
        """
123
    
124
    def get_viz(self):
125
        """
126
        Get cached visualization instance.
127
        
128
        Returns:
129
        Cached or newly created visualization object
130
        """
131

132
class Dashboard:
133
    """
134
    Dashboard composition, layout, and metadata management.
135
    
136
    Key Fields:
137
    - dashboard_title: str, dashboard display name
138
    - position_json: str, JSON-encoded layout configuration
139
    - description: str, dashboard description text
140
    - css: str, custom CSS styling rules
141
    - json_metadata: str, additional metadata and configuration
142
    - published: bool, publication status for sharing
143
    
144
    Relationships:
145
    - slices: Slice[], included charts and visualizations (many-to-many)
146
    - owners: User[], dashboard owners with edit permissions (many-to-many)
147
    """
148
    
149
    def clone(self):
150
        """
151
        Create dashboard copy with new identifier.
152
        
153
        Returns:
154
        New Dashboard instance with copied configuration
155
        """
156
    
157
    def data(self):
158
        """
159
        Get complete dashboard data for rendering.
160
        
161
        Returns:
162
        Dictionary with dashboard metadata, slices, and layout
163
        """
164
    
165
    def url(self):
166
        """
167
        Get dashboard URL path.
168
        
169
        Returns:
170
        URL string for dashboard access
171
        """
172
```
173

174
### Supporting Models
175

176
Additional models for templates, logging, and system functionality.
177

178
```python { .api }
179
class CssTemplate:
180
    """
181
    Reusable CSS template definitions.
182
    
183
    Key Fields:
184
    - template_name: str, template identifier name
185
    - css: str, CSS content and styling rules
186
    """
187

188
class Log:
189
    """
190
    Audit logging for user actions and system events.
191
    
192
    Key Fields:
193
    - action: str, type of action performed
194
    - user_id: int, identifier of user performing action
195
    - json: str, JSON-encoded action details and context
196
    - dttm: datetime, timestamp of action occurrence
197
    - dashboard_id: int, associated dashboard identifier
198
    - slice_id: int, associated chart identifier  
199
    - referrer: str, HTTP referrer header value
200
    - duration_ms: int, action duration in milliseconds
201
    """
202

203
class Url:
204
    """
205
    Short URL storage for link sharing.
206
    
207
    Key Fields:
208
    - url: str, original long URL to be shortened
209
    """
210

211
class KeyValue:
212
    """
213
    Generic key-value storage for application data.
214
    
215
    Key Fields:
216
    - value: str, stored value content
217
    """
218

219
class FavStar:
220
    """
221
    User favorites tracking across object types.
222
    
223
    Key Fields:
224
    - user_id: int, user identifier
225
    - class_name: str, favorited object type
226
    - obj_id: int, favorited object identifier
227
    - dttm: datetime, favorite creation timestamp
228
    """
229

230
class DatasourceAccessRequest:
231
    """
232
    Access request workflow for restricted datasources.
233
    
234
    Key Fields:
235
    - datasource_type: str, requested datasource type
236
    - datasource_id: int, requested datasource identifier
237
    - changed_by_fk: int, user requesting access
238
    - created_by_fk: int, user who created request
239
    """
240
```
241

242
## SQL Lab Models
243

244
Specialized models for SQL Lab query execution and management.
245

246
```python { .api }
247
class Query:
248
    """
249
    SQL Lab query execution tracking and results management.
250
    
251
    Key Fields:
252
    - client_id: str, client session identifier
253
    - database_id: int, database connection identifier
254
    - tmp_table_name: str, temporary table name for results
255
    - user_id: int, user executing query
256
    - status: str, current execution status
257
    - tab_name: str, SQL Lab tab display name
258
    - sql_editor_id: str, editor instance identifier
259
    - schema: str, target schema for query execution
260
    - sql: str, original SQL query text
261
    - select_sql: str, generated SELECT statement
262
    - executed_sql: str, actually executed SQL with modifications
263
    - limit: int, requested result row limit
264
    - limit_used: bool, whether limit was applied
265
    - select_as_cta: bool, CREATE TABLE AS SELECT flag
266
    - select_as_cta_used: bool, whether CTAS was used
267
    - progress: int, execution progress percentage
268
    - rows: int, number of result rows returned
269
    - error_message: str, error details if execution failed
270
    - results_key: str, storage key for large result sets
271
    - start_time: datetime, query execution start time
272
    - start_running_time: datetime, actual execution start
273
    - end_time: datetime, query completion time
274
    - end_result_backend_time: datetime, backend storage completion
275
    """
276

277
class SavedQuery:
278
    """
279
    Saved SQL Lab queries for reuse and sharing.
280
    
281
    Key Fields:
282
    - user_id: int, query owner user identifier
283
    - db_id: int, associated database identifier
284
    - label: str, query display name
285
    - schema: str, target schema context
286
    - sql: str, saved SQL query text
287
    - description: str, query description and notes
288
    """
289

290
class TabState:
291
    """
292
    SQL Lab tab persistence and state management.
293
    
294
    Key Fields:
295
    - user_id: int, tab owner user identifier
296
    - label: str, tab display label
297
    - active: bool, active tab indicator
298
    - database_id: int, selected database connection
299
    - schema: str, selected schema context
300
    - sql: str, current SQL content
301
    - query_limit: int, default result limit
302
    - latest_query_id: str, most recent query identifier
303
    - autorun: bool, automatic execution flag
304
    - template_params: str, Jinja template parameters
305
    """
306

307
class TableSchema:
308
    """
309
    Table metadata cache for performance optimization.
310
    
311
    Key Fields:
312
    - database_id: int, database connection identifier
313
    - schema: str, schema name
314
    - table_name: str, table name
315
    - perm: str, permission identifier string
316
    - description: str, table description text
317
    """
318
```
319

320
## Model Relationships
321

322
### Many-to-Many Associations
323

324
```python { .api }
325
# Dashboard-Slice Association
326
dashboard_slices = Table(
327
    'dashboard_slices',
328
    Column('dashboard_id', Integer, ForeignKey('dashboards.id')),
329
    Column('slice_id', Integer, ForeignKey('slices.id'))
330
)
331

332
# Dashboard-User Ownership
333
dashboard_user = Table(
334
    'dashboard_user',
335
    Column('dashboard_id', Integer, ForeignKey('dashboards.id')),
336
    Column('user_id', Integer, ForeignKey('ab_user.id'))
337
)
338

339
# Slice-User Ownership  
340
slice_user = Table(
341
    'slice_user',
342
    Column('slice_id', Integer, ForeignKey('slices.id')),
343
    Column('user_id', Integer, ForeignKey('ab_user.id'))
344
)
345
```
346

347
### Foreign Key Relationships
348

349
```python { .api }
350
# Slice to Datasource (Polymorphic)
351
slice.datasource_id -> {sqla_table.id, druid_datasource.id}
352
slice.datasource_type -> {'table', 'druid'}
353

354
# Query to Database
355
query.database_id -> database.id
356

357
# Log Entry Associations
358
log.dashboard_id -> dashboard.id (optional)
359
log.slice_id -> slice.id (optional)
360
log.user_id -> user.id
361

362
# Access Request Associations
363
datasource_access_request.datasource_id -> {sqla_table.id, druid_datasource.id}
364
datasource_access_request.changed_by_fk -> user.id
365
```
366

367
## Data Access Patterns
368

369
### Query Construction
370

371
```python { .api }
372
# Get user's accessible databases
373
databases = (
374
    session.query(Database)
375
    .filter(Database.expose_in_sqllab == True)
376
    .filter(security_manager.database_access(Database))
377
    .all()
378
)
379

380
# Get dashboard with slices
381
dashboard = (
382
    session.query(Dashboard)
383
    .options(joinedload(Dashboard.slices))
384
    .filter(Dashboard.id == dashboard_id)
385
    .one_or_none()
386
)
387

388
# Get recent user activity
389
recent_logs = (
390
    session.query(Log)
391
    .filter(Log.user_id == user_id)
392
    .order_by(Log.dttm.desc())
393
    .limit(50)
394
    .all()
395
)
396
```
397

398
### Permissions Integration
399

400
```python { .api }
401
# Check slice access
402
if security_manager.datasource_access(slice.datasource):
403
    # User can access this slice
404
    return slice.get_viz()
405

406
# Filter accessible datasources
407
accessible_tables = [
408
    table for table in tables
409
    if security_manager.datasource_access(table)
410
]
411
```
412

413
## Model Extensions
414

415
### Mixins and Base Classes
416

417
```python { .api }
418
class AuditMixin:
419
    """
420
    Audit trail mixin for tracking changes.
421
    Adds created_on, changed_on, created_by, changed_by fields.
422
    """
423

424
class ImportMixin:
425
    """
426
    Import/export functionality mixin.
427
    Provides YAML serialization for configuration management.
428
    """
429

430
class BaseDatasource:
431
    """
432
    Base class for all datasource types.
433
    Defines common interface for tables and Druid datasources.
434
    """
435
```
436

437
The data model layer provides a robust foundation for Superset's functionality, with proper abstractions for different datasource types, comprehensive audit trails, and flexible permission integration.