Support column descriptions in metadata.json

[simonw]

Could look something like this:

{
    "title": "Five Thirty Eight",
    "license": "CC Attribution 4.0 License",
    "license_url": "https://creativecommons.org/licenses/by/4.0/",
    "source": "fivethirtyeight/data on GitHub",
    "source_url": "https://github.com/fivethirtyeight/data",
    "databases": {
        "fivethirtyeight": {
            "tables": {
                "mueller-polls/mueller-approval-polls": {
                    "description_html": "<p>....</p>",
                    "columns": {
                        "name_of_column": "column_description goes here"
}

[simonw]

Could display these as tooltips on icons something like this (from the experimental datasette-inspect-columns plugin):

This would need to take accessibility into account, and would need a different display for the mobile web layout. Need to consider how it will interact with the column menu suggested in #690.

[simonw]

Easiest solution: if you provide column metadata it gets displayed above the table, something like on https://fivethirtyeight.datasettes.com/fivethirtyeight/antiquities-act%2Factions_under_antiquities_act

HTML title= tooltips are also added to the table headers, which won't be visible on touch devices but that's OK because the information is visible on the page already.

[simonw]

Is columns the right key for this in the table metadata block? I might want to use that for initial values for ?_col= in #615.

Alternative names:

• column_descriptions
• column_info

[simonw]

This will also benefit from the metadata plugin hook: #860

[zaneselvans]

Are there common patterns for storing column-based metadata inside SQLite itself? I know Postgres allows "comment" fields, which this is kind of trying to replicate. Should the units and description and possibly other per-column metadata fields be combined into a single (tabular?) structure, that would be displayed above the data on the table / query results page?

[simonw]

SQLite does let you add comments in your CREATE TABLE statements:

CREATE TABLE something (
    id integer primary key, -- integer primary key
    created text -- created date as ISO datetime
);

But the only mechanism for reading those back is to retrieve that CREATE TABLE block of SQL from the sqlite_master table and run a parser against it.

I've so far resisted adding a SQL syntax parser to Datasette for complexity reasons - though I'm increasingly thinking I'll need to do it at some point.

I think I'll leave this to plugins. I'm definitely going to build a plugin that lets you store metadata for tables and columns in a SQLite database table, which will then support interactively editing metadata through a UI.

A plugin which extracts column comments from the SQLite CREATE TABLE comments would be feasible too, if I design the plugin hooks well.

[zaneselvans]

Are you thinking that those metadata tables would be added to the SQLite DB by Datasette, when you tell it to wrap up the database, with the metadata coming from the metadata.json? Would it be easy to allow the prepopulation of those tables in the database itself? We've been struggling with the best way to make sure that the data is always accompanied by metadata, and baking it all into the database itself would be nice, since then we wouldn't need to worry about separately distributing different files in different contexts.

[simonw]

My idea is that if you installed my proposed plugin you wouldn't need metadata.json at all - your metadata would instead live in a table in the connected SQLite database files - either one table per database (so the metadata can live in the same place as the data) or maybe also in a dedicated separate database file, for if you want to add metadata to an otherwise read-only database.

The plugin would then provide a UI for editing that metadata - maybe by configuring some writable canned queries or maybe something more custom than that. Or you could edit the metadata by manually editing the SQLite database file (or loading data into it using a tool like yaml-to-sqlite).

[mroswell]

I like this idea. Though it might be nice to have some kind of automated system from database to file, so that developers could easily track diffs.