From 63d73a806fe0104b43d7debbe84026542173c432 Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Tue, 17 Mar 2026 08:47:04 -0700 Subject: [PATCH] Move table configuration docs from metadata.rst to configuration.rst (#2668) https://claude.ai/code/session_01UqboRB5Wt52BKPhxexUBEn --- docs/changelog.rst | 10 +- docs/configuration.rst | 575 ++++++++++++++++++++++++++++++++++++++ docs/facets.rst | 30 +- docs/full_text_search.rst | 10 +- docs/internals.rst | 4 +- docs/json_api.rst | 2 +- docs/metadata.rst | 381 +------------------------ docs/pages.rst | 2 +- 8 files changed, 613 insertions(+), 401 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 2c9b7170..71d63e33 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -934,7 +934,7 @@ Other small fixes 0.59 (2021-10-14) ----------------- -- Columns can now have associated metadata descriptions in ``metadata.json``, see :ref:`metadata_column_descriptions`. (:issue:`942`) +- Columns can now have associated metadata descriptions in ``metadata.json``, see :ref:`table_configuration_columns`. (:issue:`942`) - New :ref:`register_commands() ` plugin hook allows plugins to register additional Datasette CLI commands, e.g. ``datasette mycommand file.db``. (:issue:`1449`) - Adding ``?_facet_size=max`` to a table page now shows the number of unique values in each facet. (:issue:`1423`) - Upgraded dependency `httpx 0.20 `__ - the undocumented ``allow_redirects=`` parameter to :ref:`internals_datasette_client` is now ``follow_redirects=``, and defaults to ``False`` where it previously defaulted to ``True``. (:issue:`1488`) @@ -1624,7 +1624,7 @@ The main focus of this release is a major upgrade to the :ref:`plugin_register_o * Redesign of :ref:`plugin_register_output_renderer` to provide more context to the render callback and support an optional ``"can_render"`` callback that controls if a suggested link to the output format is provided. (:issue:`581`, :issue:`770`) * Visually distinguish float and integer columns - useful for figuring out why order-by-column might be returning unexpected results. (:issue:`729`) * The :ref:`internals_request`, which is passed to several plugin hooks, is now documented. (:issue:`706`) -* New ``metadata.json`` option for setting a custom default page size for specific tables and views, see :ref:`metadata_page_size`. (:issue:`751`) +* New ``metadata.json`` option for setting a custom default page size for specific tables and views, see :ref:`table_configuration_size`. (:issue:`751`) * Canned queries can now be configured with a default URL fragment hash, useful when working with plugins such as `datasette-vega `__, see :ref:`canned_queries_options`. (:issue:`706`) * Fixed a bug in ``datasette publish`` when running on operating systems where the ``/tmp`` directory lives in a different volume, using a backport of the Python 3.8 ``shutil.copytree()`` function. (:issue:`744`) * Every plugin hook is now covered by the unit tests, and a new unit test checks that each plugin hook has at least one corresponding test. (:issue:`771`, :issue:`773`) @@ -1688,7 +1688,7 @@ Also in this release: ----------------- * New :ref:`setting_base_url` configuration setting for serving up the correct links while running Datasette under a different URL prefix. (:issue:`394`) -* New metadata settings ``"sort"`` and ``"sort_desc"`` for setting the default sort order for a table. See :ref:`metadata_default_sort`. (:issue:`702`) +* New metadata settings ``"sort"`` and ``"sort_desc"`` for setting the default sort order for a table. See :ref:`table_configuration_sort`. (:issue:`702`) * Sort direction arrow now displays by default on the primary key. This means you only have to click once (not twice) to sort in reverse order. (:issue:`677`) * New ``await Request(scope, receive).post_vars()`` method for accessing POST form variables. (:issue:`700`) * :ref:`plugin_hooks` documentation now links to example uses of each plugin. (:issue:`709`) @@ -2123,7 +2123,7 @@ New plugin hooks, improved database view support and an easier way to use more r - New ``render_cell`` plugin hook. Plugins can now customize how values are displayed in the HTML tables produced by Datasette's browsable interface. `datasette-json-html `__ and `datasette-render-images `__ are two new plugins that use this hook. :ref:`render_cell documentation `. Closes :issue:`352` - New ``extra_body_script`` plugin hook, enabling plugins to provide additional JavaScript that should be added to the page footer. :ref:`extra_body_script documentation `. - ``extra_css_urls`` and ``extra_js_urls`` hooks now take additional optional parameters, allowing them to be more selective about which pages they apply to. :ref:`Documentation `. -- You can now use the :ref:`sortable_columns metadata setting ` to explicitly enable sort-by-column in the interface for database views, as well as for specific tables. +- You can now use the :ref:`sortable_columns metadata setting ` to explicitly enable sort-by-column in the interface for database views, as well as for specific tables. - The new ``fts_table`` and ``fts_pk`` metadata settings can now be used to :ref:`explicitly configure full-text search for a table or a view `, even if that table is not directly coupled to the SQLite FTS feature in the database schema itself. - Datasette will now use `pysqlite3 `__ in place of the standard library ``sqlite3`` module if it has been installed in the current environment. This makes it much easier to run Datasette against a more recent version of SQLite, including the just-released `SQLite 3.25.0 `__ which adds window function support. More details on how to use this in :issue:`360` - New mechanism that allows :ref:`plugin configuration options ` to be set using ``metadata.json``. @@ -2208,7 +2208,7 @@ Foreign key expansions ~~~~~~~~~~~~~~~~~~~~~~ When Datasette detects a foreign key reference it attempts to resolve a label -for that reference (automatically or using the :ref:`label_columns` metadata +for that reference (automatically or using the :ref:`table_configuration_label_column` metadata option) so it can display a link to the associated row. This expansion is now also available for JSON and CSV representations of the diff --git a/docs/configuration.rst b/docs/configuration.rst index 425024da..b61c3692 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -634,5 +634,580 @@ Will produce this HTML: +.. _configuration_reference_table: + +Table configuration +~~~~~~~~~~~~~~~~~~~ + +Datasette supports a number of table-level configuration options inside ``datasette.yaml``. These are placed under ``databases.database_name.tables.table_name``. + +.. _table_configuration_sort: + +``sort`` / ``sort_desc`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +By default Datasette tables are sorted by primary key. You can set a default sort order for a specific table using the ``sort`` or ``sort_desc`` properties: + +.. [[[cog + from metadata_doc import config_example + import textwrap + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + sort: created + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + sort: created + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "sort": "created" + } + } + } + } + } +.. [[[end]]] + +Or use ``sort_desc`` to sort in descending order: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + sort_desc: created + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + sort_desc: created + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "sort_desc": "created" + } + } + } + } + } +.. [[[end]]] + +.. _table_configuration_size: + +``size`` +^^^^^^^^ + +Datasette defaults to displaying 100 rows per page, for both tables and views. You can change this on a per-table or per-view basis using the ``size`` key: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + size: 10 + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + size: 10 + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "size": 10 + } + } + } + } + } +.. [[[end]]] + +This size can still be over-ridden by passing e.g. ``?_size=50`` in the query string. + +.. _table_configuration_sortable_columns: + +``sortable_columns`` +^^^^^^^^^^^^^^^^^^^^ + +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 ``sortable_columns``: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + sortable_columns: + - height + - weight + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + sortable_columns: + - height + - weight + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "sortable_columns": [ + "height", + "weight" + ] + } + } + } + } + } +.. [[[end]]] + +This will restrict sorting of ``example_table`` to just the ``height`` and ``weight`` columns. + +You can also disable sorting entirely by setting ``"sortable_columns": []`` + +You can use ``sortable_columns`` to enable specific sort orders for a view called ``name_of_view`` in the database ``my_database`` like so: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + my_database: + tables: + name_of_view: + sortable_columns: + - clicks + - impressions + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + my_database: + tables: + name_of_view: + sortable_columns: + - clicks + - impressions + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "my_database": { + "tables": { + "name_of_view": { + "sortable_columns": [ + "clicks", + "impressions" + ] + } + } + } + } + } +.. [[[end]]] + +.. _table_configuration_label_column: + +``label_column`` +^^^^^^^^^^^^^^^^ + +Datasette's HTML interface attempts to display foreign key references as labelled hyperlinks. By default, it automatically detects a label column using the following rules (in order): + +1. If there is exactly one unique text column, use that. +2. If there is a column called ``name`` or ``title`` (case-insensitive), use that. +3. If the table has only two columns - a primary key and one other - use the non-primary-key column. + +You can override this automatic detection by specifying which column should be used for the link label with the ``label_column`` property: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + label_column: title + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + label_column: title + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "label_column": "title" + } + } + } + } + } +.. [[[end]]] + +.. _table_configuration_hidden: + +``hidden`` +^^^^^^^^^^ + +You can hide tables from the database listing view (in the same way that FTS and SpatiaLite tables are automatically hidden) using ``"hidden": true``: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + hidden: true + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + hidden: true + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "hidden": true + } + } + } + } + } +.. [[[end]]] + +.. _table_configuration_facets: + +``facets`` / ``facet_size`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can turn on facets by default for specific tables. ``facet_size`` controls how many unique values are shown for each facet on that table (the default is controlled by the :ref:`setting_default_facet_size` setting). See :ref:`facets_metadata` for full details. + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + sf-trees: + tables: + Street_Tree_List: + facets: + - qLegalStatus + facet_size: 10 + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + sf-trees: + tables: + Street_Tree_List: + facets: + - qLegalStatus + facet_size: 10 + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "sf-trees": { + "tables": { + "Street_Tree_List": { + "facets": [ + "qLegalStatus" + ], + "facet_size": 10 + } + } + } + } + } +.. [[[end]]] + +You can also specify :ref:`array ` or :ref:`date ` facets using JSON objects with a single key of ``array`` or ``date``: + +.. code-block:: yaml + + facets: + - array: tags + - date: created + +.. _table_configuration_fts: + +``fts_table`` / ``fts_pk`` / ``searchmode`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These configure :ref:`full-text search ` for a table or view. See :ref:`full_text_search_table_or_view` for full details. + +``fts_table`` specifies which FTS table to use for search. ``fts_pk`` sets the primary key column if it is something other than ``rowid``. ``searchmode`` can be set to ``"raw"`` to enable `SQLite advanced search operators `__. + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + russian-ads: + tables: + display_ads: + fts_table: ads_fts + fts_pk: id + searchmode: raw + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + russian-ads: + tables: + display_ads: + fts_table: ads_fts + fts_pk: id + searchmode: raw + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "russian-ads": { + "tables": { + "display_ads": { + "fts_table": "ads_fts", + "fts_pk": "id", + "searchmode": "raw" + } + } + } + } + } +.. [[[end]]] + +.. _table_configuration_column_types: + +``column_types`` +^^^^^^^^^^^^^^^^ + +You can assign semantic column types to columns, which affect how values are rendered, validated, and transformed. Built-in column types include ``url``, ``email``, and ``json``. Plugins can register additional column types using the :ref:`register_column_types ` plugin hook. + +The simplest form maps column names to type name strings: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + column_types: + website: url + contact: email + extra_data: json + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + column_types: + website: url + contact: email + extra_data: json + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "column_types": { + "website": "url", + "contact": "email", + "extra_data": "json" + } + } + } + } + } + } +.. [[[end]]] + +For column types that accept additional configuration, use an object with ``type`` and ``config`` keys: + +.. [[[cog + config_example(cog, textwrap.dedent( + """ + databases: + mydatabase: + tables: + example_table: + column_types: + website: + type: url + config: + prefix: "https://" + """).strip() + ) +.. ]]] + +.. tab:: datasette.yaml + + .. code-block:: yaml + + databases: + mydatabase: + tables: + example_table: + column_types: + website: + type: url + config: + prefix: "https://" + +.. tab:: datasette.json + + .. code-block:: json + + { + "databases": { + "mydatabase": { + "tables": { + "example_table": { + "column_types": { + "website": { + "type": "url", + "config": { + "prefix": "https://" + } + } + } + } + } + } + } + } +.. [[[end]]] diff --git a/docs/facets.rst b/docs/facets.rst index 2a135b69..960ac03a 100644 --- a/docs/facets.rst +++ b/docs/facets.rst @@ -98,16 +98,16 @@ You can increase this on an individual page by adding ``?_facet_size=100`` to th .. _facets_metadata: -Facets in metadata ------------------- +Facets in configuration +----------------------- -You can turn facets on by default for specific tables by adding them to a ``"facets"`` key in a Datasette :ref:`metadata` file. +You can turn facets on by default for specific tables by adding a ``"facets"`` key to the table configuration in ``datasette.yaml``. See also the :ref:`table configuration reference ` for a quick overview. 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: .. [[[cog - from metadata_doc import metadata_example - metadata_example(cog, { + from metadata_doc import config_example + config_example(cog, { "databases": { "sf-trees": { "tables": { @@ -120,7 +120,7 @@ Here's an example that turns on faceting by default for the ``qLegalStatus`` col }) .. ]]] -.. tab:: metadata.yaml +.. tab:: datasette.yaml .. code-block:: yaml @@ -132,7 +132,7 @@ Here's an example that turns on faceting by default for the ``qLegalStatus`` col - qLegalStatus -.. tab:: metadata.json +.. tab:: datasette.json .. code-block:: json @@ -153,12 +153,12 @@ 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. -Facets defined in metadata will be displayed in the order they are listed in the configuration. Any additional facets added via query string parameters (e.g. ``?_facet=column_name``) will appear after the metadata-defined facets, sorted by the number of unique values. +Facets defined in configuration will be displayed in the order they are listed. Any additional facets added via query string parameters (e.g. ``?_facet=column_name``) will appear after the configured facets, sorted by the number of unique values. -You can specify :ref:`array ` or :ref:`date ` facets in metadata using JSON objects with a single key of ``array`` or ``date`` and a value specifying the column, like this: +You can specify :ref:`array ` or :ref:`date ` facets using JSON objects with a single key of ``array`` or ``date`` and a value specifying the column, like this: .. [[[cog - metadata_example(cog, { + config_example(cog, { "facets": [ {"array": "tags"}, {"date": "created"} @@ -166,7 +166,7 @@ You can specify :ref:`array ` or :ref:`date }) .. ]]] -.. tab:: metadata.yaml +.. tab:: datasette.yaml .. code-block:: yaml @@ -175,7 +175,7 @@ You can specify :ref:`array ` or :ref:`date - date: created -.. tab:: metadata.json +.. tab:: datasette.json .. code-block:: json @@ -194,7 +194,7 @@ You can specify :ref:`array ` or :ref:`date You can change the default facet size (the number of results shown for each facet) for a table using ``facet_size``: .. [[[cog - metadata_example(cog, { + config_example(cog, { "databases": { "sf-trees": { "tables": { @@ -208,7 +208,7 @@ You can change the default facet size (the number of results shown for each face }) .. ]]] -.. tab:: metadata.yaml +.. tab:: datasette.yaml .. code-block:: yaml @@ -221,7 +221,7 @@ You can change the default facet size (the number of results shown for each face facet_size: 10 -.. tab:: metadata.json +.. tab:: datasette.json .. code-block:: json diff --git a/docs/full_text_search.rst b/docs/full_text_search.rst index 7bb73b93..349ad149 100644 --- a/docs/full_text_search.rst +++ b/docs/full_text_search.rst @@ -52,7 +52,7 @@ Configuring full-text search for a table or view If a table has a corresponding FTS table set up using the ``content=`` argument to ``CREATE VIRTUAL TABLE`` shown below, Datasette will detect it automatically and add a search interface to the table page for that table. -You can also manually configure which table should be used for full-text search using query string parameters or :ref:`metadata`. You can set the associated FTS table for a specific table and you can also set one for a view - if you do that, the page for that SQL view will offer a search option. +You can also manually configure which table should be used for full-text search using query string parameters or table configuration in ``datasette.yaml`` (see :ref:`table_configuration_fts`). You can set the associated FTS table for a specific table and you can also set one for a view - if you do that, the page for that SQL view will offer a search option. Use ``?_fts_table=x`` to over-ride the FTS table for a specific page. If the primary key was something other than ``rowid`` you can use ``?_fts_pk=col`` to set that as well. This is particularly useful for views, for example: @@ -65,8 +65,8 @@ The ``"searchmode": "raw"`` property can be used to default the table to accepti Here is an example which enables full-text search (with SQLite advanced search operators) for a ``display_ads`` view which is defined against the ``ads`` table and hence needs to run FTS against the ``ads_fts`` table, using the ``id`` as the primary key: .. [[[cog - from metadata_doc import metadata_example - metadata_example(cog, { + from metadata_doc import config_example + config_example(cog, { "databases": { "russian-ads": { "tables": { @@ -81,7 +81,7 @@ Here is an example which enables full-text search (with SQLite advanced search o }) .. ]]] -.. tab:: metadata.yaml +.. tab:: datasette.yaml .. code-block:: yaml @@ -94,7 +94,7 @@ Here is an example which enables full-text search (with SQLite advanced search o searchmode: raw -.. tab:: metadata.json +.. tab:: datasette.json .. code-block:: json diff --git a/docs/internals.rst b/docs/internals.rst index 6bd3d41d..544dd7fd 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -1820,13 +1820,13 @@ The ``Database`` class also provides properties and methods for introspecting th The name of the FTS table associated with this table, if one exists. ``await db.label_column_for_table(table)`` - string or None - The label column that is associated with this table - either automatically detected or using the ``"label_column"`` key from :ref:`metadata`, see :ref:`label_columns`. + The label column that is associated with this table - either automatically detected or using the ``"label_column"`` key in configuration, see :ref:`table_configuration_label_column`. ``await db.foreign_keys_for_table(table)`` - list of dictionaries Details of columns in this table which are foreign keys to other tables. A list of dictionaries where each dictionary is shaped like this: ``{"column": string, "other_table": string, "other_column": string}``. ``await db.hidden_table_names()`` - list of strings - List of tables which Datasette "hides" by default - usually these are tables associated with SQLite's full-text search feature, the SpatiaLite extension or tables hidden using the :ref:`metadata_hiding_tables` feature. + List of tables which Datasette "hides" by default - usually these are tables associated with SQLite's full-text search feature, the SpatiaLite extension or tables hidden using the :ref:`table_configuration_hidden` feature. ``await db.get_table_definition(table)`` - string Returns the SQL definition for the table - the ``CREATE TABLE`` statement and any associated ``CREATE INDEX`` statements. diff --git a/docs/json_api.rst b/docs/json_api.rst index 91a2bb15..891aa9e0 100644 --- a/docs/json_api.rst +++ b/docs/json_api.rst @@ -438,7 +438,7 @@ looks like: ] The column in the foreign key table that is used for the label can be specified -in ``metadata.json`` - see :ref:`label_columns`. +in ``datasette.yaml`` - see :ref:`table_configuration_label_column`. .. _json_api_discover_alternate: diff --git a/docs/metadata.rst b/docs/metadata.rst index a3fa4040..d9d10b8c 100644 --- a/docs/metadata.rst +++ b/docs/metadata.rst @@ -205,370 +205,14 @@ These will be displayed at the top of the table page, and will also show in the You can see an example of how these look at `latest.datasette.io/fixtures/roadside_attractions `__. -.. _metadata_default_sort: +.. _metadata_table_config: -Setting a default sort order ----------------------------- +Table configuration +------------------- -By default Datasette tables are sorted by primary key. You can over-ride this default for a specific table using the ``"sort"`` or ``"sort_desc"`` metadata properties: +Datasette supports a range of table-level configuration options including sort order, page size, facets, full-text search, column types, and more. These are now documented in the :ref:`table configuration ` section of the configuration reference. -.. [[[cog - metadata_example(cog, { - "databases": { - "mydatabase": { - "tables": { - "example_table": { - "sort": "created" - } - } - } - } - }) -.. ]]] - -.. tab:: metadata.yaml - - .. code-block:: yaml - - databases: - mydatabase: - tables: - example_table: - sort: created - - -.. tab:: metadata.json - - .. code-block:: json - - { - "databases": { - "mydatabase": { - "tables": { - "example_table": { - "sort": "created" - } - } - } - } - } -.. [[[end]]] - -Or use ``"sort_desc"`` to sort in descending order: - -.. [[[cog - metadata_example(cog, { - "databases": { - "mydatabase": { - "tables": { - "example_table": { - "sort_desc": "created" - } - } - } - } - }) -.. ]]] - -.. tab:: metadata.yaml - - .. code-block:: yaml - - databases: - mydatabase: - tables: - example_table: - sort_desc: created - - -.. tab:: metadata.json - - .. code-block:: json - - { - "databases": { - "mydatabase": { - "tables": { - "example_table": { - "sort_desc": "created" - } - } - } - } - } -.. [[[end]]] - -.. _metadata_page_size: - -Setting a custom page size --------------------------- - -Datasette defaults to displaying 100 rows per page, for both tables and views. You can change this default page size on a per-table or per-view basis using the ``"size"`` key in ``metadata.json``: - -.. [[[cog - metadata_example(cog, { - "databases": { - "mydatabase": { - "tables": { - "example_table": { - "size": 10 - } - } - } - } - }) -.. ]]] - -.. tab:: metadata.yaml - - .. code-block:: yaml - - databases: - mydatabase: - tables: - example_table: - size: 10 - - -.. tab:: metadata.json - - .. code-block:: json - - { - "databases": { - "mydatabase": { - "tables": { - "example_table": { - "size": 10 - } - } - } - } - } -.. [[[end]]] - -This size can still be over-ridden by passing e.g. ``?_size=50`` in the query string. - -.. _metadata_sortable_columns: - -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: - -.. [[[cog - metadata_example(cog, { - "databases": { - "database1": { - "tables": { - "example_table": { - "sortable_columns": [ - "height", - "weight" - ] - } - } - } - } - }) -.. ]]] - -.. tab:: metadata.yaml - - .. code-block:: yaml - - databases: - database1: - tables: - example_table: - sortable_columns: - - height - - weight - - -.. tab:: metadata.json - - .. code-block:: json - - { - "databases": { - "database1": { - "tables": { - "example_table": { - "sortable_columns": [ - "height", - "weight" - ] - } - } - } - } - } -.. [[[end]]] - -This will restrict sorting of ``example_table`` to just the ``height`` and -``weight`` columns. - -You can also disable sorting entirely by setting ``"sortable_columns": []`` - -You can use ``sortable_columns`` to enable specific sort orders for a view called ``name_of_view`` in the database ``my_database`` like so: - -.. [[[cog - metadata_example(cog, { - "databases": { - "my_database": { - "tables": { - "name_of_view": { - "sortable_columns": [ - "clicks", - "impressions" - ] - } - } - } - } - }) -.. ]]] - -.. tab:: metadata.yaml - - .. code-block:: yaml - - databases: - my_database: - tables: - name_of_view: - sortable_columns: - - clicks - - impressions - - -.. tab:: metadata.json - - .. code-block:: json - - { - "databases": { - "my_database": { - "tables": { - "name_of_view": { - "sortable_columns": [ - "clicks", - "impressions" - ] - } - } - } - } - } -.. [[[end]]] - -.. _label_columns: - -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: - -.. [[[cog - metadata_example(cog, { - "databases": { - "database1": { - "tables": { - "example_table": { - "label_column": "title" - } - } - } - } - }) -.. ]]] - -.. tab:: metadata.yaml - - .. code-block:: yaml - - databases: - database1: - tables: - example_table: - label_column: title - - -.. tab:: metadata.json - - .. code-block:: json - - { - "databases": { - "database1": { - "tables": { - "example_table": { - "label_column": "title" - } - } - } - } - } -.. [[[end]]] - -.. _metadata_hiding_tables: - -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``: - -.. [[[cog - metadata_example(cog, { - "databases": { - "database1": { - "tables": { - "example_table": { - "hidden": True - } - } - } - } - }) -.. ]]] - -.. tab:: metadata.yaml - - .. code-block:: yaml - - databases: - database1: - tables: - example_table: - hidden: true - - -.. tab:: metadata.json - - .. code-block:: json - - { - "databases": { - "database1": { - "tables": { - "example_table": { - "hidden": true - } - } - } - } - } -.. [[[end]]] +For backwards compatibility these options can be specified in either ``metadata.yaml`` or ``datasette.yaml``. .. _metadata_reference: @@ -613,7 +257,7 @@ Table-level metadata "Table-level" metadata refers to fields that can be specified for each table in a Datasette instance. These attributes should be listed under a specific table using the `"tables"` field. -The following are the full list of allowed table-level metadata fields: +The following metadata fields are supported at the table level: - ``source`` - ``source_url`` @@ -621,13 +265,6 @@ The following are the full list of allowed table-level metadata fields: - ``license_url`` - ``about`` - ``about_url`` -- ``hidden`` -- ``sort/sort_desc`` -- ``size`` -- ``sortable_columns`` -- ``label_column`` -- ``facets`` -- ``fts_table`` -- ``fts_pk`` -- ``searchmode`` -- ``columns`` +- ``columns`` (see :ref:`metadata_column_descriptions`) + +Additionally, tables support a number of configuration options (``sort``, ``sort_desc``, ``size``, ``sortable_columns``, ``label_column``, ``hidden``, ``facets``, ``facet_size``, ``fts_table``, ``fts_pk``, ``searchmode``, ``column_types``). See :ref:`table configuration ` for full details. diff --git a/docs/pages.rst b/docs/pages.rst index 2e54ce2f..a8a25fa7 100644 --- a/docs/pages.rst +++ b/docs/pages.rst @@ -50,7 +50,7 @@ Some tables listed on the database page are treated as hidden. Hidden tables are The following tables are hidden by default: - Any table with a name that starts with an underscore - this is a Datasette convention to help plugins easily hide their own internal tables. -- Tables that have been configured as ``"hidden": true`` using :ref:`metadata_hiding_tables`. +- Tables that have been configured as ``"hidden": true`` using :ref:`table_configuration_hidden`. - ``*_fts`` tables that implement SQLite full-text search indexes. - Tables relating to the inner workings of the SpatiaLite SQLite extension. - ``sqlite_stat`` tables used to store statistics used by the query optimizer.