Datasette plugin providing data dashboards from metadata
Project description
datasette-dashboards
Datasette plugin providing data dashboards from metadata
Try out a live demo at https://datasette-dashboards-demo.vercel.app
WARNING: this plugin is still experimental and not ready for production. Some breaking changes might happen between releases before reaching a stable version. Use it at your own risks!
Installation
Install this plugin in the same environment as Datasette:
$ datasette install datasette-dashboards
Usage
Define dashboards within metadata.yml
/ metadata.json
:
plugins:
datasette-dashboards:
my-dashboard:
title: My Dashboard
description: Showing some nice metrics
layout:
- [analysis-note, events-count]
- [analysis-note, events-source]
filters:
date_start:
name: Date Start
type: date
default: "2021-01-01"
date_end:
name: Date End
type: date
charts:
analysis-note:
library: markdown
display: |-
# Analysis notes
> A quick rundown of events statistics and KPIs
events-count:
title: Total number of events
db: jobs
query: SELECT count(*) as count FROM events
library: metric
display:
field: count
prefix:
suffix:
events-source:
title: Number of events by source
db: jobs
query: SELECT source, count(*) as count FROM events WHERE TRUE [[ AND date >= date(:date_start) ]] [[ AND date <= date(:date_end) ]] GROUP BY source ORDER BY count DESC
library: vega
display:
mark: { type: bar, tooltip: true }
encoding:
color: { field: source, type: nominal }
theta: { field: count, type: quantitative }
A new menu entry is now available, pointing at /-/dashboards
to access all defined dashboards.
Properties
Dashboard properties:
Property | Type | Description |
---|---|---|
title |
string |
Dashboard title |
description |
string |
Dashboard description |
layout |
array |
Dashboard layout |
filters |
object |
Dashboard filters |
Dashboard filters:
Property | Type | Description |
---|---|---|
name |
string |
Filter display name |
type |
string |
Filter type (text , date , number ) |
default |
string , number |
(optional) Filter default value |
min |
number |
(optional) Filter minimum value |
max |
number |
(optional) Filter maximum value |
step |
number |
(optional) Filter stepping value |
Common chart properties for all chart types:
Property | Type | Description |
---|---|---|
title |
string |
Chart title |
db |
string |
Database name against which to run the query |
query |
string |
SQL query to run and extract data from |
library |
string |
One of supported libraries: vega , markdown |
display |
object |
Chart display specification (depend on the used library) |
To define SQL queries using dashboard filters:
SELECT * FROM mytable [[ WHERE col >= :my_filter ]]
SELECT * FROM mytable WHERE TRUE [[ AND col1 = :my_filter_1 ]] [[ AND col2 = :my_filter_2 ]]
Vega properties
Available configuration for vega
charts:
Property | Type | Description |
---|---|---|
library |
string |
Must be set to vega |
display |
object |
Vega specification object |
Notes about the display
property:
- Requires a valid Vega specification object
- Some fields are pre-defined:
$schema
,title
,width
,view
,config
,data
- All fields are passed along as-is (overriding pre-defined fields if any)
- Only
mark
andencoding
fields are required as the bare-minimum
Markdown properties
Available configuration for markdown
chart:
Property | Type | Description |
---|---|---|
library |
string |
Must be set to markdown |
display |
string |
Multi-line string containing the Markdown content |
Note :
- Some common properties do not apply and can be omitted:
title
,db
,query
- Markdown rendering is done by
datasette-render-markdown
- To configure Markdown rendering, extensions can be enabled in metadata
Metric properties
Available configuration for metric
chart:
Property | Type | Description |
---|---|---|
library |
string |
Must be set to metric |
display.field |
string |
Numerical field to be displayed as metric |
display.prefix |
string |
Prefix to be displayed before metric |
display.suffix |
string |
Prefix to be displayed after metric |
Note:
- The
display.field
must reference a single-numerical value from the SQL query (e.g. numericalnumber
field inSELECT count(*) as number FROM events
)
Dashboard layout
The default dashboard layout will present two charts per row (one per row on mobile).
To make use of custom dashboard layout using CSS Grid Layout,
define the layout
array property as a grid / matrix:
- Each entry represents a row of charts
- Each column is referring a chart by its property name
Development
To set up this plugin locally, first checkout the code. Then create a new virtual environment and the required dependencies:
pipenv install -d
pipenv shell
To run the tests:
pytest
Demo
With the developmnent environment setup, you can run the demo locally:
datasette --metadata demo/metadata.yml demo/jobs.db
License
Licensed under Apache License, Version 2.0
Copyright (c) 2021 - present Romain Clement
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for datasette-dashboards-0.1.6.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | fa2b9646af4f2d1b335b45d92990e3f73d0acc1c2879c5fbb6ac39afbc962f2d |
|
MD5 | 63e3f1a11d2acadfbc344b170037a4a1 |
|
BLAKE2b-256 | 630beaeccf7c3d785b0aa9cdd111b945e3e8227ca9596cd981fb43513cf96f97 |
Hashes for datasette_dashboards-0.1.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7a6c1b1347f4b8713f87cb9fc39a5096aa96412ee21700a6f7c908cabf3c1d1 |
|
MD5 | 44e2855041cf91f674863329ad2332f6 |
|
BLAKE2b-256 | 79bbc7c7ca4bf673c906c560bce3628fa660ba6f3667190e98dba1807409a52c |