Documentation: https://docs.datasette.io/en/latest/metadata.html#column-descriptions

Live demo: https://latest.datasette.io/fixtures/roadside_attractions

Codecov Report

Merging #1430 (9419947) into main (b1fed48) will increase coverage by 0.00%. The diff coverage is 100.00%.

```diff @@ Coverage Diff @@

main #1430 +/-

======================================= Coverage 91.71% 91.71%
======================================= Files 34 34
Lines 4417 4418 +1
======================================= + Hits 4051 4052 +1
Misses 366 366
```

| Impacted Files | Coverage Δ | | |---|---|---| | datasette/views/table.py | 96.00% <100.00%> (+<0.01%) | :arrow_up: |

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update b1fed48...9419947. Read the comment docs.

I like this enough that I'm going to ship it as an alpha and try it out on a couple of live projects.

Prototype with a <dl>:

```diff diff --git a/datasette/static/app.css b/datasette/static/app.css index c6be1e9..bf068fd 100644 --- a/datasette/static/app.css +++ b/datasette/static/app.css @@ -836,6 +841,16 @@ svg.dropdown-menu-icon { background-repeat: no-repeat; }

+dl.column-descriptions dt { + font-weight: bold; +} +dl.column-descriptions dd { + padding-left: 1.5em; + white-space: pre-wrap; + line-height: 1.1em; + color: #666; +} + .anim-scale-in { animation-name: scale-in; animation-duration: 0.15s; diff --git a/datasette/templates/table.html b/datasette/templates/table.html index 211352b..466e8a4 100644 --- a/datasette/templates/table.html +++ b/datasette/templates/table.html @@ -51,6 +51,14 @@

{% block description_source_license %}{% include "_description_source_license.html" %}{% endblock %}

+{% if metadata.columns %} +<dl class="column-descriptions"> + {% for column_name, column_description in metadata.columns.items() %} + <dt>{{ column_name }}</dt><dd>{{ column_description }}</dd> + {% endfor %} +</dl> +{% endif %} + {% if filtered_table_rows_count or human_description_en %}

{% if filtered_table_rows_count or filtered_table_rows_count == 0 %}{{ "{:,}".format(filtered_table_rows_count) }} row{% if filtered_table_rows_count == 1 %}{% else %}s{% endif %}{% endif %} {% if human_description_en %}{{ human_description_en }}{% endif %} ```

This looks awesome. We'll definitely make extensive use of this feature!

On Thu, Aug 12, 2021 at 5:52 PM Simon Willison @.***> wrote:

I like this. Need to solve for mobile though where the cog menu isn't visible - I think I'll do that with a definition list at the top of the page.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/simonw/datasette/issues/942#issuecomment-898022235, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAERSNYEF6QRZO2HRJGRIWDT4RGDFANCNFSM4QEC6ATA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email .

-- Zane A. Selvans, PhD Chief Data Wrangler Catalyst Cooperative https://catalyst.coop @.*** Signal/WhatsApp/SMS: +1 720 443 1363 Twitter: @ZaneSelvans https://twitter.com/ZaneSelvans PGP https://www.gnupg.org/: 0x64F7B56F3A127B04

I like this. Need to solve for mobile though where the cog menu isn't visible - I think I'll do that with a definition list at the top of the page.

Prototype:

``diff diff --git a/datasette/static/app.css b/datasette/static/app.css index c6be1e9..5ca64cb 100644 --- a/datasette/static/app.css +++ b/datasette/static/app.css @@ -784,9 +784,14 @@ svg.dropdown-menu-icon { font-size: 0.7em; color: #666; margin: 0; - padding: 0; padding: 4px 8px 4px 8px; } +.dropdown-menu .dropdown-column-description { + margin: 0; + color: #666; + padding: 4px 8px 4px 8px; + max-width: 20em; +} .dropdown-menu li { border-bottom: 1px solid #ccc; } diff --git a/datasette/static/table.js b/datasette/static/table.js index 991346d..a903112 100644 --- a/datasette/static/table.js +++ b/datasette/static/table.js @@ -9,6 +9,7 @@ var DROPDOWN_HTML =

var DROPDOWN_ICON_SVG = <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> @@ -166,6 +167,14 @@ var DROPDOWN_ICON_SVG =<svg xmlns="http://www.w3.org/2000/svg" width="14" heig } else { columnTypeP.style.display = "none"; } + + var columnDescriptionP = menu.querySelector(".dropdown-column-description"); + if (th.dataset.columnDescription) { + columnDescriptionP.innerText = th.dataset.columnDescription; + columnDescriptionP.style.display = 'block'; + } else { + columnDescriptionP.style.display = 'none'; + } menu.style.position = "absolute"; menu.style.top = menuTop + 6 + "px"; menu.style.left = menuLeft + "px"; diff --git a/datasette/templates/table.html b/datasette/templates/_table.html index d765937..649f517 100644 --- a/datasette/templates/_table.html +++ b/datasette/templates/_table.html @@ -4,7 +4,7 @@ <thead> <tr> {% for column in display_columns %} - <th class="col-{{ column.name|to_css_class }}" scope="col" data-column="{{ column.name }}" data-column-type="{{ column.type }}" data-column-not-null="{{ column.notnull }}" data-is-pk="{% if column.is_pk %}1{% else %}0{% endif %}"> + <th {% if column.description %}data-column-description="{{ column.description }}" {% endif %}class="col-{{ column.name|to_css_class }}" scope="col" data-column="{{ column.name }}" data-column-type="{{ column.type }}" data-column-not-null="{{ column.notnull }}" data-is-pk="{% if column.is_pk %}1{% else %}0{% endif %}"> {% if not column.sortable %} {{ column.name }} {% else %} diff --git a/datasette/views/table.py b/datasette/views/table.py index 456d806..486a613 100644 --- a/datasette/views/table.py +++ b/datasette/views/table.py @@ -125,6 +125,7 @@ class RowTableShared(DataView): """Returns columns, rows for specified table - including fancy foreign key treatment""" db = self.ds.databases[database] table_metadata = self.ds.table_metadata(database, table) + column_descriptions = table_metadata.get("columns") or {} column_details = {col.name: col for col in await db.table_column_details(table)} sortable_columns = await self.sortable_columns_for_table(database, table, True) pks = await db.primary_keys(table) @@ -147,6 +148,7 @@ class RowTableShared(DataView): "is_pk": r[0] in pks_for_display, "type": type, "notnull": notnull, + "description": column_descriptions.get(r[0]), } )

```

I'm going with "columns": {"name-of-column": "description-of-column"}.

If I decide to make "col" and "nocol" available in metadata I'll use those as the keys in the metadata, for consistency with the existing query string parameters.

I'm OK with having both "columns": ... and "col": ... keys in the metadata, even though they could be a tiny bit confusing without the documentation.

Maybe something like this:

Next page - 100 per page (show 1,000 per page)

Actually, I forgot to include the bib_pub_year in the extract ...

But also, I tried again with empty string values instead of NULL values and it seems to place the foreign key properly / correctly...

```python3 sql = """\ INSERT INTO "circulation_info" ("item_id", "bib_title", "bib_creator", "bib_format", "bib_pub_year", "checkout_date") VALUES (1, "title one", "creator one", "Book", 2018, "2021-08-12 00:01"), (2, "title two", "creator one", "Book", 2019, "2021-08-12 00:02"), (3, "title three", "", "DVD", 2020, "2021-08-12 00:03"), (4, "title four", "", "DVD", "", "2021-08-12 00:04"), (5, "title five", "", "DVD", "", "2021-08-12 00:05") """

with sqlite3.connect('test_bib_2.db') as con: con.execute(sql) ```

python3 db["circulation_info"].extract( [ "bib_title", "bib_creator", "bib_format", "bib_pub_year" ], table="bib_info", fk_column="bib_info_id" )

``` {'id': 1, 'item_id': 1, 'bib_info_id': 1, 'bib_pub_year': 2018, 'checkout_date': '2021-08-12 00:01'} {'id': 2, 'item_id': 2, 'bib_info_id': 2, 'bib_pub_year': 2019, 'checkout_date': '2021-08-12 00:02'} {'id': 3, 'item_id': 3, 'bib_info_id': 3, 'bib_pub_year': 2020, 'checkout_date': '2021-08-12 00:03'} {'id': 4, 'item_id': 4, 'bib_info_id': 4, 'bib_pub_year': '', 'checkout_date': '2021-08-12 00:04'} {'id': 5, 'item_id': 5, 'bib_info_id': 5, 'bib_pub_year': '', 'checkout_date': '2021-08-12 00:05'}

{'id': 1, 'bib_title': 'title one', 'bib_creator': 'creator one', 'bib_format': 'Book'} {'id': 2, 'bib_title': 'title two', 'bib_creator': 'creator one', 'bib_format': 'Book'} {'id': 3, 'bib_title': 'title three', 'bib_creator': '', 'bib_format': 'DVD'} {'id': 4, 'bib_title': 'title four', 'bib_creator': '', 'bib_format': 'DVD'} {'id': 5, 'bib_title': 'title five', 'bib_creator': '', 'bib_format': 'DVD'} ```

I think I ran into an issue that's perhaps related with extract()

I have a case where I want to create a lookup table for all the related title data where there are possibly multiple null values in the related columns .... ```python3 sql = """\ INSERT INTO "circulation_info" ("item_id", "bib_title", "bib_creator", "bib_format", "bib_pub_year", "checkout_date") VALUES (1, "title one", "creator one", "Book", 2018, "2021-08-12 00:01"), (2, "title two", "creator one", "Book", 2019, "2021-08-12 00:02"), (3, "title three", NULL, "DVD", 2020, "2021-08-12 00:03"), (4, "title four", NULL, "DVD", NULL, "2021-08-12 00:04"), (5, "title five", NULL, "DVD", NULL, "2021-08-12 00:05") """

with sqlite3.connect('test_bib.db') as con: con.execute(sql) ```

when I run the extract() method ...

```python3 db["circulation_info"].extract( [ "bib_title", "bib_creator", "bib_format"
], table="bib_info", fk_column="bib_info_id" )

db = sqlite_utils.Database("test_bib.db")

for row in db["circulation_info"].rows: print(row)

print("\n---\n")

for row in db["bib_info"].rows: print(row) ```

results in this .. ``` {'id': 1, 'item_id': 1, 'bib_info_id': 1, 'bib_pub_year': 2018, 'checkout_date': '2021-08-12 00:01'} {'id': 2, 'item_id': 2, 'bib_info_id': 2, 'bib_pub_year': 2019, 'checkout_date': '2021-08-12 00:02'} {'id': 3, 'item_id': 3, 'bib_info_id': None, 'bib_pub_year': 2020, 'checkout_date': '2021-08-12 00:03'} {'id': 4, 'item_id': 4, 'bib_info_id': None, 'bib_pub_year': None, 'checkout_date': '2021-08-12 00:04'} {'id': 5, 'item_id': 5, 'bib_info_id': None, 'bib_pub_year': None, 'checkout_date': '2021-08-12 00:05'}

{'id': 1, 'bib_title': 'title one', 'bib_creator': 'creator one', 'bib_format': 'Book'} {'id': 2, 'bib_title': 'title two', 'bib_creator': 'creator one', 'bib_format': 'Book'} {'id': 3, 'bib_title': 'title three', 'bib_creator': None, 'bib_format': 'DVD'} {'id': 4, 'bib_title': 'title four', 'bib_creator': None, 'bib_format': 'DVD'} {'id': 5, 'bib_title': 'title five', 'bib_creator': None, 'bib_format': 'DVD'} ```

Seems like it's correctly generating the row data for those lookups, but it's not correctly updating the foreign key back to the primary table? Looks like it just results in a NULL value in that original table.

Any ideas on why? Thanks again!