remote/datasette
1
0
Fork 0
mirror of https://github.com/simonw/datasette.git synced 2026-06-02 23:26:59 +02:00
Code Issues Projects Releases Packages Wiki Activity

Move table configuration docs from metadata.rst to configuration.rst (#2668)

Browse source 
https://claude.ai/code/session_01UqboRB5Wt52BKPhxexUBEn
This commit is contained in:
Simon Willison 2026-03-17 08:47:04 -07:00 • committed by GitHub
commit 63d73a806f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 613 additions and 401 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/changelog.rst
View file

@ -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_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 <https://github.com/encode/httpx/releases/tag/0.20.0>`__ - 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 <https://github.com/simonw/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 <https://github.com/simonw/datasette-json-html>`__ and `datasette-render-images <https://github.com/simonw/datasette-render-images>`__ are two new plugins that use this hook. :ref:`render_cell documentation <plugin_hook_render_cell>`. 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 <plugin_hook_extra_body_script>`.
- ``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 <plugin_hook_extra_css_urls>`.
- You can now use the :ref:`sortable_columns metadata setting <metadata_sortable_columns>` 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 <table_configuration_sortable_columns>` 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 <full_text_search_table_or_view>`, even if that table is not directly coupled to the SQLite FTS feature in the database schema itself.
- Datasette will now use `pysqlite3 <https://github.com/coleifer/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 <https://www.sqlite.org/releaselog/3_25_0.html>`__ which adds window function support. More details on how to use this in :issue:`360`
- New mechanism that allows :ref:`plugin configuration options <plugins_configuration>` 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

575
docs/configuration.rst
View file

@ -634,5 +634,580 @@ Will produce this HTML:
<script type="module" src="https://example.datasette.io/module.js"></script>
.. _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 <facet_by_json_array>` or :ref:`date <facet_by_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 <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 <https://www.sqlite.org/fts5.html#full_text_query_syntax>`__.
.. [[[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_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]]]

30
docs/facets.rst
View file

@ -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 <table_configuration_facets>` 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 <facet_by_json_array>` or :ref:`date <facet_by_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 <facet_by_json_array>` or :ref:`date <facet_by_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 <facet_by_json_array>` or :ref:`date <facet_by_date>
})
.. ]]]
.. tab:: metadata.yaml
.. tab:: datasette.yaml
.. code-block:: yaml
@ -175,7 +175,7 @@ You can specify :ref:`array <facet_by_json_array>` or :ref:`date <facet_by_date>
- date: created
.. tab:: metadata.json
.. tab:: datasette.json
.. code-block:: json
@ -194,7 +194,7 @@ You can specify :ref:`array <facet_by_json_array>` or :ref:`date <facet_by_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

10
docs/full_text_search.rst
View file

@ -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

4
docs/internals.rst
View file

@ -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.

2
docs/json_api.rst
View file

@ -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:

381
docs/metadata.rst
View file

@ -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 <https://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 <configuration_reference_table>` 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 <configuration_reference_table>` for full details.

2
docs/pages.rst
View file

@ -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.