Datasette Documentation Simon Willison Sep 22, 2021 Contents 1 Contents 3 1.1 Getting started..............................................3 1.1.1 Play with a live demo......................................3 1.1.2 Try Datasette without installing anything using Glitch.....................3 1.1.3 Using Datasette on your own computer............................4 1.1.4 datasette –get..........................................5 1.1.5 datasette serve –help......................................6 1.2 Installation................................................7 1.2.1 Basic installation........................................7 1.2.2 Advanced installation options.................................8 1.3 The Datasette Ecosystem......................................... 10 1.3.1 sqlite-utils............................................ 11 1.3.2 Dogsheep............................................ 11 1.4 Pages and API endpoints......................................... 11 1.4.1 Top-level index......................................... 11 1.4.2 Database............................................ 12 1.4.3 Table.............................................. 12 1.4.4 Row............................................... 12 1.5 Publishing data.............................................. 13 1.5.1 datasette publish........................................ 13 1.5.2 datasette package........................................ 16 1.6 Deploying Datasette........................................... 17 1.6.1 Deployment fundamentals................................... 18 1.6.2 Running Datasette using systemd................................ 18 1.6.3 Deploying using buildpacks.................................. 19 1.6.4 Running Datasette behind a proxy............................... 20 1.7 JSON API................................................ 21 1.7.1 Different shapes......................................... 21 1.7.2 Pagination............................................ 23 1.7.3 Special JSON arguments.................................... 24 1.7.4 Table arguments......................................... 24 1.7.5 Expanding foreign key references............................... 27 1.8 Running SQL queries.......................................... 27 1.8.1 Named parameters....................................... 28 1.8.2 Views.............................................. 28 1.8.3 Canned queries......................................... 28 i 1.8.4 Pagination............................................ 33 1.8.5 Cross-database queries..................................... 34 1.9 Authentication and permissions..................................... 34 1.9.1 Actors.............................................. 34 1.9.2 Permissions........................................... 35 1.9.3 Configuring permissions in metadata.json........................... 37 1.9.4 Checking permissions in plugins................................ 39 1.9.5 actor_matches_allow()..................................... 40 1.9.6 The permissions debug tool................................... 40 1.9.7 The ds_actor cookie....................................... 40 1.9.8 Built-in permissions....................................... 41 1.10 Performance and caching........................................ 42 1.10.1 Immutable mode........................................ 42 1.10.2 Using "datasette inspect".................................... 43 1.10.3 HTTP caching.......................................... 43 1.10.4 Hashed URL mode....................................... 44 1.11 CSV export................................................ 44 1.11.1 URL parameters......................................... 45 1.11.2 Streaming all records...................................... 45 1.11.3 A note on URLs......................................... 45 1.12 Binary data................................................ 45 1.12.1 Linking to binary downloads.................................. 46 1.12.2 Binary plugins......................................... 46 1.13 Facets................................................... 47 1.13.1 Facets in query strings..................................... 47 1.13.2 Facets in metadata.json..................................... 49 1.13.3 Suggested facets........................................ 49 1.13.4 Speeding up facets with indexes................................ 50 1.13.5 Facet by JSON array...................................... 50 1.13.6 Facet by date.......................................... 50 1.14 Full-text search.............................................. 50 1.14.1 The table page and table view API............................... 51 1.14.2 Advanced SQLite search queries................................ 52 1.14.3 Configuring full-text search for a table or view........................ 52 1.14.4 Searches using custom SQL.................................. 52 1.14.5 Enabling full-text search for a SQLite table.......................... 53 1.14.6 FTS versions.......................................... 55 1.15 SpatiaLite................................................. 55 1.15.1 Installation........................................... 55 1.15.2 Spatial indexing latitude/longitude columns.......................... 56 1.15.3 Making use of a spatial index.................................. 56 1.15.4 Importing shapefiles into SpatiaLite.............................. 57 1.15.5 Importing GeoJSON polygons using Shapely......................... 58 1.15.6 Querying polygons using within()............................... 58 1.16 Metadata................................................. 59 1.16.1 Per-database and per-table metadata.............................. 59 1.16.2 Source, license and about.................................... 60 1.16.3 Column descriptions...................................... 60 1.16.4 Specifying units for a column.................................. 61 1.16.5 Setting a default sort order................................... 61 1.16.6 Setting a custom page size................................... 62 1.16.7 Setting which columns can be used for sorting......................... 62 1.16.8 Specifying the label column for a table............................. 63 1.16.9 Hiding tables.......................................... 63 ii 1.16.10 Using YAML for metadata................................... 64 1.17 Settings.................................................. 64 1.17.1 Using –setting.......................................... 64 1.17.2 Configuration directory mode.................................. 64 1.17.3 Settings............................................. 65 1.17.4 Configuring the secret...................................... 69 1.17.5 Using secrets with datasette publish.............................. 70 1.18 Introspection............................................... 70 1.18.1 /-/metadata........................................... 70 1.18.2 /-/versions............................................ 71 1.18.3 /-/plugins............................................ 71 1.18.4 /-/settings............................................ 71 1.18.5 /-/databases........................................... 72 1.18.6 /-/threads............................................ 72 1.18.7 /-/actor.............................................. 73 1.18.8 /-/messages........................................... 73 1.19 Custom pages and templates....................................... 73 1.19.1 Custom CSS and JavaScript.................................. 73 1.19.2 Custom templates........................................ 76 1.19.3 Custom pages.......................................... 78 1.19.4 Custom error pages....................................... 79 1.20 Plugins.................................................. 80 1.20.1 Installing plugins........................................ 80 1.20.2 Seeing what plugins are installed................................ 81 1.20.3 Plugin configuration...................................... 82 1.21 Writing plugins.............................................. 83 1.21.1 Writing one-off plugins..................................... 84 1.21.2 Starting an installable plugin using cookiecutter........................ 84 1.21.3 Packaging a plugin....................................... 84 1.21.4 Static assets........................................... 85 1.21.5 Custom templates........................................ 86 1.21.6 Writing plugins that accept configuration........................... 86 1.21.7 Designing URLs for your plugin................................ 87 1.21.8 Building URLs within plugins................................. 87 1.22 Plugin hooks............................................... 88 1.22.1 prepare_connection(conn, database, datasette)......................... 89 1.22.2 prepare_jinja2_environment(env)................................ 89 1.22.3 extra_template_vars(template, database, table, columns, view_name, request, datasette)... 90 1.22.4 extra_css_urls(template, database, table, columns, view_name, request, datasette)...... 91 1.22.5 extra_js_urls(template, database, table, columns, view_name, request, datasette)....... 92 1.22.6 extra_body_script(template, database, table, columns, view_name, request, datasette).... 92 1.22.7 publish_subcommand(publish)................................. 93 1.22.8 render_cell(value, column, table, database, datasette)..................... 94 1.22.9 register_output_renderer(datasette)............................... 95 1.22.10 register_routes(datasette).................................... 96 1.22.11 register_commands(cli)....................................