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

Refresh JSON API extra descriptions

Browse source
This commit is contained in:
Simon Willison 2026-06-23 07:32:37 -07:00
commit 2680e3c4bd
1 changed files with 35 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

70
docs/json_api.rst
View file

@ -267,7 +267,7 @@ The available table extras are listed below.
15
``count_sql``
SQL query used to calculate the total count
SQL query string used to calculate the total count for the current table view, including active filters.
``GET /fixtures/facetable.json?_size=0&_extra=count_sql``
@ -276,7 +276,7 @@ The available table extras are listed below.
"select count(*) from facetable "
``facet_results``
Results of facets calculated against this data (May execute additional queries. See :ref:`facets` for details of how facets work.)
Results of facets calculated against this data. A dictionary with ``results`` and ``timed_out`` keys: ``results`` maps facet names to facet dictionaries with ``name``, ``type``, ``results`` and URL keys, and each facet result item includes ``value``, ``label``, ``count`` and ``toggle_url``. (May execute additional queries. See :ref:`facets` for details of how facets work.)
Shape abbreviated from /fixtures/facetable.json?_facet=state&_extra=facet_results.
@ -305,7 +305,7 @@ The available table extras are listed below.
}
``facets_timed_out``
Facet calculations that timed out
List of names of facet calculations that exceeded the facet time limit.
``GET /fixtures/facetable.json?_facet=state&_extra=facets_timed_out``
@ -316,7 +316,7 @@ The available table extras are listed below.
[]
``suggested_facets``
Suggestions for facets that might return interesting results (May execute additional queries. Suggestions are controlled by the :ref:`setting_suggest_facets` setting.)
Suggestions for facets that might return interesting results. Each item is a dictionary with ``name`` and ``toggle_url`` keys, and may include extra keys such as ``type`` or ``label`` depending on the facet class. (May execute additional queries. Suggestions are controlled by the :ref:`setting_suggest_facets` setting.)
Shape abbreviated from /fixtures/facetable.json?_extra=suggested_facets.
@ -350,7 +350,7 @@ The available table extras are listed below.
"http://localhost/fixtures/facetable.json?_size=1&_extra=next_url&_next=1"
``columns``
Column names returned by this query
List of column names returned by this table, row or query.
``GET /fixtures/facetable.json?_extra=columns``
@ -371,7 +371,7 @@ The available table extras are listed below.
]
``all_columns``
All columns in the table, regardless of _col/_nocol filtering
List of all column names in the table, regardless of ``_col=`` or ``_nocol=`` filtering.
``GET /fixtures/facetable.json?_col=pk&_extra=all_columns``
@ -392,7 +392,7 @@ The available table extras are listed below.
]
``primary_keys``
Primary keys for this table
List of primary key column names for this table, or an empty list if the table has no explicit primary key.
``GET /fixtures/facetable.json?_extra=primary_keys``
@ -403,7 +403,7 @@ The available table extras are listed below.
]
``display_columns``
Column metadata used by the HTML table display
Column metadata used by the HTML table display. Each item includes ``name``, ``sortable``, ``is_pk``, ``type``, ``notnull``, ``description``, ``column_type`` and ``column_type_config`` keys.
Shape abbreviated from /fixtures/facetable.json?_size=1&_extra=display_columns.
@ -456,7 +456,7 @@ The available table extras are listed below.
}
``debug``
Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
Extra debug information dictionary. This is intended for development only and its shape is not part of the stable template contract. (The contents of this block are not a stable part of the Datasette API and may change without warning.)
``GET /fixtures/facetable.json?_extra=debug``
@ -474,7 +474,7 @@ The available table extras are listed below.
}
``request``
Full information about the request
Dictionary with request details: ``url``, ``path``, ``full_path``, ``host`` and ``args`` where ``args`` maps query string parameter names to their values.
``GET /fixtures/facetable.json?_extra=request``
@ -493,7 +493,7 @@ The available table extras are listed below.
}
``query``
Details of the underlying SQL query
Details of the underlying SQL query as a dictionary with ``sql`` and ``params`` keys.
``GET /fixtures/facetable.json?_size=1&_extra=query``
@ -505,7 +505,7 @@ The available table extras are listed below.
}
``column_types``
Column type assignments for this table (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
Column type assignments for this table. A dictionary mapping column names to ``{"type": type_name, "config": config}`` dictionaries. (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
``GET /fixtures/facetable.json?_size=0&_extra=column_types``
@ -521,7 +521,7 @@ The available table extras are listed below.
}
``set_column_type_ui``
Information needed to build an interface for assigning column types (``null`` unless the current actor is allowed to use the :ref:`set column type API <TableSetColumnTypeView>` for this table.)
Information needed to build an interface for assigning column types, or ``None`` if unavailable. When present it has ``path`` and ``columns`` keys; ``columns`` maps column names to ``current`` and ``options`` values. (``null`` unless the current actor is allowed to use the :ref:`set column type API <TableSetColumnTypeView>` for this table.)
Shape abbreviated to two columns, as seen by an actor with ``set-column-type`` permission. ``current`` is the column type currently assigned to each column and ``options`` lists the types that could be assigned to it.
@ -571,7 +571,7 @@ The available table extras are listed below.
}
``metadata``
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
Metadata dictionary for the table, database or stored query. Table and row metadata include a ``columns`` dictionary mapping column names to descriptions; stored query metadata returns the stored query configuration. (See :ref:`metadata` for how to attach metadata to tables.)
``GET /fixtures/facetable.json?_extra=metadata``
@ -587,7 +587,7 @@ The available table extras are listed below.
}
``extras``
List of ?_extra= blocks that can be used on this page
List of ``?_extra=`` blocks that can be used on this page. Each item has ``name``, ``description``, ``toggle_url`` and ``selected`` keys.
Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
@ -636,7 +636,7 @@ The available table extras are listed below.
"9403e5"
``renderers``
Alternative output renderers available for this table
Dictionary mapping output format names such as ``json`` or plugin-provided renderer names to URLs for this data in that format.
``GET /fixtures/facetable.json?_extra=renderers``
@ -649,7 +649,7 @@ The available table extras are listed below.
}
``custom_table_templates``
Custom template names considered for this table (The first template in this list that exists will be used to render the table on the HTML version of this page. See :ref:`customization_custom_templates`.)
List of custom template names considered for rendering table rows, in lookup order. (The first template in this list that exists will be used to render the table on the HTML version of this page. See :ref:`customization_custom_templates`.)
``GET /fixtures/facetable.json?_extra=custom_table_templates``
@ -662,7 +662,7 @@ The available table extras are listed below.
]
``sorted_facet_results``
Facet results sorted for display (The same data as ``facet_results``, as a list in the order used by the HTML interface: facets from :ref:`facet configuration <facets_metadata>` first, then other facets ordered by their number of results.)
Facet result dictionaries sorted for display. Each item has the same shape as an entry from ``facet_results['results']``. (The same data as ``facet_results``, as a list in the order used by the HTML interface: facets from :ref:`facet configuration <facets_metadata>` first, then other facets ordered by their number of results.)
``GET /fixtures/facetable.json?_facet=state&_extra=sorted_facet_results``
@ -738,7 +738,7 @@ The available table extras are listed below.
false
``expandable_columns``
Foreign key columns that can be expanded with labels (See :ref:`expand_foreign_keys` for how to expand these labels.)
List of foreign key columns that can be expanded with labels. Each item is a ``(foreign_key, label_column)`` pair where ``foreign_key`` is the SQLite foreign key dictionary and ``label_column`` is the label column in the referenced table, or ``None``. (See :ref:`expand_foreign_keys` for how to expand these labels.)
``GET /fixtures/facetable.json?_extra=expandable_columns``
@ -758,7 +758,7 @@ The available table extras are listed below.
]
``form_hidden_args``
Hidden form arguments used by the HTML table interface
List of ``(name, value)`` pairs for hidden form fields used by the HTML table interface to preserve current query string options.
``GET /fixtures/facetable.json?_facet=state&_size=1&_extra=form_hidden_args``
@ -785,7 +785,7 @@ Row JSON responses
The following extras are available for row JSON responses.
``columns``
Column names returned by this query
List of column names returned by this table, row or query.
``GET /fixtures/simple_primary_key/1.json?_extra=columns``
@ -797,7 +797,7 @@ The following extras are available for row JSON responses.
]
``primary_keys``
Primary keys for this table
List of primary key column names for this table, or an empty list if the table has no explicit primary key.
``GET /fixtures/simple_primary_key/1.json?_extra=primary_keys``
@ -829,7 +829,7 @@ The following extras are available for row JSON responses.
}
``debug``
Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
Extra debug information dictionary. This is intended for development only and its shape is not part of the stable template contract. (The contents of this block are not a stable part of the Datasette API and may change without warning.)
``GET /fixtures/simple_primary_key/1.json?_extra=debug``
@ -858,7 +858,7 @@ The following extras are available for row JSON responses.
}
``request``
Full information about the request
Dictionary with request details: ``url``, ``path``, ``full_path``, ``host`` and ``args`` where ``args`` maps query string parameter names to their values.
``GET /fixtures/simple_primary_key/1.json?_extra=request``
@ -877,7 +877,7 @@ The following extras are available for row JSON responses.
}
``query``
Details of the underlying SQL query
Details of the underlying SQL query as a dictionary with ``sql`` and ``params`` keys.
``GET /fixtures/simple_primary_key/1.json?_extra=query``
@ -891,7 +891,7 @@ The following extras are available for row JSON responses.
}
``column_types``
Column type assignments for this table (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
Column type assignments for this table. A dictionary mapping column names to ``{"type": type_name, "config": config}`` dictionaries. (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
``GET /fixtures/facetable/1.json?_extra=column_types``
@ -907,7 +907,7 @@ The following extras are available for row JSON responses.
}
``metadata``
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
Metadata dictionary for the table, database or stored query. Table and row metadata include a ``columns`` dictionary mapping column names to descriptions; stored query metadata returns the stored query configuration. (See :ref:`metadata` for how to attach metadata to tables.)
``GET /fixtures/simple_primary_key/1.json?_extra=metadata``
@ -920,7 +920,7 @@ The following extras are available for row JSON responses.
}
``extras``
List of ?_extra= blocks that can be used on this page
List of ``?_extra=`` blocks that can be used on this page. Each item has ``name``, ``description``, ``toggle_url`` and ``selected`` keys.
Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
@ -978,7 +978,7 @@ The following extras are available for row JSON responses.
false
``foreign_key_tables``
Tables that link to this row using foreign keys (May execute additional queries.)
List of tables that link to this row using foreign keys. Each item includes the foreign key fields plus ``count`` for matching rows and ``link`` for the filtered table URL. (May execute additional queries.)
``GET /fixtures/simple_primary_key/1.json?_extra=foreign_key_tables``
@ -1030,7 +1030,7 @@ Query JSON responses
The following extras are available for arbitrary SQL query responses and stored, named query responses.
``columns``
Column names returned by this query
List of column names returned by this table, row or query.
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=columns``
@ -1061,7 +1061,7 @@ The following extras are available for arbitrary SQL query responses and stored,
}
``debug``
Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
Extra debug information dictionary. This is intended for development only and its shape is not part of the stable template contract. (The contents of this block are not a stable part of the Datasette API and may change without warning.)
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=debug``
@ -1075,7 +1075,7 @@ The following extras are available for arbitrary SQL query responses and stored,
}
``request``
Full information about the request
Dictionary with request details: ``url``, ``path``, ``full_path``, ``host`` and ``args`` where ``args`` maps query string parameter names to their values.
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=request``
@ -1097,7 +1097,7 @@ The following extras are available for arbitrary SQL query responses and stored,
}
``query``
Details of the underlying SQL query
Details of the underlying SQL query as a dictionary with ``sql`` and ``params`` keys.
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=query``
@ -1120,7 +1120,7 @@ The following extras are available for arbitrary SQL query responses and stored,
}
``metadata``
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
Metadata dictionary for the table, database or stored query. Table and row metadata include a ``columns`` dictionary mapping column names to descriptions; stored query metadata returns the stored query configuration. (See :ref:`metadata` for how to attach metadata to tables.)
``GET /fixtures/neighborhood_search.json?text=town&_extra=metadata``
@ -1151,7 +1151,7 @@ The following extras are available for arbitrary SQL query responses and stored,
}
``extras``
List of ?_extra= blocks that can be used on this page
List of ``?_extra=`` blocks that can be used on this page. Each item has ``name``, ``description``, ``toggle_url`` and ``selected`` keys.
Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.