2018-05-12 22:29:06 +00:00
.. _metadata:
2017-12-07 17:19:35 +00:00
Metadata
========
Data loves metadata. Any time you run Datasette you can optionally include a
JSON file with metadata about your databases and tables. Datasette will then
display that information in the web UI.
Run Datasette like this::
datasette database1.db database2.db --metadata metadata.json
Your `` metadata.json `` file can look something like this::
{
"title": "Custom title for your index page",
"description": "Some description text can go here",
"license": "ODbL",
"license_url": "https://opendatacommons.org/licenses/odbl/",
"source": "Original Data Source",
"source_url": "http://example.com/"
}
The above metadata will be displayed on the index page of your Datasette-powered
site. The source and license information will also be included in the footer of
every page served by Datasette.
Any special HTML characters in `` description `` will be escaped. If you want to
include HTML in your description, you can use a `` description_html `` property
instead.
Per-database and per-table metadata
-----------------------------------
Metadata at the top level of the JSON will be shown on the index page and in the
footer on every page of the site. The license and source is expected to apply to
all of your data.
You can also provide metadata at the per-database or per-table level, like this::
{
"databases": {
"database1": {
"source": "Alternative source",
"source_url": "http://example.com/",
"tables": {
"example_table": {
"description_html": "Custom <em>table</em> description",
"license": "CC BY 3.0 US",
"license_url": "https://creativecommons.org/licenses/by/3.0/us/"
}
}
}
}
}
Each of the top-level metadata fields can be used at the database and table level.
2018-04-14 10:16:09 +00:00
Specifying units for a column
-----------------------------
Datasette supports attaching units to a column, which will be used when displaying
values from that column. SI prefixes will be used where appropriate.
Column units are configured in the metadata like so::
{
"databases": {
"database1": {
"tables": {
"example_table": {
"units": {
"column1": "metres",
"column2": "Hz"
}
}
}
}
}
}
Units are interpreted using Pint_, and you can see the full list of available units in
2018-04-14 14:08:20 +00:00
Pint's `unit registry`_ . You can also add `custom units`_ to the metadata, which will be
2018-04-14 11:27:06 +00:00
registered with Pint::
2018-04-22 17:51:43 +00:00
2018-04-14 11:27:06 +00:00
{
"custom_units": [
"decibel = [] = dB"
]
}
2018-04-14 10:16:09 +00:00
.. _Pint: https://pint.readthedocs.io/
.. _unit registry: https://github.com/hgrecco/pint/blob/master/pint/default_en.txt
2018-04-14 14:08:20 +00:00
.. _custom units: http://pint.readthedocs.io/en/latest/defining.html
2018-04-14 10:16:09 +00:00
2018-04-09 04:58:25 +00:00
Setting which columns can be used for sorting
---------------------------------------------
Datasette allows any column to be used for sorting by default. If you need to
control which columns are available for sorting you can do so using the optional
`` sortable_columns `` key::
{
"databases": {
"database1": {
"tables": {
"example_table": {
"sortable_columns": [
"height",
"weight"
]
}
}
}
}
}
This will restrict sorting of `` example_table `` to just the `` height `` and
`` weight `` columns.
You can also disable sorting entirely by setting `` "sortable_columns": [] ``
2018-08-06 00:29:23 +00:00
By default, database views in Datasette do not support sorting. You can use `` sortable_columns `` to enable specific sort orders for a view called `` name_of_view `` in the database `` my_database `` like so::
2018-08-28 09:56:34 +00:00
{
"databases": {
"my_database": {
"tables": {
"name_of_view": {
"sortable_columns": [
"clicks",
"impressions"
]
}
2018-08-06 00:29:23 +00:00
}
}
}
}
?_labels= and ?_label=COL to expand foreign keys in JSON/CSV
These new querystring arguments can be used to request expanded foreign keys
in both JSON and CSV formats.
?_labels=on turns on expansions for ALL foreign key columns
?_label=COLUMN1&_label=COLUMN2 can be used to pick specific columns to expand
e.g. `Street_Tree_List.json?_label=qSpecies&_label=qLegalStatus`
{
"rowid": 233,
"TreeID": 121240,
"qLegalStatus": {
"value" 2,
"label": "Private"
}
"qSpecies": {
"value": 16,
"label": "Sycamore"
}
"qAddress": "91 Commonwealth Ave",
...
}
The labels option also works for the HTML and CSV views.
HTML defaults to `?_labels=on`, so if you pass `?_labels=off` you can disable
foreign key expansion entirely - or you can use `?_label=COLUMN` to request
just specific columns.
If you expand labels on CSV you get additional columns in the output:
`/Street_Tree_List.csv?_label=qLegalStatus`
rowid,TreeID,qLegalStatus,qLegalStatus_label...
1,141565,1,Permitted Site...
2,232565,2,Undocumented...
I also refactored the existing foreign key expansion code.
Closes #233. Refs #266.
2018-06-16 22:18:57 +00:00
.. _label_columns:
2018-06-18 03:21:02 +00:00
2018-04-22 17:51:43 +00:00
Specifying the label column for a table
---------------------------------------
Datasette's HTML interface attempts to display foreign key references as
labelled hyperlinks. By default, it looks for referenced tables that only have
two columns: a primary key column and one other. It assumes that the second
column should be used as the link label.
If your table has more than two columns you can specify which column should be
used for the link label with the `` label_column `` property::
{
"databases": {
"database1": {
"tables": {
"example_table": {
"label_column": "title"
}
}
}
}
}
2018-04-26 03:42:57 +00:00
Hiding tables
-------------
You can hide tables from the database listing view (in the same way that FTS and
Spatialite tables are automatically hidden) using `` "hidden": true `` ::
{
"databases": {
"database1": {
"tables": {
"example_table": {
"hidden": true
}
}
}
}
}
2017-12-07 17:19:35 +00:00
Generating a metadata skeleton
------------------------------
Tracking down the names of all of your databases and tables and formatting them
as JSON can be a little tedious, so Datasette provides a tool to help you
generate a "skeleton" JSON file::
datasette skeleton database1.db database2.db
This will create a `` metadata.json `` file looking something like this::
{
"title": null,
"description": null,
"description_html": null,
"license": null,
"license_url": null,
"source": null,
"source_url": null,
"databases": {
"database1": {
"title": null,
"description": null,
"description_html": null,
"license": null,
"license_url": null,
"source": null,
"source_url": null,
"queries": {},
"tables": {
"example_table": {
"title": null,
"description": null,
"description_html": null,
"license": null,
"license_url": null,
"source": null,
2018-04-14 10:16:09 +00:00
"source_url": null,
"units": {}
2017-12-07 17:19:35 +00:00
}
}
},
"database2": ...
}
}
You can replace any of the `` null `` values with a JSON string to populate that
piece of metadata.