diff --git a/datasette/views/database.py b/datasette/views/database.py
index 46a90c4c..7409e7d3 100644
--- a/datasette/views/database.py
+++ b/datasette/views/database.py
@@ -268,12 +268,20 @@ class DatabaseContext(Context):
size: int = field(metadata={"help": "The size of the database in bytes"})
tables: list = field(
metadata={
- "help": "List of table objects in the database. Each item includes a ``count_truncated`` key that is true if ``count`` is a capped lower bound rather than an exact total."
+ "help": "List of table dictionaries in the database. Each item has ``name``, ``columns``, ``primary_keys``, ``count``, ``count_truncated``, ``hidden``, ``fts_table``, ``foreign_keys`` and ``private`` keys. ``count_truncated`` is true if ``count`` is a capped lower bound rather than an exact total."
}
)
hidden_count: int = field(metadata={"help": "Count of hidden tables"})
- views: list = field(metadata={"help": "List of view objects in the database"})
- queries: list = field(metadata={"help": "List of stored query objects"})
+ views: list = field(
+ metadata={
+ "help": "List of SQLite view dictionaries. Each item has ``name`` and ``private`` keys."
+ }
+ )
+ queries: list = field(
+ metadata={
+ "help": "List of stored query objects. Each has attributes including ``name``, ``sql``, ``title``, ``description``, ``description_html``, ``hide_sql``, ``fragment``, ``parameters``, ``is_write`` and ``private``."
+ }
+ )
queries_more: bool = field(
metadata={"help": "Boolean indicating if more stored queries are available"}
)
@@ -282,16 +290,24 @@ class DatabaseContext(Context):
metadata={"help": "Boolean indicating if custom SQL can be executed"}
)
table_columns: dict = field(
- metadata={"help": "Dictionary mapping table names to their column lists"}
+ metadata={
+ "help": "Dictionary mapping table names to lists of column names, used to power SQL autocomplete."
+ }
+ )
+ metadata: dict = field(
+ metadata={
+ "help": "Metadata dictionary for the database, such as ``title``, ``description``, ``license`` and ``source`` values from Datasette metadata."
+ }
)
- metadata: dict = field(metadata={"help": "Metadata for the database"})
database_color: str = field(metadata={"help": "The color assigned to the database"})
database_page_data: dict = field(
- metadata={"help": "JSON data used by JavaScript on the database page"}
+ metadata={
+ "help": 'JSON data used by JavaScript on the database page. Currently ``{}`` or ``{"createTable": {...}}`` where ``createTable`` includes ``path``, ``foreignKeyTargetsPath``, ``databaseName``, ``columnTypes``, ``defaultExpressions`` and optional ``customColumnTypes``.'
+ }
)
database_actions: callable = field(
metadata={
- "help": "Callable returning list of action links for the database menu"
+ "help": 'Async callable returning action items for the database menu. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions` and :ref:`plugin_hook_database_actions`.'
}
)
show_hidden: str = field(metadata={"help": "Value of _show_hidden query parameter"})
@@ -302,18 +318,22 @@ class DatabaseContext(Context):
metadata={"help": "Boolean indicating if database download is allowed"}
)
attached_databases: list = field(
- metadata={"help": "List of names of attached databases"}
+ metadata={
+ "help": "List of names of databases attached to this SQLite connection. This is only populated for the special ``/_memory`` database when Datasette is started with ``--crossdb`` for :ref:`cross_database_queries`."
+ }
)
alternate_url_json: str = field(
metadata={"help": "URL for the alternate JSON version of this page"}
)
select_templates: list = field(
metadata={
- "help": "List of templates that were considered for rendering this page"
+ "help": "List of template names that were considered for this page, with the selected template prefixed by ``*``."
}
)
top_database: callable = field(
- metadata={"help": "Callable to render the top_database slot"}
+ metadata={
+ "help": "Async callable that renders the ``top_database`` plugin slot for this database and returns HTML."
+ }
)
@@ -326,7 +346,9 @@ class QueryContext(Context):
database: str = field(metadata={"help": "The name of the database being queried"})
database_color: str = field(metadata={"help": "The color of the database"})
query: dict = field(
- metadata={"help": "The SQL query object containing the `sql` string"}
+ metadata={
+ "help": "Dictionary describing the SQL query being executed, with ``sql`` and ``params`` keys."
+ }
)
stored_query: str = field(
metadata={"help": "The name of the stored query if this is a stored query"}
@@ -343,7 +365,9 @@ class QueryContext(Context):
}
)
metadata: dict = field(
- metadata={"help": "Metadata about the database or the stored query"}
+ metadata={
+ "help": "Metadata dictionary for the database or stored query. Stored query metadata may include options such as ``hide_sql``, ``on_success_message`` and ``on_error_redirect``."
+ }
)
db_is_immutable: bool = field(
metadata={"help": "Boolean indicating if this database is immutable"}
@@ -369,24 +393,42 @@ class QueryContext(Context):
)
tables: list = field(
metadata={
- "help": "List of table objects in the database. Each item includes a ``count_truncated`` key that is true if ``count`` is a capped lower bound rather than an exact total."
+ "help": "List of table dictionaries in the database. Each item has ``name``, ``columns``, ``primary_keys``, ``count``, ``count_truncated``, ``hidden``, ``fts_table``, ``foreign_keys`` and ``private`` keys. ``count_truncated`` is true if ``count`` is a capped lower bound rather than an exact total."
}
)
named_parameter_values: dict = field(
- metadata={"help": "Dictionary of parameter names/values"}
+ metadata={
+ "help": "Dictionary of named SQL parameter values, keyed by parameter name without the leading ``:``."
+ }
)
edit_sql_url: str = field(
metadata={"help": "URL to edit the SQL for a stored query"}
)
- display_rows: list = field(metadata={"help": "List of result rows to display"})
- columns: list = field(metadata={"help": "List of column names"})
- renderers: dict = field(metadata={"help": "Dictionary of renderer name to URL"})
+ display_rows: list = field(
+ metadata={
+ "help": "List of result rows formatted for HTML display. Each row is a list of rendered cell values in the same order as ``columns``."
+ }
+ )
+ columns: list = field(
+ metadata={
+ "help": "List of result column names in the order they appear in ``display_rows`` and ``rows``."
+ }
+ )
+ renderers: dict = field(
+ metadata={
+ "help": "Dictionary mapping output format names such as ``json`` to URLs for this query in that format."
+ }
+ )
url_csv: str = field(metadata={"help": "URL for CSV export"})
show_hide_hidden: str = field(
- metadata={"help": "Hidden input field for the _show_sql parameter"}
+ metadata={
+ "help": "Rendered hidden ```` HTML preserving the current ``_hide_sql`` or ``_show_sql`` state."
+ }
)
table_columns: dict = field(
- metadata={"help": "Dictionary of table name to list of column names"}
+ metadata={
+ "help": "Dictionary mapping table names to lists of column names, used to power SQL autocomplete."
+ }
)
alternate_url_json: str = field(
metadata={"help": "URL for alternate JSON version of this page"}
@@ -394,18 +436,22 @@ class QueryContext(Context):
# TODO: refactor this to somewhere else, probably ds.render_template()
select_templates: list = field(
metadata={
- "help": "List of templates that were considered for rendering this page"
+ "help": "List of template names that were considered for this page, with the selected template prefixed by ``*``."
}
)
top_query: callable = field(
- metadata={"help": "Callable to render the top_query slot"}
+ metadata={
+ "help": "Async callable that renders the ``top_query`` plugin slot for this query and returns HTML."
+ }
)
top_stored_query: callable = field(
- metadata={"help": "Callable to render the top_stored_query slot"}
+ metadata={
+ "help": "Async callable that renders the ``top_stored_query`` plugin slot for stored queries and returns HTML."
+ }
)
query_actions: callable = field(
metadata={
- "help": "Callable returning a list of links for the query action menu"
+ "help": 'Async callable returning action items for the query menu. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions` and :ref:`plugin_hook_query_actions`.'
}
)
diff --git a/datasette/views/row.py b/datasette/views/row.py
index e7472773..7802f45e 100644
--- a/datasette/views/row.py
+++ b/datasette/views/row.py
@@ -50,7 +50,7 @@ class RowContext(Context):
)
rows: list = field(
metadata={
- "help": "The rows for this page, as a list of dictionaries mapping column name to value"
+ "help": "A single-item list containing this row as a dictionary mapping column name to raw value."
}
)
primary_key_values: list = field(
@@ -62,48 +62,58 @@ class RowContext(Context):
}
)
display_columns: list = field(
- metadata={"help": "Column objects formatted for the HTML table display"}
+ metadata={
+ "help": "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."
+ }
)
display_rows: list = field(
- metadata={"help": "Row data formatted for the HTML table display"}
+ metadata={
+ "help": "Rows formatted for the HTML table display. Each row is iterable and contains cell dictionaries with ``column``, ``value``, ``raw`` and ``value_type`` keys."
+ }
)
custom_table_templates: list = field(
metadata={
- "help": "Custom template names that were considered for displaying this table"
+ "help": "Custom template names that were considered for displaying this row's table, in lookup order."
}
)
row_actions: list = field(
- metadata={"help": "Row actions made available by plugin hooks"}
- )
- row_mutation_ui: bool = field(
metadata={
- "help": "True if the row edit/delete JavaScript UI should be enabled"
+ "help": 'Row actions made available by core and plugin hooks. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions` and :ref:`plugin_hook_row_actions`.'
}
)
+ row_mutation_ui: bool = field(
+ metadata={"help": "True if the row edit/delete JavaScript UI should be enabled"}
+ )
table_page_data: dict = field(
- metadata={"help": "JSON data used by JavaScript on the row page"}
+ metadata={
+ "help": "JSON data used by JavaScript on the row page. Includes ``database``, ``table`` and ``tableUrl``, plus optional ``foreignKeys`` mapping column names to autocomplete URLs."
+ }
)
top_row: callable = field(
- metadata={"help": "Async function rendering the top_row plugin slot"}
+ metadata={
+ "help": "Async callable that renders the ``top_row`` plugin slot for this row and returns HTML."
+ }
)
renderers: dict = field(
metadata={
- "help": "Dictionary mapping output format names (e.g. json) to their URLs for this page"
+ "help": "Dictionary mapping output format names such as ``json`` to URLs for this row in that format."
}
)
url_csv: str = field(metadata={"help": "URL for the CSV export of this page"})
url_csv_path: str = field(metadata={"help": "Path portion of the CSV export URL"})
url_csv_hidden_args: list = field(
metadata={
- "help": "(name, value) pairs for hidden form fields used by the CSV export form"
+ "help": "List of ``(name, value)`` pairs for hidden form fields used by the CSV export form, preserving current options while forcing ``_size=max``."
}
)
settings: dict = field(
- metadata={"help": "Dictionary of Datasette's current settings"}
+ metadata={
+ "help": "Dictionary of Datasette's current settings, keyed by setting name."
+ }
)
select_templates: list = field(
metadata={
- "help": "List of template names that were considered for this page, the one used marked with an asterisk"
+ "help": "List of template names that were considered for this page, with the selected template prefixed by ``*``."
}
)
alternate_url_json: str = field(
diff --git a/datasette/views/table.py b/datasette/views/table.py
index 38a69f5f..4b6899b2 100644
--- a/datasette/views/table.py
+++ b/datasette/views/table.py
@@ -120,25 +120,27 @@ class TableContext(Context):
)
rows: list = field(
metadata={
- "help": "The rows for this page, as a list of dictionaries mapping column name to value"
+ "help": "The rows for this page, as a list of dictionaries mapping column name to raw value."
}
)
filter_columns: list = field(
- metadata={"help": "List of columns offered by the filter interface"}
+ metadata={
+ "help": "List of column names offered by the filter interface, including currently displayed columns and any hidden columns that can still be filtered."
+ }
)
supports_search: bool = field(
metadata={"help": "True if this table has full-text search configured"}
)
extra_wheres_for_ui: list = field(
metadata={
- "help": "Extra where clauses from ?_where=, with links to remove them"
+ "help": "Extra where clauses from ``?_where=`` for display in the UI. Each item has ``text`` for the SQL fragment and ``remove_url`` for a URL that removes that fragment."
}
)
url_csv: str = field(metadata={"help": "URL for the CSV export of this page"})
url_csv_path: str = field(metadata={"help": "Path portion of the CSV export URL"})
url_csv_hidden_args: list = field(
metadata={
- "help": "(name, value) pairs for hidden form fields used by the CSV export form"
+ "help": "List of ``(name, value)`` pairs for hidden form fields used by the CSV export form, preserving current filters while forcing ``_size=max``."
}
)
sort: str = field(metadata={"help": "Column the page is sorted by, or None"})
@@ -147,19 +149,23 @@ class TableContext(Context):
)
append_querystring: callable = field(
metadata={
- "help": "Function that appends additional querystring arguments to a URL"
+ "help": "Function ``append_querystring(url, querystring)`` that appends additional query string arguments to a URL, using ``?`` or ``&`` as appropriate."
}
)
path_with_replaced_args: callable = field(
metadata={
- "help": "Function for building the current path with modified querystring arguments"
+ "help": "Function for building the current path with modified query string arguments. Pass the current ``request`` and a dictionary of argument names to replacement values, using ``None`` to remove an argument."
}
)
fix_path: callable = field(
- metadata={"help": "Function that applies the base_url prefix to a path"}
+ metadata={
+ "help": "Function that applies the configured ``base_url`` prefix to a path."
+ }
)
settings: dict = field(
- metadata={"help": "Dictionary of Datasette's current settings"}
+ metadata={
+ "help": "Dictionary of Datasette's current settings, keyed by setting name."
+ }
)
alternate_url_json: str = field(
metadata={"help": "URL for the JSON version of this page"}
@@ -184,14 +190,18 @@ class TableContext(Context):
)
select_templates: list = field(
metadata={
- "help": "List of template names that were considered for this page, the one used marked with an asterisk"
+ "help": "List of template names that were considered for this page, with the selected template prefixed by ``*``."
}
)
top_table: callable = field(
- metadata={"help": "Async function rendering the top_table plugin slot"}
+ metadata={
+ "help": "Async callable that renders the ``top_table`` plugin slot for this table or view and returns HTML."
+ }
)
table_page_data: dict = field(
- metadata={"help": "JSON data used by JavaScript on the table page"}
+ metadata={
+ "help": "JSON data used by JavaScript on the table page. Includes ``database``, ``table`` and ``tableUrl``, plus optional ``foreignKeys`` mapping column names to autocomplete URLs, optional ``insertRow`` data and optional ``alterTable`` data."
+ }
)
diff --git a/datasette/views/table_extras.py b/datasette/views/table_extras.py
index f688433d..db659c80 100644
--- a/datasette/views/table_extras.py
+++ b/datasette/views/table_extras.py
@@ -98,7 +98,7 @@ class QueryExtraContext:
class CountSqlExtra(Extra):
- description = "SQL query used to calculate the total count"
+ description = "SQL query string used to calculate the total count for the current table view, including active filters."
example = ExtraExample("/fixtures/facetable.json?_size=0&_extra=count_sql")
scopes = {ExtraScope.TABLE}
@@ -165,7 +165,7 @@ class FacetInstancesProvider(Provider):
class FacetResultsExtra(Extra):
- description = "Results of facets calculated against this data"
+ description = "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``."
example = ExtraExample(
value={
"results": {
@@ -214,7 +214,9 @@ class FacetResultsExtra(Extra):
class FacetsTimedOutExtra(Extra):
- description = "Facet calculations that timed out"
+ description = (
+ "List of names of facet calculations that exceeded the facet time limit."
+ )
example = ExtraExample(
"/fixtures/facetable.json?_facet=state&_extra=facets_timed_out",
note=(
@@ -230,7 +232,7 @@ class FacetsTimedOutExtra(Extra):
class SuggestedFacetsExtra(Extra):
- description = "Suggestions for facets that might return interesting results"
+ description = "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."
example = ExtraExample(
value=[
{
@@ -301,7 +303,7 @@ class NextUrlExtra(Extra):
class ColumnsExtra(Extra):
- description = "Column names returned by this query"
+ description = "List of column names returned by this table, row or query."
example = ExtraExample("/fixtures/facetable.json?_extra=columns")
examples = {
ExtraScope.ROW: ExtraExample(
@@ -318,7 +320,7 @@ class ColumnsExtra(Extra):
class AllColumnsExtra(Extra):
- description = "All columns in the table, regardless of _col/_nocol filtering"
+ description = "List of all column names in the table, regardless of ``_col=`` or ``_nocol=`` filtering."
example = ExtraExample("/fixtures/facetable.json?_col=pk&_extra=all_columns")
scopes = {ExtraScope.TABLE}
@@ -327,7 +329,7 @@ class AllColumnsExtra(Extra):
class PrimaryKeysExtra(Extra):
- description = "Primary keys for this table"
+ description = "List of primary key column names for this table, or an empty list if the table has no explicit primary key."
example = ExtraExample("/fixtures/facetable.json?_extra=primary_keys")
examples = {
ExtraScope.ROW: ExtraExample(
@@ -341,7 +343,7 @@ class PrimaryKeysExtra(Extra):
class ActionsExtra(Extra):
- description = "Table or view actions made available by plugin hooks"
+ description = 'Async callable returning table or view actions made available by core and plugin hooks. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions`, :ref:`plugin_hook_table_actions` and :ref:`plugin_hook_view_actions`.'
scopes = {ExtraScope.TABLE}
# Returns an async function for the HTML templates - not JSON serializable
public = False
@@ -421,7 +423,7 @@ class IsViewExtra(Extra):
class DebugExtra(Extra):
- description = "Extra debug information"
+ description = "Extra debug information dictionary. This is intended for development only and its shape is not part of the stable template contract."
docs_note = (
"The contents of this block are not a stable part of the Datasette "
"API and may change without warning."
@@ -457,7 +459,7 @@ class DebugExtra(Extra):
class RequestExtra(Extra):
- description = "Full information about the request"
+ description = "Dictionary with request details: ``url``, ``path``, ``full_path``, ``host`` and ``args`` where ``args`` maps query string parameter names to their values."
example = ExtraExample("/fixtures/facetable.json?_extra=request")
examples = {
ExtraScope.ROW: ExtraExample(
@@ -501,7 +503,7 @@ class DisplayColumnsAndRowsProvider(Provider):
class DisplayColumnsExtra(Extra):
- description = "Column metadata used by the HTML table display"
+ description = "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."
example = ExtraExample(
value=[
{
@@ -531,7 +533,7 @@ class DisplayColumnsExtra(Extra):
class DisplayRowsExtra(Extra):
- description = "Row data formatted for the HTML table display"
+ description = "Rows formatted for the HTML table display. Each row is iterable and contains cell dictionaries with ``column``, ``value``, ``raw`` and ``value_type`` keys; table pages may also provide ``pk_path``, ``row_path`` and ``row_label`` attributes on each row object."
scopes = {ExtraScope.TABLE}
# Contains markupsafe/sqlite3.Row values - not JSON serializable
public = False
@@ -640,7 +642,7 @@ class RenderCellExtra(Extra):
class QueryExtra(Extra):
- description = "Details of the underlying SQL query"
+ description = "Details of the underlying SQL query as a dictionary with ``sql`` and ``params`` keys."
example = ExtraExample("/fixtures/facetable.json?_size=1&_extra=query")
examples = {
ExtraScope.ROW: ExtraExample(
@@ -661,7 +663,7 @@ class QueryExtra(Extra):
class ColumnTypesExtra(Extra):
- description = "Column type assignments for this table"
+ description = 'Column type assignments for this table. A dictionary mapping column names to ``{"type": type_name, "config": config}`` dictionaries.'
docs_note = (
"An empty object if no column types have been assigned. Column types "
"can be assigned in :ref:`configuration "
@@ -700,7 +702,7 @@ class ColumnTypesExtra(Extra):
class SetColumnTypeUiExtra(Extra):
- description = "Information needed to build an interface for assigning column types"
+ description = "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."
docs_note = (
"``null`` unless the current actor is allowed to use the :ref:`set "
"column type API ` for this table."
@@ -784,7 +786,7 @@ class SetColumnTypeUiExtra(Extra):
class MetadataExtra(Extra):
- description = "Metadata about the table, database or stored query"
+ description = "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."
docs_note = "See :ref:`metadata` for how to attach metadata to tables."
example = ExtraExample(
"/fixtures/facetable.json?_extra=metadata",
@@ -891,7 +893,7 @@ class DatabaseColorExtra(Extra):
class FormHiddenArgsExtra(Extra):
- description = "Hidden form arguments used by the HTML table interface"
+ description = "List of ``(name, value)`` pairs for hidden form fields used by the HTML table interface to preserve current query string options."
example = ExtraExample(
"/fixtures/facetable.json?_facet=state&_size=1&_extra=form_hidden_args"
)
@@ -911,7 +913,7 @@ class FormHiddenArgsExtra(Extra):
class FiltersExtra(Extra):
- description = "Filters object used by the HTML table interface"
+ description = "``Filters`` object used by the HTML table interface. Useful methods include ``filters.human_description_en()``; this is not JSON serializable."
scopes = {ExtraScope.TABLE}
# Returns a Filters instance for the HTML templates - not JSON serializable
public = False
@@ -921,7 +923,7 @@ class FiltersExtra(Extra):
class CustomTableTemplatesExtra(Extra):
- description = "Custom template names considered for this table"
+ description = "List of custom template names considered for rendering table rows, in lookup order."
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 "
@@ -939,7 +941,7 @@ class CustomTableTemplatesExtra(Extra):
class SortedFacetResultsExtra(Extra):
- description = "Facet results sorted for display"
+ description = "Facet result dictionaries sorted for display. Each item has the same shape as an entry from ``facet_results['results']``."
docs_note = (
"The same data as ``facet_results``, as a list in the order used by "
"the HTML interface: facets from :ref:`facet configuration "
@@ -1001,7 +1003,7 @@ class ViewDefinitionExtra(Extra):
class RenderersExtra(Extra):
- description = "Alternative output renderers available for this table"
+ description = "Dictionary mapping output format names such as ``json`` or plugin-provided renderer names to URLs for this data in that format."
example = ExtraExample(
"/fixtures/facetable.json?_extra=renderers",
note=(
@@ -1068,7 +1070,7 @@ class PrivateExtra(Extra):
class ExpandableColumnsExtra(Extra):
- description = "Foreign key columns that can be expanded with labels"
+ description = "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``."
docs_note = "See :ref:`expand_foreign_keys` for how to expand these labels."
example = ExtraExample(
"/fixtures/facetable.json?_extra=expandable_columns",
@@ -1090,7 +1092,7 @@ class ExpandableColumnsExtra(Extra):
class ForeignKeyTablesExtra(Extra):
- description = "Tables that link to this row using foreign keys"
+ description = "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."
example = ExtraExample(
"/fixtures/simple_primary_key/1.json?_extra=foreign_key_tables",
note=(
@@ -1108,7 +1110,7 @@ class ForeignKeyTablesExtra(Extra):
class ExtrasExtra(Extra):
- description = "List of ?_extra= blocks that can be used on this page"
+ description = "List of ``?_extra=`` blocks that can be used on this page. Each item has ``name``, ``description``, ``toggle_url`` and ``selected`` keys."
example = ExtraExample(
value=[
{
diff --git a/docs/template_context.rst b/docs/template_context.rst
index dd4524f0..b09fc3a1 100644
--- a/docs/template_context.rst
+++ b/docs/template_context.rst
@@ -95,19 +95,19 @@ The page listing the tables, views and queries in a database, e.g. /fixtures. Re
URL for the alternate JSON version of this page
``attached_databases`` - ``list``
- List of names of attached databases
+ List of names of databases attached to this SQLite connection. This is only populated for the special ``/_memory`` database when Datasette is started with ``--crossdb`` for :ref:`cross_database_queries`.
``database`` - ``str``
The name of the database
``database_actions`` - ``callable``
- Callable returning list of action links for the database menu
+ Async callable returning action items for the database menu. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions` and :ref:`plugin_hook_database_actions`.
``database_color`` - ``str``
The color assigned to the database
``database_page_data`` - ``dict``
- JSON data used by JavaScript on the database page
+ JSON data used by JavaScript on the database page. Currently ``{}`` or ``{"createTable": {...}}`` where ``createTable`` includes ``path``, ``foreignKeyTargetsPath``, ``databaseName``, ``columnTypes``, ``defaultExpressions`` and optional ``customColumnTypes``.
``editable`` - ``bool``
Boolean indicating if the database is editable
@@ -116,7 +116,7 @@ The page listing the tables, views and queries in a database, e.g. /fixtures. Re
Count of hidden tables
``metadata`` - ``dict``
- Metadata for the database
+ Metadata dictionary for the database, such as ``title``, ``description``, ``license`` and ``source`` values from Datasette metadata.
``path`` - ``str``
The URL path to this database
@@ -125,7 +125,7 @@ The page listing the tables, views and queries in a database, e.g. /fixtures. Re
Boolean indicating if this is a private database
``queries`` - ``list``
- List of stored query objects
+ List of stored query objects. Each has attributes including ``name``, ``sql``, ``title``, ``description``, ``description_html``, ``hide_sql``, ``fragment``, ``parameters``, ``is_write`` and ``private``.
``queries_count`` - ``int``
Count of visible stored queries
@@ -134,7 +134,7 @@ The page listing the tables, views and queries in a database, e.g. /fixtures. Re
Boolean indicating if more stored queries are available
``select_templates`` - ``list``
- List of templates that were considered for rendering this page
+ List of template names that were considered for this page, with the selected template prefixed by ``*``.
``show_hidden`` - ``str``
Value of _show_hidden query parameter
@@ -143,16 +143,16 @@ The page listing the tables, views and queries in a database, e.g. /fixtures. Re
The size of the database in bytes
``table_columns`` - ``dict``
- Dictionary mapping table names to their column lists
+ Dictionary mapping table names to lists of column names, used to power SQL autocomplete.
``tables`` - ``list``
- List of table objects in the database. Each item includes a ``count_truncated`` key that is true if ``count`` is a capped lower bound rather than an exact total.
+ List of table dictionaries in the database. Each item has ``name``, ``columns``, ``primary_keys``, ``count``, ``count_truncated``, ``hidden``, ``fts_table``, ``foreign_keys`` and ``private`` keys. ``count_truncated`` is true if ``count`` is a capped lower bound rather than an exact total.
``top_database`` - ``callable``
- Callable to render the top_database slot
+ Async callable that renders the ``top_database`` plugin slot for this database and returns HTML.
``views`` - ``list``
- List of view objects in the database
+ List of SQLite view dictionaries. Each item has ``name`` and ``private`` keys.
Query page
----------
@@ -166,7 +166,7 @@ The page for arbitrary SQL queries (/database/-/query?sql=...) and stored querie
URL for alternate JSON version of this page
``columns`` - ``list``
- List of column names
+ List of result column names in the order they appear in ``display_rows`` and ``rows``.
``database`` - ``str``
The name of the database being queried
@@ -178,7 +178,7 @@ The page for arbitrary SQL queries (/database/-/query?sql=...) and stored querie
Boolean indicating if this database is immutable
``display_rows`` - ``list``
- List of result rows to display
+ List of result rows formatted for HTML display. Each row is a list of rendered cell values in the same order as ``columns``.
``edit_sql_url`` - ``str``
URL to edit the SQL for a stored query
@@ -193,31 +193,31 @@ The page for arbitrary SQL queries (/database/-/query?sql=...) and stored querie
Boolean indicating if the SQL should be hidden
``metadata`` - ``dict``
- Metadata about the database or the stored query
+ Metadata dictionary for the database or stored query. Stored query metadata may include options such as ``hide_sql``, ``on_success_message`` and ``on_error_redirect``.
``named_parameter_values`` - ``dict``
- Dictionary of parameter names/values
+ Dictionary of named SQL parameter values, keyed by parameter name without the leading ``:``.
``private`` - ``bool``
Boolean indicating if this is a private database
``query`` - ``dict``
- The SQL query object containing the `sql` string
+ Dictionary describing the SQL query being executed, with ``sql`` and ``params`` keys.
``query_actions`` - ``callable``
- Callable returning a list of links for the query action menu
+ Async callable returning action items for the query menu. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions` and :ref:`plugin_hook_query_actions`.
``renderers`` - ``dict``
- Dictionary of renderer name to URL
+ Dictionary mapping output format names such as ``json`` to URLs for this query in that format.
``save_query_url`` - ``str``
URL to save the current arbitrary SQL as a query
``select_templates`` - ``list``
- List of templates that were considered for rendering this page
+ List of template names that were considered for this page, with the selected template prefixed by ``*``.
``show_hide_hidden`` - ``str``
- Hidden input field for the _show_sql parameter
+ Rendered hidden ```` HTML preserving the current ``_hide_sql`` or ``_show_sql`` state.
``show_hide_link`` - ``str``
The URL to toggle showing/hiding the SQL
@@ -232,16 +232,16 @@ The page for arbitrary SQL queries (/database/-/query?sql=...) and stored querie
Boolean indicating if this is a stored query that allows writes
``table_columns`` - ``dict``
- Dictionary of table name to list of column names
+ Dictionary mapping table names to lists of column names, used to power SQL autocomplete.
``tables`` - ``list``
- List of table objects in the database. Each item includes a ``count_truncated`` key that is true if ``count`` is a capped lower bound rather than an exact total.
+ List of table dictionaries in the database. Each item has ``name``, ``columns``, ``primary_keys``, ``count``, ``count_truncated``, ``hidden``, ``fts_table``, ``foreign_keys`` and ``private`` keys. ``count_truncated`` is true if ``count`` is a capped lower bound rather than an exact total.
``top_query`` - ``callable``
- Callable to render the top_query slot
+ Async callable that renders the ``top_query`` plugin slot for this query and returns HTML.
``top_stored_query`` - ``callable``
- Callable to render the top_stored_query slot
+ Async callable that renders the ``top_stored_query`` plugin slot for stored queries and returns HTML.
``url_csv`` - ``str``
URL for CSV export
@@ -254,10 +254,10 @@ The page showing the rows in a table or SQL view, e.g. /fixtures/facetable. Rend
Many of these keys are shared with the :ref:`JSON API ` for this page.
``actions`` - ``callable``
- Table or view actions made available by plugin hooks
+ Async callable returning table or view actions made available by core and plugin hooks. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions`, :ref:`plugin_hook_table_actions` and :ref:`plugin_hook_view_actions`.
``all_columns`` - ``list``
- All columns in the table, regardless of _col/_nocol filtering
+ List of all column names in the table, regardless of ``_col=`` or ``_nocol=`` filtering.
``allow_execute_sql`` - ``bool``
True if the current actor can execute custom SQL against this database
@@ -266,22 +266,22 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
URL for the JSON version of this page
``append_querystring`` - ``callable``
- Function that appends additional querystring arguments to a URL
+ Function ``append_querystring(url, querystring)`` that appends additional query string arguments to a URL, using ``?`` or ``&`` as appropriate.
``columns`` - ``list``
- Column names returned by this query
+ List of column names returned by this table, row or query.
``count`` - ``int``
Total count of rows matching these filters
``count_sql`` - ``str``
- 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.
``count_truncated`` - ``bool``
True if ``count`` is a capped lower bound rather than an exact total, because Datasette stopped counting after its configured row-count limit.
``custom_table_templates`` - ``list``
- Custom template names considered for this table
+ List of custom template names considered for rendering table rows, in lookup order.
``database`` - ``str``
Database name
@@ -293,34 +293,34 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
The string "true" or "false" reflecting the allow_facet setting
``display_columns`` - ``list``
- 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.
``display_rows`` - ``list``
- Row data formatted for the HTML table display
+ Rows formatted for the HTML table display. Each row is iterable and contains cell dictionaries with ``column``, ``value``, ``raw`` and ``value_type`` keys; table pages may also provide ``pk_path``, ``row_path`` and ``row_label`` attributes on each row object.
``expandable_columns`` - ``list``
- Foreign key columns that can be expanded with 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``.
``extra_wheres_for_ui`` - ``list``
- Extra where clauses from ?_where=, with links to remove them
+ Extra where clauses from ``?_where=`` for display in the UI. Each item has ``text`` for the SQL fragment and ``remove_url`` for a URL that removes that fragment.
``facet_results`` - ``dict``
- Results of facets calculated against this data
+ 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``.
``facets_timed_out`` - ``list``
- Facet calculations that timed out
+ List of names of facet calculations that exceeded the facet time limit.
``filter_columns`` - ``list``
- List of columns offered by the filter interface
+ List of column names offered by the filter interface, including currently displayed columns and any hidden columns that can still be filtered.
``filters`` - ``Filters``
- Filters object used by the HTML table interface
+ ``Filters`` object used by the HTML table interface. Useful methods include ``filters.human_description_en()``; this is not JSON serializable.
``fix_path`` - ``callable``
- Function that applies the base_url prefix to a path
+ Function that applies the configured ``base_url`` prefix to a path.
``form_hidden_args`` - ``list``
- 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.
``human_description_en`` - ``str``
Human-readable description of the filters
@@ -332,7 +332,7 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
Whether this resource is a view instead of a table
``metadata`` - ``dict``
- Metadata about the table, database or stored query
+ 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.
``next`` - ``str``
Pagination token for the next page, or None
@@ -344,34 +344,34 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
True if the data for this page was retrieved without errors
``path_with_replaced_args`` - ``callable``
- Function for building the current path with modified querystring arguments
+ Function for building the current path with modified query string arguments. Pass the current ``request`` and a dictionary of argument names to replacement values, using ``None`` to remove an argument.
``primary_keys`` - ``list``
- 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.
``private`` - ``bool``
Whether this resource is private to the current actor
``query`` - ``dict``
- Details of the underlying SQL query
+ Details of the underlying SQL query as a dictionary with ``sql`` and ``params`` keys.
``query_ms`` - ``float``
Time taken by the SQL queries for this page, in milliseconds
``renderers`` - ``dict``
- 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.
``rows`` - ``list``
- The rows for this page, as a list of dictionaries mapping column name to value
+ The rows for this page, as a list of dictionaries mapping column name to raw value.
``select_templates`` - ``list``
- List of template names that were considered for this page, the one used marked with an asterisk
+ List of template names that were considered for this page, with the selected template prefixed by ``*``.
``set_column_type_ui`` - ``dict``
- Information needed to build an interface for assigning column types
+ 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.
``settings`` - ``dict``
- Dictionary of Datasette's current settings
+ Dictionary of Datasette's current settings, keyed by setting name.
``sort`` - ``str``
Column the page is sorted by, or None
@@ -380,10 +380,10 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
Column the page is sorted by in descending order, or None
``sorted_facet_results`` - ``list``
- Facet results sorted for display
+ Facet result dictionaries sorted for display. Each item has the same shape as an entry from ``facet_results['results']``.
``suggested_facets`` - ``list``
- Suggestions for facets that might return interesting results
+ 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.
``supports_search`` - ``bool``
True if this table has full-text search configured
@@ -395,16 +395,16 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
SQL definition for this table
``table_page_data`` - ``dict``
- JSON data used by JavaScript on the table page
+ JSON data used by JavaScript on the table page. Includes ``database``, ``table`` and ``tableUrl``, plus optional ``foreignKeys`` mapping column names to autocomplete URLs, optional ``insertRow`` data and optional ``alterTable`` data.
``top_table`` - ``callable``
- Async function rendering the top_table plugin slot
+ Async callable that renders the ``top_table`` plugin slot for this table or view and returns HTML.
``url_csv`` - ``str``
URL for the CSV export of this page
``url_csv_hidden_args`` - ``list``
- (name, value) pairs for hidden form fields used by the CSV export form
+ List of ``(name, value)`` pairs for hidden form fields used by the CSV export form, preserving current filters while forcing ``_size=max``.
``url_csv_path`` - ``str``
Path portion of the CSV export URL
@@ -423,10 +423,10 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
URL for the JSON version of this page
``columns`` - ``list``
- Column names returned by this query
+ List of column names returned by this table, row or query.
``custom_table_templates`` - ``list``
- Custom template names that were considered for displaying this table
+ Custom template names that were considered for displaying this row's table, in lookup order.
``database`` - ``str``
Database name
@@ -435,16 +435,16 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
Color assigned to the database
``display_columns`` - ``list``
- Column objects formatted for 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.
``display_rows`` - ``list``
- Row data formatted for the HTML table display
+ Rows formatted for the HTML table display. Each row is iterable and contains cell dictionaries with ``column``, ``value``, ``raw`` and ``value_type`` keys.
``foreign_key_tables`` - ``list``
- Tables that link to this row using foreign keys
+ 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.
``metadata`` - ``dict``
- Metadata about the table, database or stored query
+ 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.
``ok`` - ``bool``
True if the data for this page was retrieved without errors
@@ -453,7 +453,7 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
Values of the primary keys for this row, from the URL
``primary_keys`` - ``list``
- 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.
``private`` - ``bool``
Whether this resource is private to the current actor
@@ -462,37 +462,37 @@ Many of these keys are shared with the :ref:`JSON API ` for this page.
Time taken by the SQL queries for this page, in milliseconds
``renderers`` - ``dict``
- Dictionary mapping output format names (e.g. json) to their URLs for this page
+ Dictionary mapping output format names such as ``json`` to URLs for this row in that format.
``row_actions`` - ``list``
- Row actions made available by plugin hooks
+ Row actions made available by core and plugin hooks. Each item is either a link with ``href``, ``label`` and optional ``description`` keys, or a button with ``type: "button"``, ``label``, optional ``description`` and optional ``attrs``. See :ref:`plugin_actions` and :ref:`plugin_hook_row_actions`.
``row_mutation_ui`` - ``bool``
True if the row edit/delete JavaScript UI should be enabled
``rows`` - ``list``
- The rows for this page, as a list of dictionaries mapping column name to value
+ A single-item list containing this row as a dictionary mapping column name to raw value.
``select_templates`` - ``list``
- List of template names that were considered for this page, the one used marked with an asterisk
+ List of template names that were considered for this page, with the selected template prefixed by ``*``.
``settings`` - ``dict``
- Dictionary of Datasette's current settings
+ Dictionary of Datasette's current settings, keyed by setting name.
``table`` - ``str``
Table name
``table_page_data`` - ``dict``
- JSON data used by JavaScript on the row page
+ JSON data used by JavaScript on the row page. Includes ``database``, ``table`` and ``tableUrl``, plus optional ``foreignKeys`` mapping column names to autocomplete URLs.
``top_row`` - ``callable``
- Async function rendering the top_row plugin slot
+ Async callable that renders the ``top_row`` plugin slot for this row and returns HTML.
``url_csv`` - ``str``
URL for the CSV export of this page
``url_csv_hidden_args`` - ``list``
- (name, value) pairs for hidden form fields used by the CSV export form
+ List of ``(name, value)`` pairs for hidden form fields used by the CSV export form, preserving current options while forcing ``_size=max``.
``url_csv_path`` - ``str``
Path portion of the CSV export URL