mirror of
https://github.com/simonw/datasette.git
synced 2026-06-12 12:06:57 +02:00
Clearer examples and descriptions for JSON API extras (#2773)
Review of the generated ?_extra= documentation found several extras
with no example output or with examples that needed explanation:
- extras: now shows an abbreviated example of the toggle list and has
a clearer description (which also improves the live API output)
- set_column_type_ui: example of the shape seen with set-column-type
permission, plus a note that it is null otherwise
- column_types: live example generated from a table with an assigned
column type instead of an empty {}
- metadata: live table example now demonstrates a table description
and column descriptions; row and query examples gained explanatory
notes
- expandable_columns, foreign_key_tables, facets_timed_out, next_url,
renderers: notes explaining the shape of their output
Also added docs_note cross-references to the relevant documentation:
facets, pagination, render_cell and register_output_renderer plugin
hooks, column type configuration and API, metadata, custom templates,
permissions and foreign key label expansion. foreign_key_tables is
now flagged as potentially executing additional queries.
https://claude.ai/code/session_01EfjBe6E817m9XNFW7EX3Vm
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Simon Willison
GitHub
parent
1d4212122e
commit
fa86ac7b11
3 changed files with 360 additions and 42 deletions
|
|
@ -184,6 +184,7 @@ class FacetResultsExtra(Extra):
|
|||
)
|
||||
scopes = {ExtraScope.TABLE}
|
||||
expensive = True
|
||||
docs_note = "See :ref:`facets` for details of how facets work."
|
||||
|
||||
async def resolve(self, context, facet_instances):
|
||||
facet_results = {}
|
||||
|
|
@ -215,7 +216,12 @@ class FacetResultsExtra(Extra):
|
|||
class FacetsTimedOutExtra(Extra):
|
||||
description = "Facet calculations that timed out"
|
||||
example = ExtraExample(
|
||||
"/fixtures/facetable.json?_facet=state&_extra=facets_timed_out"
|
||||
"/fixtures/facetable.json?_facet=state&_extra=facets_timed_out",
|
||||
note=(
|
||||
"A list of the names of any facets that exceeded the "
|
||||
":ref:`setting_facet_time_limit_ms` time limit - an empty list "
|
||||
"if every facet calculation completed."
|
||||
),
|
||||
)
|
||||
scopes = {ExtraScope.TABLE}
|
||||
|
||||
|
|
@ -236,6 +242,9 @@ class SuggestedFacetsExtra(Extra):
|
|||
)
|
||||
scopes = {ExtraScope.TABLE}
|
||||
expensive = True
|
||||
docs_note = (
|
||||
"Suggestions are controlled by the :ref:`setting_suggest_facets` setting."
|
||||
)
|
||||
|
||||
async def resolve(self, context, facet_instances):
|
||||
suggested_facets = []
|
||||
|
|
@ -278,7 +287,13 @@ class HumanDescriptionEnExtra(Extra):
|
|||
|
||||
class NextUrlExtra(Extra):
|
||||
description = "Full URL for the next page of results"
|
||||
example = ExtraExample("/fixtures/facetable.json?_size=1&_extra=next_url")
|
||||
example = ExtraExample(
|
||||
"/fixtures/facetable.json?_size=1&_extra=next_url",
|
||||
note=(
|
||||
"``null`` if there are no more pages of results. "
|
||||
"See :ref:`json_api_pagination`."
|
||||
),
|
||||
)
|
||||
scopes = {ExtraScope.TABLE}
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -366,6 +381,10 @@ class IsViewExtra(Extra):
|
|||
|
||||
class DebugExtra(Extra):
|
||||
description = "Extra debug information"
|
||||
docs_note = (
|
||||
"The contents of this block are not a stable part of the Datasette "
|
||||
"API and may change without warning."
|
||||
)
|
||||
example = ExtraExample("/fixtures/facetable.json?_extra=debug")
|
||||
examples = {
|
||||
ExtraScope.ROW: ExtraExample(
|
||||
|
|
@ -482,6 +501,10 @@ class DisplayRowsExtra(Extra):
|
|||
|
||||
class RenderCellExtra(Extra):
|
||||
description = "Rendered HTML for each cell using the render_cell plugin hook"
|
||||
docs_note = (
|
||||
"See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` "
|
||||
"documentation."
|
||||
)
|
||||
example = ExtraExample(
|
||||
value={
|
||||
"rows": [
|
||||
|
|
@ -598,7 +621,28 @@ class QueryExtra(Extra):
|
|||
|
||||
class ColumnTypesExtra(Extra):
|
||||
description = "Column type assignments for this table"
|
||||
example = ExtraExample(value={})
|
||||
docs_note = (
|
||||
"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>`."
|
||||
)
|
||||
example = ExtraExample(
|
||||
"/fixtures/facetable.json?_size=0&_extra=column_types",
|
||||
note=(
|
||||
"This example is from an instance where the ``tags`` column has "
|
||||
"been assigned the ``json`` column type."
|
||||
),
|
||||
)
|
||||
examples = {
|
||||
ExtraScope.ROW: ExtraExample(
|
||||
"/fixtures/facetable/1.json?_extra=column_types",
|
||||
note=(
|
||||
"This example is from an instance where the ``tags`` column "
|
||||
"has been assigned the ``json`` column type."
|
||||
),
|
||||
)
|
||||
}
|
||||
scopes = {ExtraScope.TABLE, ExtraScope.ROW}
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -615,7 +659,40 @@ class ColumnTypesExtra(Extra):
|
|||
|
||||
|
||||
class SetColumnTypeUiExtra(Extra):
|
||||
description = "Column type UI metadata for this table"
|
||||
description = "Information needed to build an interface for assigning column types"
|
||||
docs_note = (
|
||||
"``null`` unless the current actor is allowed to use the :ref:`set "
|
||||
"column type API <TableSetColumnTypeView>` for this table."
|
||||
)
|
||||
example = ExtraExample(
|
||||
value={
|
||||
"path": "/fixtures/facetable/-/set-column-type",
|
||||
"columns": {
|
||||
"created": {
|
||||
"current": None,
|
||||
"options": [
|
||||
{"name": "email", "description": "Email address"},
|
||||
{"name": "json", "description": "JSON data"},
|
||||
{"name": "url", "description": "URL"},
|
||||
],
|
||||
},
|
||||
"tags": {
|
||||
"current": {"type": "json", "config": None},
|
||||
"options": [
|
||||
{"name": "email", "description": "Email address"},
|
||||
{"name": "json", "description": "JSON data"},
|
||||
{"name": "url", "description": "URL"},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
note=(
|
||||
"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."
|
||||
),
|
||||
)
|
||||
scopes = {ExtraScope.TABLE}
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -667,13 +744,33 @@ class SetColumnTypeUiExtra(Extra):
|
|||
|
||||
class MetadataExtra(Extra):
|
||||
description = "Metadata about the table, database or stored query"
|
||||
example = ExtraExample("/fixtures/facetable.json?_extra=metadata")
|
||||
docs_note = "See :ref:`metadata` for how to attach metadata to tables."
|
||||
example = ExtraExample(
|
||||
"/fixtures/facetable.json?_extra=metadata",
|
||||
note=(
|
||||
"This example is from an instance where the ``facetable`` table "
|
||||
"has a metadata ``description`` and a :ref:`column description "
|
||||
"<metadata_column_descriptions>` for its ``state`` column. The "
|
||||
"``columns`` object is empty for tables with no column "
|
||||
"descriptions."
|
||||
),
|
||||
)
|
||||
examples = {
|
||||
ExtraScope.ROW: ExtraExample(
|
||||
"/fixtures/simple_primary_key/1.json?_extra=metadata"
|
||||
"/fixtures/simple_primary_key/1.json?_extra=metadata",
|
||||
note=(
|
||||
"This table has no metadata, so only an empty ``columns`` "
|
||||
"object is returned."
|
||||
),
|
||||
),
|
||||
ExtraScope.QUERY: ExtraExample(
|
||||
"/fixtures/neighborhood_search.json?text=town&_extra=metadata"
|
||||
"/fixtures/neighborhood_search.json?text=town&_extra=metadata",
|
||||
note=(
|
||||
"For stored queries this returns the full configuration of "
|
||||
"the query, including the :ref:`stored query options "
|
||||
"<queries_options>`. For ``?sql=`` queries it returns an "
|
||||
"empty object."
|
||||
),
|
||||
),
|
||||
}
|
||||
scopes = {ExtraScope.TABLE, ExtraScope.ROW, ExtraScope.QUERY}
|
||||
|
|
@ -733,6 +830,10 @@ class TableExtra(Extra):
|
|||
|
||||
class DatabaseColorExtra(Extra):
|
||||
description = "Color assigned to the database"
|
||||
docs_note = (
|
||||
"A six character hex color, without the leading ``#``, derived from "
|
||||
"a hash of the database name and used in the Datasette interface."
|
||||
)
|
||||
example = ExtraExample("/fixtures/facetable.json?_extra=database_color")
|
||||
examples = {
|
||||
ExtraScope.ROW: ExtraExample(
|
||||
|
|
@ -780,6 +881,11 @@ class FiltersExtra(Extra):
|
|||
|
||||
class CustomTableTemplatesExtra(Extra):
|
||||
description = "Custom template names considered for this table"
|
||||
docs_note = (
|
||||
"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`."
|
||||
)
|
||||
example = ExtraExample("/fixtures/facetable.json?_extra=custom_table_templates")
|
||||
scopes = {ExtraScope.TABLE}
|
||||
|
||||
|
|
@ -793,6 +899,12 @@ class CustomTableTemplatesExtra(Extra):
|
|||
|
||||
class SortedFacetResultsExtra(Extra):
|
||||
description = "Facet results sorted for display"
|
||||
docs_note = (
|
||||
"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."
|
||||
)
|
||||
example = ExtraExample(
|
||||
"/fixtures/facetable.json?_facet=state&_extra=sorted_facet_results"
|
||||
)
|
||||
|
|
@ -849,7 +961,15 @@ class ViewDefinitionExtra(Extra):
|
|||
|
||||
class RenderersExtra(Extra):
|
||||
description = "Alternative output renderers available for this table"
|
||||
example = ExtraExample("/fixtures/facetable.json?_extra=renderers")
|
||||
example = ExtraExample(
|
||||
"/fixtures/facetable.json?_extra=renderers",
|
||||
note=(
|
||||
"Each key is the name of an output format, each value the URL "
|
||||
"for this data in that format. Plugins can add additional "
|
||||
"formats using the :ref:`register_output_renderer() plugin hook "
|
||||
"<plugin_register_output_renderer>`."
|
||||
),
|
||||
)
|
||||
scopes = {ExtraScope.TABLE}
|
||||
|
||||
async def resolve(self, context, expandable_columns, query):
|
||||
|
|
@ -887,6 +1007,10 @@ class RenderersExtra(Extra):
|
|||
|
||||
class PrivateExtra(Extra):
|
||||
description = "Whether this resource is private to the current actor"
|
||||
docs_note = (
|
||||
"``true`` if the current actor can see this resource but an "
|
||||
"anonymous user could not. See :ref:`authentication_permissions`."
|
||||
)
|
||||
example = ExtraExample("/fixtures/facetable.json?_extra=private")
|
||||
examples = {
|
||||
ExtraScope.ROW: ExtraExample(
|
||||
|
|
@ -904,7 +1028,15 @@ class PrivateExtra(Extra):
|
|||
|
||||
class ExpandableColumnsExtra(Extra):
|
||||
description = "Foreign key columns that can be expanded with labels"
|
||||
example = ExtraExample("/fixtures/facetable.json?_extra=expandable_columns")
|
||||
docs_note = "See :ref:`expand_foreign_keys` for how to expand these labels."
|
||||
example = ExtraExample(
|
||||
"/fixtures/facetable.json?_extra=expandable_columns",
|
||||
note=(
|
||||
"Each item is a ``[foreign_key, label_column]`` pair: the "
|
||||
"foreign key relationship, then the column in the other table "
|
||||
"that would be used as the label for each expanded value."
|
||||
),
|
||||
)
|
||||
scopes = {ExtraScope.TABLE}
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -919,9 +1051,14 @@ class ExpandableColumnsExtra(Extra):
|
|||
class ForeignKeyTablesExtra(Extra):
|
||||
description = "Tables that link to this row using foreign keys"
|
||||
example = ExtraExample(
|
||||
"/fixtures/simple_primary_key/1.json?_extra=foreign_key_tables"
|
||||
"/fixtures/simple_primary_key/1.json?_extra=foreign_key_tables",
|
||||
note=(
|
||||
"``count`` is the number of rows in the other table that "
|
||||
"reference this row, and ``link`` is a URL to browse those rows."
|
||||
),
|
||||
)
|
||||
scopes = {ExtraScope.ROW}
|
||||
expensive = True
|
||||
|
||||
async def resolve(self, context):
|
||||
return await context.foreign_key_tables(
|
||||
|
|
@ -930,7 +1067,30 @@ class ForeignKeyTablesExtra(Extra):
|
|||
|
||||
|
||||
class ExtrasExtra(Extra):
|
||||
description = "Available ?_extra= blocks"
|
||||
description = "List of ?_extra= blocks that can be used on this page"
|
||||
example = ExtraExample(
|
||||
value=[
|
||||
{
|
||||
"name": "count",
|
||||
"description": "Total count of rows matching these filters",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
|
||||
"selected": False,
|
||||
},
|
||||
{
|
||||
"name": "extras",
|
||||
"description": "List of ?_extra= blocks that can be used on this page",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json",
|
||||
"selected": True,
|
||||
},
|
||||
],
|
||||
note=(
|
||||
"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."
|
||||
),
|
||||
)
|
||||
scopes = {ExtraScope.TABLE, ExtraScope.ROW, ExtraScope.QUERY}
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
|
|||
|
|
@ -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.)
|
||||
Results of facets calculated against this data (May execute additional queries. See :ref:`facets` for details of how facets work.)
|
||||
|
||||
Shape abbreviated from /fixtures/facetable.json?_facet=state&_extra=facet_results.
|
||||
|
||||
|
|
@ -309,12 +309,14 @@ The available table extras are listed below.
|
|||
|
||||
``GET /fixtures/facetable.json?_facet=state&_extra=facets_timed_out``
|
||||
|
||||
A list of the names of any facets that exceeded the :ref:`setting_facet_time_limit_ms` time limit - an empty list if every facet calculation completed.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[]
|
||||
|
||||
``suggested_facets``
|
||||
Suggestions for facets that might return interesting results (May execute additional queries.)
|
||||
Suggestions for facets that might return interesting results (May execute additional queries. Suggestions are controlled by the :ref:`setting_suggest_facets` setting.)
|
||||
|
||||
Shape abbreviated from /fixtures/facetable.json?_extra=suggested_facets.
|
||||
|
||||
|
|
@ -341,6 +343,8 @@ The available table extras are listed below.
|
|||
|
||||
``GET /fixtures/facetable.json?_size=1&_extra=next_url``
|
||||
|
||||
``null`` if there are no more pages of results. See :ref:`json_api_pagination`.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"http://localhost/fixtures/facetable.json?_size=1&_extra=next_url&_next=1"
|
||||
|
|
@ -426,7 +430,7 @@ The available table extras are listed below.
|
|||
]
|
||||
|
||||
``render_cell``
|
||||
Rendered HTML for each cell using the render_cell plugin hook
|
||||
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
|
||||
|
||||
The ``render_cell`` array has one item per row, in the same order as the ``rows`` array. Each object is keyed by column name. Only columns whose rendered value differs from the default are included.
|
||||
|
||||
|
|
@ -452,7 +456,7 @@ The available table extras are listed below.
|
|||
}
|
||||
|
||||
``debug``
|
||||
Extra debug information
|
||||
Extra debug information (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``
|
||||
|
||||
|
|
@ -501,28 +505,108 @@ The available table extras are listed below.
|
|||
}
|
||||
|
||||
``column_types``
|
||||
Column type assignments for this table
|
||||
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>`.)
|
||||
|
||||
.. code-block:: json
|
||||
``GET /fixtures/facetable.json?_size=0&_extra=column_types``
|
||||
|
||||
{}
|
||||
|
||||
``set_column_type_ui``
|
||||
Column type UI metadata for this table
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=metadata``
|
||||
This example is from an instance where the ``tags`` column has been assigned the ``json`` column type.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"columns": {}
|
||||
"tags": {
|
||||
"type": "json",
|
||||
"config": null
|
||||
}
|
||||
}
|
||||
|
||||
``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.)
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"path": "/fixtures/facetable/-/set-column-type",
|
||||
"columns": {
|
||||
"created": {
|
||||
"current": null,
|
||||
"options": [
|
||||
{
|
||||
"name": "email",
|
||||
"description": "Email address"
|
||||
},
|
||||
{
|
||||
"name": "json",
|
||||
"description": "JSON data"
|
||||
},
|
||||
{
|
||||
"name": "url",
|
||||
"description": "URL"
|
||||
}
|
||||
]
|
||||
},
|
||||
"tags": {
|
||||
"current": {
|
||||
"type": "json",
|
||||
"config": null
|
||||
},
|
||||
"options": [
|
||||
{
|
||||
"name": "email",
|
||||
"description": "Email address"
|
||||
},
|
||||
{
|
||||
"name": "json",
|
||||
"description": "JSON data"
|
||||
},
|
||||
{
|
||||
"name": "url",
|
||||
"description": "URL"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=metadata``
|
||||
|
||||
This example is from an instance where the ``facetable`` table has a metadata ``description`` and a :ref:`column description <metadata_column_descriptions>` for its ``state`` column. The ``columns`` object is empty for tables with no column descriptions.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"description": "A demo table of places, used to demonstrate facets",
|
||||
"columns": {
|
||||
"state": "Two letter US state code"
|
||||
}
|
||||
}
|
||||
|
||||
``extras``
|
||||
Available ?_extra= blocks
|
||||
List of ?_extra= blocks that can be used on this page
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "count",
|
||||
"description": "Total count of rows matching these filters",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
|
||||
"selected": false
|
||||
},
|
||||
{
|
||||
"name": "extras",
|
||||
"description": "List of ?_extra= blocks that can be used on this page",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json",
|
||||
"selected": true
|
||||
}
|
||||
]
|
||||
|
||||
``database``
|
||||
Database name
|
||||
|
|
@ -543,7 +627,7 @@ The available table extras are listed below.
|
|||
"facetable"
|
||||
|
||||
``database_color``
|
||||
Color assigned to the database
|
||||
Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=database_color``
|
||||
|
||||
|
|
@ -556,6 +640,8 @@ The available table extras are listed below.
|
|||
|
||||
``GET /fixtures/facetable.json?_extra=renderers``
|
||||
|
||||
Each key is the name of an output format, each value the URL for this data in that format. Plugins can add additional formats using the :ref:`register_output_renderer() plugin hook <plugin_register_output_renderer>`.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
|
|
@ -563,7 +649,7 @@ The available table extras are listed below.
|
|||
}
|
||||
|
||||
``custom_table_templates``
|
||||
Custom template names considered for this table
|
||||
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`.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=custom_table_templates``
|
||||
|
||||
|
|
@ -576,7 +662,7 @@ The available table extras are listed below.
|
|||
]
|
||||
|
||||
``sorted_facet_results``
|
||||
Facet results sorted for display
|
||||
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.)
|
||||
|
||||
``GET /fixtures/facetable.json?_facet=state&_extra=sorted_facet_results``
|
||||
|
||||
|
|
@ -643,7 +729,7 @@ The available table extras are listed below.
|
|||
true
|
||||
|
||||
``private``
|
||||
Whether this resource is private to the current actor
|
||||
Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=private``
|
||||
|
||||
|
|
@ -652,10 +738,12 @@ The available table extras are listed below.
|
|||
false
|
||||
|
||||
``expandable_columns``
|
||||
Foreign key columns that can be expanded with labels
|
||||
Foreign key columns that can be expanded with labels (See :ref:`expand_foreign_keys` for how to expand these labels.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=expandable_columns``
|
||||
|
||||
Each item is a ``[foreign_key, label_column]`` pair: the foreign key relationship, then the column in the other table that would be used as the label for each expanded value.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
|
|
@ -720,7 +808,7 @@ The following extras are available for row JSON responses.
|
|||
]
|
||||
|
||||
``render_cell``
|
||||
Rendered HTML for each cell using the render_cell plugin hook
|
||||
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
|
||||
|
||||
The ``render_cell`` array has one item for the requested row. The object is keyed by column name. Only columns whose rendered value differs from the default are included.
|
||||
|
||||
|
|
@ -741,7 +829,7 @@ The following extras are available for row JSON responses.
|
|||
}
|
||||
|
||||
``debug``
|
||||
Extra debug information
|
||||
Extra debug information (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``
|
||||
|
||||
|
|
@ -803,17 +891,28 @@ The following extras are available for row JSON responses.
|
|||
}
|
||||
|
||||
``column_types``
|
||||
Column type assignments for this table
|
||||
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>`.)
|
||||
|
||||
``GET /fixtures/facetable/1.json?_extra=column_types``
|
||||
|
||||
This example is from an instance where the ``tags`` column has been assigned the ``json`` column type.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{}
|
||||
{
|
||||
"tags": {
|
||||
"type": "json",
|
||||
"config": null
|
||||
}
|
||||
}
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query
|
||||
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=metadata``
|
||||
|
||||
This table has no metadata, so only an empty ``columns`` object is returned.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
|
|
@ -821,7 +920,26 @@ The following extras are available for row JSON responses.
|
|||
}
|
||||
|
||||
``extras``
|
||||
Available ?_extra= blocks
|
||||
List of ?_extra= blocks that can be used on this page
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "count",
|
||||
"description": "Total count of rows matching these filters",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
|
||||
"selected": false
|
||||
},
|
||||
{
|
||||
"name": "extras",
|
||||
"description": "List of ?_extra= blocks that can be used on this page",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json",
|
||||
"selected": true
|
||||
}
|
||||
]
|
||||
|
||||
``database``
|
||||
Database name
|
||||
|
|
@ -842,7 +960,7 @@ The following extras are available for row JSON responses.
|
|||
"simple_primary_key"
|
||||
|
||||
``database_color``
|
||||
Color assigned to the database
|
||||
Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=database_color``
|
||||
|
||||
|
|
@ -851,7 +969,7 @@ The following extras are available for row JSON responses.
|
|||
"9403e5"
|
||||
|
||||
``private``
|
||||
Whether this resource is private to the current actor
|
||||
Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=private``
|
||||
|
||||
|
|
@ -860,10 +978,12 @@ The following extras are available for row JSON responses.
|
|||
false
|
||||
|
||||
``foreign_key_tables``
|
||||
Tables that link to this row using foreign keys
|
||||
Tables that link to this row using foreign keys (May execute additional queries.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=foreign_key_tables``
|
||||
|
||||
``count`` is the number of rows in the other table that reference this row, and ``link`` is a URL to browse those rows.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
|
|
@ -921,7 +1041,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
]
|
||||
|
||||
``render_cell``
|
||||
Rendered HTML for each cell using the render_cell plugin hook
|
||||
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
|
||||
|
||||
The ``render_cell`` array has one item per query result row, in the same order as the ``rows`` array. Each object is keyed by column name. Only columns whose rendered value differs from the default are included.
|
||||
|
||||
|
|
@ -941,7 +1061,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
}
|
||||
|
||||
``debug``
|
||||
Extra debug information
|
||||
Extra debug information (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``
|
||||
|
||||
|
|
@ -1000,10 +1120,12 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
}
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query
|
||||
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
|
||||
|
||||
``GET /fixtures/neighborhood_search.json?text=town&_extra=metadata``
|
||||
|
||||
For stored queries this returns the full configuration of the query, including the :ref:`stored query options <queries_options>`. For ``?sql=`` queries it returns an empty object.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
|
|
@ -1029,7 +1151,26 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
}
|
||||
|
||||
``extras``
|
||||
Available ?_extra= blocks
|
||||
List of ?_extra= blocks that can be used on this page
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "count",
|
||||
"description": "Total count of rows matching these filters",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
|
||||
"selected": false
|
||||
},
|
||||
{
|
||||
"name": "extras",
|
||||
"description": "List of ?_extra= blocks that can be used on this page",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json",
|
||||
"selected": true
|
||||
}
|
||||
]
|
||||
|
||||
``database``
|
||||
Database name
|
||||
|
|
@ -1041,7 +1182,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
"fixtures"
|
||||
|
||||
``database_color``
|
||||
Color assigned to the database
|
||||
Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
|
||||
|
||||
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=database_color``
|
||||
|
||||
|
|
@ -1050,7 +1191,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
"9403e5"
|
||||
|
||||
``private``
|
||||
Whether this resource is private to the current actor
|
||||
Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
|
||||
|
||||
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=private``
|
||||
|
||||
|
|
|
|||
|
|
@ -93,9 +93,26 @@ async def _fetch_live_examples(scoped_classes):
|
|||
datasette = Datasette(
|
||||
[str(db_path)],
|
||||
settings={"num_sql_threads": 1},
|
||||
metadata={
|
||||
"databases": {
|
||||
"fixtures": {
|
||||
"tables": {
|
||||
"facetable": {
|
||||
"description": "A demo table of places, used to demonstrate facets",
|
||||
"columns": {"state": "Two letter US state code"},
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
config={
|
||||
"databases": {
|
||||
"fixtures": {
|
||||
"tables": {
|
||||
"facetable": {
|
||||
"column_types": {"tags": "json"},
|
||||
}
|
||||
},
|
||||
"queries": {
|
||||
"neighborhood_search": {
|
||||
"sql": textwrap.dedent("""
|
||||
|
|
@ -108,7 +125,7 @@ async def _fetch_live_examples(scoped_classes):
|
|||
"""),
|
||||
"title": "Search neighborhoods",
|
||||
}
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue