0
# Panoramix
1

2
Panoramix is an interactive data visualization platform built on SQLAlchemy and Druid.io. It provides a web-based interface for querying and visualizing data from various databases, with support for both SQL databases and Druid real-time analytics. Panoramix serves as the foundation for what would later become Apache Superset.
3

4
## Package Information
5

6
- **Package Name**: panoramix
7
- **Language**: Python
8
- **Installation**: `pip install panoramix`
9
- **Version**: 0.2.0
10

11
## Core Imports
12

13
```python
14
import panoramix
15
```
16

17
Main application objects:
18

19
```python
20
from panoramix import app, db, appbuilder
21
```
22

23
Data models:
24

25
```python
26
from panoramix.models import Database, Table, Cluster, Datasource
27
```
28

29
Visualizations:
30

31
```python
32
from panoramix.viz import TableViz, TimeSeriesViz, BubbleViz, viz_types
33
```
34

35
Configuration:
36

37
```python
38
from panoramix.config import ROW_LIMIT, PANORAMIX_WEBSERVER_PORT
39
```
40

41
## Basic Usage
42

43
```python
44
import panoramix
45
from panoramix.models import Database, Table
46

47
# Start the web application
48
# panoramix.app.run()
49

50
# Connect to a database
51
db = Database(
52
    database_name='my_database',
53
    sqlalchemy_uri='sqlite:///my_data.db'
54
)
55

56
# Create a table reference
57
table = Table(
58
    table_name='sales_data',
59
    database=db,
60
    main_datetime_column='created_at'
61
)
62

63
# Query the table
64
result = table.query(
65
    groupby=['product'],
66
    metrics=['sum__amount'],
67
    granularity='day'
68
)
69

70
print(result.df)  # Pandas DataFrame with results
71
```
72

73
## CLI Usage
74

75
Panoramix includes a command line interface for starting the web server:
76

77
```bash
78
# Install and create admin user
79
pip install panoramix
80
fabmanager create-admin --app panoramix
81

82
# Start the development server
83
panoramix
84

85
# The server will be available at http://localhost:8088
86
```
87

88
## Architecture
89

90
Panoramix follows a modular architecture centered around data sources and visualizations:
91

92
- **Application Layer**: Flask web application with Flask-AppBuilder for admin interface
93
- **Data Layer**: Supports both SQL databases (via SQLAlchemy) and Druid clusters (via PyDruid)
94
- **Visualization Layer**: Pluggable visualization system with multiple chart types
95
- **Model Layer**: ORM models for databases, tables, datasources, and metadata
96

97
The platform provides a semantic layer that abstracts database specifics, allowing users to create metrics, filters, and visualizations without writing SQL directly.
98

99
## Capabilities
100

101
### Data Source Management
102

103
SQL database and Druid cluster connection management, including database registration, table discovery, and metadata synchronization.
104

105
```python { .api }
106
class Database(Model, AuditMixin):
107
    def get_sqla_engine(self): ...
108
    def get_table(self, table_name): ...
109

110
class Cluster(Model, AuditMixin):
111
    def get_pydruid_client(self): ...
112
    def refresh_datasources(self): ...
113
```
114

115
[Data Sources](./data-sources.md)
116

117
### SQL Tables and Querying
118

119
SQL table management with query capabilities, metrics definition, and data exploration for traditional databases.
120

121
```python { .api }
122
class Table(Model, Queryable, AuditMixin):
123
    def query(self, groupby=None, metrics=None, granularity=None, 
124
             since=None, until=None, row_limit=None, **kwargs): ...
125
    def fetch_metadata(self): ...
126
```
127

128
[SQL Tables](./sql-tables.md)
129

130
### Druid Data Sources
131

132
Druid datasource management for real-time analytics, including dimension and metric configuration, and high-performance querying.
133

134
```python { .api }
135
class Datasource(Model, AuditMixin, Queryable):
136
    def query(self, groupby=None, metrics=None, granularity=None,
137
             since=None, until=None, row_limit=None, **kwargs): ...
138
    def get_metric_obj(self, metric_name): ...
139
```
140

141
[Druid Sources](./druid-sources.md)
142

143
### Visualization Framework
144

145
Comprehensive visualization system with multiple chart types, dynamic form generation, and chart rendering capabilities.
146

147
```python { .api }
148
class BaseViz:
149
    def bake_query(self): ...
150
    def query_obj(self): ...
151
    def render(self): ...
152

153
# Available chart types
154
viz_types = OrderedDict([
155
    ('table', TableViz),
156
    ('line', TimeSeriesViz),
157
    ('area', TimeSeriesAreaViz),
158
    ('bar', TimeSeriesBarViz),
159
    ('pie', DistributionPieViz),
160
    ('bubble', BubbleViz),
161
    # ... and more
162
])
163
```
164

165
[Visualizations](./visualizations.md)
166

167
### Web Interface and Views
168

169
Flask-based web interface with admin views for data source management and main visualization endpoints.
170

171
```python { .api }
172
class Panoramix(BaseView):
173
    @expose("/table/<table_id>/")
174
    def table(self, table_id): ...
175
    
176
    @expose("/datasource/<datasource_name>/")
177
    def datasource(self, datasource_name): ...
178
    
179
    @expose("/autocomplete/<datasource>/<column>/")
180
    def autocomplete(self, datasource, column): ...
181
```
182

183
[Web Interface](./web-interface.md)
184

185
### Configuration and Utilities
186

187
Application configuration options, utility functions for date/time parsing, and helper functions for common operations.
188

189
```python { .api }
190
# Configuration constants
191
ROW_LIMIT = 5000
192
PANORAMIX_WEBSERVER_PORT = 8088
193
APP_NAME = "Panoramix"
194

195
# Utility functions
196
def parse_human_datetime(s): ...
197
def parse_human_timedelta(s): ...
198
```
199

200
[Configuration](./configuration.md)
201

202
## Types
203

204
```python { .api }
205
class QueryResult:
206
    """Named tuple containing query results"""
207
    df: pandas.DataFrame     # Query results as DataFrame
208
    query: str              # Executed query string
209
    duration: float         # Query execution time in seconds
210

211
class AuditMixin:
212
    """Mixin providing audit fields for models"""
213
    created_on: datetime.datetime
214
    changed_on: datetime.datetime
215
    created_by: User
216
    changed_by: User
217

218
class Queryable:
219
    """Base mixin for queryable data sources"""
220
    @property
221
    def column_names(self) -> List[str]: ...
222
    @property  
223
    def groupby_column_names(self) -> List[str]: ...
224
    @property
225
    def filterable_column_names(self) -> List[str]: ...
226
```