Clarified relationship between metadata and _facet= facets, updated docs - refs @255

docs/facets.rst

@@ -3,8 +3,6 @@
 Facets
 ======
 
-This feature is currently under development, see `#255 <https://github.com/simonw/datasette/issues/255>`_
-
 Datasette facets can be used to add a faceted browse interface to any Datasette table. With facets, tables are displayed along with a summary showing the most common values in specified columns. These values can be selected to further filter the table.
 
 Facets can be specified in two ways: using queryset parameters, or in ``metadata.json`` configuration for the table.
@@ -18,43 +16,72 @@ To turn on faceting for specific columns on a Datasette table view, add one or m
 
 This works for both the HTML interface and the ``.json`` view. When enabled, facets will cause a ``facet_results`` block to be added to the JSON output, looking something like this::
 
-    "facet_results": {
-      "state": [
-        {
-          "value": "CA",
-          "count": 10,
-          "selected": false,
-          "toggle_url": "http://...&state=CA"
-        },
-        {
-          "value": "MI",
-          "count": 4,
-          "selected": false,
-          "toggle_url": "http://...&state=MI"
-        }
-      ],
-      "city": [
-        {
-          "value": "San Francisco",
-          "count": 6,
-          "selected": false,
-          "toggle_url": "http://...=San+Francisco"
-        },
-        {
-          "value": "Detroit",
-          "count": 4,
-          "selected": false,
-          "toggle_url": "http://...&city=Detroit"
-        },
-        {
-          "value": "Los Angeles",
-          "count": 4,
-          "selected": false,
-          "toggle_url": "http://...=Los+Angeles"
-        }
-      ]
+    {
+      "state": {
+        "name": "state",
+        "results": [
+          {
+            "value": "CA",
+            "label": "CA",
+            "count": 10,
+            "toggle_url": "http://...?_facet=city_id&_facet=state&state=CA",
+            "selected": false
+          },
+          {
+            "value": "MI",
+            "label": "MI",
+            "count": 4,
+            "toggle_url": "http://...?_facet=city_id&_facet=state&state=MI",
+            "selected": false
+          },
+          {
+            "value": "MC",
+            "label": "MC",
+            "count": 1,
+            "toggle_url": "http://...?_facet=city_id&_facet=state&state=MC",
+            "selected": false
+          }
+        ],
+        "truncated": false
+      }
+      "city_id": {
+        "name": "city_id",
+        "results": [
+          {
+            "value": 1,
+            "label": "San Francisco",
+            "count": 6,
+            "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=1",
+            "selected": false
+          },
+          {
+            "value": 2,
+            "label": "Los Angeles",
+            "count": 4,
+            "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=2",
+            "selected": false
+          },
+          {
+            "value": 3,
+            "label": "Detroit",
+            "count": 4,
+            "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=3",
+            "selected": false
+          },
+          {
+            "value": 4,
+            "label": "Memnonia",
+            "count": 1,
+            "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=4",
+            "selected": false
+          }
+        ],
+        "truncated": false
+      }
     }
 
+If Datasette detects that a column is a foreign key, the ``"label"`` proper will be automatically derived from the detected label column on the referenced table.
+
 Facets in metadata.json
 -----------------------
 
@@ -73,3 +100,19 @@ Here's an example that turns on faceting by default for the ``qLegalStatus`` col
             }
         }
     }
+
+Facets defined in this way will always be shown in the interface and returned in the API, regardless of the ``_facet`` arguments passed to the view.
+
+Suggested facets
+----------------
+
+Datasette's table UI will suggest facets for the user to apply, based on the following criteria:
+
+For the currently filtered data are there any columns which, if applied as a facet...
+
+* Will return 20 or less unique options
+* Will return more than one unique option
+* Will return less unique options than the total number of filtered rows
+* And the query used to evaluate this criteria can be completed in under 20ms
+
+That last point is particularly important: Datasette runs a query for every column that is displayed on a page, which could get expensive - so to avoid slow load times it sets a time limit of just 20ms for each of those queries. This means suggested facets are unlikely to appear for tables with millions of records in them.