From 96aac7f9e94d94243a7ee524d0ad25501ec98f72 Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Wed, 16 May 2018 08:45:12 -0700 Subject: [PATCH] Facet documentation tweaks --- docs/facets.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/facets.rst b/docs/facets.rst index 47da6e9d..45bb4292 100644 --- a/docs/facets.rst +++ b/docs/facets.rst @@ -3,18 +3,18 @@ Facets ====== -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. +Datasette facets can be used to add a faceted browse interface to any database 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. .. image:: facets.png -Facets can be specified in two ways: using queryset parameters, or in ``metadata.json`` configuration for the table. +Facets can be specified in two ways: using querystring parameters, or in ``metadata.json`` configuration for the table. Facets in querystrings ---------------------- -To turn on faceting for specific columns on a Datasette table view, add one or more ``_facet=COLUMN`` parameters to the URL. For example, if you want to turn on facets for the ``city`` and ``state`` columns, construct a URL that looks like this:: +To turn on faceting for specific columns on a Datasette table view, add one or more ``_facet=COLUMN`` parameters to the URL. For example, if you want to turn on facets for the ``city_id`` and ``state`` columns, construct a URL that looks like this:: - /dbname/tablename?_facet=state&_facet=city + /dbname/tablename?_facet=state&_facet=city_id 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:: @@ -92,15 +92,15 @@ You can turn facets on by default for specific tables by adding them to a ``"fac Here's an example that turns on faceting by default for the ``qLegalStatus`` column in the ``Street_Tree_List`` table in the ``sf-trees`` database:: { - "databases": { - "sf-trees": { - "tables": { - "Street_Tree_List": { - "facets": ["qLegalStatus"] - } - } + "databases": { + "sf-trees": { + "tables": { + "Street_Tree_List": { + "facets": ["qLegalStatus"] } + } } + } } 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.