mirror of
https://github.com/simonw/datasette.git
synced 2026-05-31 22:27:00 +02:00
Rename canned queries to queries/stored queries in docs
This commit is contained in:
Simon Willison
parent
0cadd07187
commit
4bf1c4b065
17 changed files with 144 additions and 101 deletions
|
|
@ -121,13 +121,13 @@ def register_actions():
|
|||
Action(
|
||||
name="update-query",
|
||||
abbr="uq",
|
||||
description="Update saved queries",
|
||||
description="Update stored queries",
|
||||
resource_class=QueryResource,
|
||||
),
|
||||
Action(
|
||||
name="delete-query",
|
||||
abbr="dq",
|
||||
description="Delete saved queries",
|
||||
description="Delete stored queries",
|
||||
resource_class=QueryResource,
|
||||
),
|
||||
)
|
||||
|
|
|
|||
|
|
@ -174,7 +174,7 @@ def view_actions(datasette, actor, database, view, request):
|
|||
|
||||
@hookspec
|
||||
def query_actions(datasette, actor, database, query_name, request, sql, params):
|
||||
"""Links for the query and canned query actions menu"""
|
||||
"""Links for the query and stored query actions menu"""
|
||||
|
||||
|
||||
@hookspec
|
||||
|
|
@ -229,7 +229,7 @@ def top_query(datasette, request, database, sql):
|
|||
|
||||
@hookspec
|
||||
def top_canned_query(datasette, request, database, query_name):
|
||||
"""HTML to include at the top of the canned query page"""
|
||||
"""HTML to include at the top of the stored query page"""
|
||||
|
||||
|
||||
@hookspec
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ class TableResource(Resource):
|
|||
|
||||
|
||||
class QueryResource(Resource):
|
||||
"""A saved query in a database."""
|
||||
"""A stored query in a database."""
|
||||
|
||||
name = "query"
|
||||
parent_class = DatabaseResource
|
||||
|
|
|
|||
|
|
@ -222,11 +222,11 @@ class DatabaseContext(Context):
|
|||
tables: list = field(metadata={"help": "List of table objects in the database"})
|
||||
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 canned query objects"})
|
||||
queries: list = field(metadata={"help": "List of stored query objects"})
|
||||
queries_more: bool = field(
|
||||
metadata={"help": "Boolean indicating if more saved queries are available"}
|
||||
metadata={"help": "Boolean indicating if more stored queries are available"}
|
||||
)
|
||||
queries_count: int = field(metadata={"help": "Count of visible saved queries"})
|
||||
queries_count: int = field(metadata={"help": "Count of visible stored queries"})
|
||||
allow_execute_sql: bool = field(
|
||||
metadata={"help": "Boolean indicating if custom SQL can be executed"}
|
||||
)
|
||||
|
|
@ -272,7 +272,7 @@ class QueryContext(Context):
|
|||
metadata={"help": "The SQL query object containing the `sql` string"}
|
||||
)
|
||||
canned_query: str = field(
|
||||
metadata={"help": "The name of the canned query if this is a canned query"}
|
||||
metadata={"help": "The name of the stored query if this is a stored query"}
|
||||
)
|
||||
private: bool = field(
|
||||
metadata={"help": "Boolean indicating if this is a private database"}
|
||||
|
|
@ -282,11 +282,11 @@ class QueryContext(Context):
|
|||
# )
|
||||
canned_query_write: bool = field(
|
||||
metadata={
|
||||
"help": "Boolean indicating if this is a canned query that allows writes"
|
||||
"help": "Boolean indicating if this is a stored query that allows writes"
|
||||
}
|
||||
)
|
||||
metadata: dict = field(
|
||||
metadata={"help": "Metadata about the database or the canned query"}
|
||||
metadata={"help": "Metadata about the database or the stored query"}
|
||||
)
|
||||
db_is_immutable: bool = field(
|
||||
metadata={"help": "Boolean indicating if this database is immutable"}
|
||||
|
|
@ -315,7 +315,7 @@ class QueryContext(Context):
|
|||
metadata={"help": "Dictionary of parameter names/values"}
|
||||
)
|
||||
edit_sql_url: str = field(
|
||||
metadata={"help": "URL to edit the SQL for a canned query"}
|
||||
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"})
|
||||
|
|
@ -1623,7 +1623,7 @@ class QueryView(View):
|
|||
|
||||
db = await datasette.resolve_database(request)
|
||||
|
||||
# We must be a canned query
|
||||
# We must be a stored query
|
||||
table_found = False
|
||||
try:
|
||||
await datasette.resolve_table(request)
|
||||
|
|
@ -1742,14 +1742,14 @@ class QueryView(View):
|
|||
# Create lookup dict for quick access
|
||||
allowed_dict = {r.child: r for r in allowed_tables_page.resources}
|
||||
|
||||
# Are we a canned query?
|
||||
# Are we a stored query?
|
||||
canned_query = None
|
||||
canned_query_write = False
|
||||
if "table" in request.url_vars:
|
||||
try:
|
||||
await datasette.resolve_table(request)
|
||||
except TableNotFound as table_not_found:
|
||||
# Was this actually a canned query?
|
||||
# Was this actually a stored query?
|
||||
canned_query = await datasette.get_canned_query(
|
||||
table_not_found.database_name, table_not_found.table, request.actor
|
||||
)
|
||||
|
|
@ -1759,7 +1759,7 @@ class QueryView(View):
|
|||
|
||||
private = False
|
||||
if canned_query:
|
||||
# Respect canned query permissions
|
||||
# Respect stored query permissions
|
||||
visible, private = await datasette.check_visibility(
|
||||
request.actor,
|
||||
action="view-query",
|
||||
|
|
@ -1823,7 +1823,7 @@ class QueryView(View):
|
|||
# For regular queries we only allow SELECT, plus other rules
|
||||
validate_sql_select(sql)
|
||||
else:
|
||||
# Canned queries can run magic parameters
|
||||
# Stored queries can run magic parameters
|
||||
params_for_query = MagicParameters(sql, params, request, datasette)
|
||||
await params_for_query.execute_params()
|
||||
results = await datasette.execute(
|
||||
|
|
|
|||
|
|
@ -963,11 +963,11 @@ async def table_view_traced(datasette, request):
|
|||
try:
|
||||
resolved = await datasette.resolve_table(request)
|
||||
except TableNotFound as not_found:
|
||||
# Was this actually a canned query?
|
||||
# Was this actually a stored query?
|
||||
canned_query = await datasette.get_canned_query(
|
||||
not_found.database_name, not_found.table, request.actor
|
||||
)
|
||||
# If this is a canned query, not a table, then dispatch to QueryView instead
|
||||
# If this is a stored query, not a table, then dispatch to QueryView instead
|
||||
if canned_query:
|
||||
return await QueryView()(request, datasette)
|
||||
else:
|
||||
|
|
|
|||
|
|
@ -468,7 +468,7 @@ You can control the following:
|
|||
* Access to the entire Datasette instance
|
||||
* Access to specific databases
|
||||
* Access to specific tables and views
|
||||
* Access to specific :ref:`canned_queries`
|
||||
* Access to specific :ref:`queries <canned_queries>`
|
||||
|
||||
If a user has permission to view a table they will be able to view that table, independent of if they have permission to view the database or instance that the table exists within.
|
||||
|
||||
|
|
@ -641,12 +641,12 @@ This works for SQL views as well - you can list their names in the ``"tables"``
|
|||
|
||||
.. _authentication_permissions_query:
|
||||
|
||||
Access to specific canned queries
|
||||
---------------------------------
|
||||
Access to specific queries
|
||||
--------------------------
|
||||
|
||||
:ref:`canned_queries` allow you to configure named SQL queries in your ``datasette.yaml`` that can be executed by users. These queries can be set up to both read and write to the database, so controlling who can execute them can be important.
|
||||
:ref:`Queries <canned_queries>` allow you to configure named SQL queries in your ``datasette.yaml`` that can be executed by users. These queries can be set up to both read and write to the database, so controlling who can execute them can be important.
|
||||
|
||||
To limit access to the ``add_name`` canned query in your ``dogs.db`` database to just the :ref:`root user<authentication_root>`:
|
||||
To limit access to the ``add_name`` query in your ``dogs.db`` database to just the :ref:`root user<authentication_root>`:
|
||||
|
||||
.. [[[cog
|
||||
config_example(cog, """
|
||||
|
|
@ -1285,7 +1285,7 @@ Actor is allowed to view a table (or view) page, e.g. https://latest.datasette.i
|
|||
view-query
|
||||
----------
|
||||
|
||||
Actor is allowed to view a saved query page, e.g. https://latest.datasette.io/fixtures/pragma_cache_size. Executing an untrusted saved query also requires ``execute-sql`` or the relevant write permissions; trusted saved queries can execute with ``view-query`` alone.
|
||||
Actor is allowed to view a stored query page, e.g. https://latest.datasette.io/fixtures/pragma_cache_size. Executing an untrusted stored query also requires ``execute-sql`` or the relevant write permissions; :ref:`trusted stored queries <trusted_stored_queries>` can execute with ``view-query`` alone.
|
||||
|
||||
``resource`` - ``datasette.resources.QueryResource(database, query)``
|
||||
``database`` is the name of the database (string)
|
||||
|
|
@ -1308,7 +1308,7 @@ Actor is allowed to create stored queries in a database.
|
|||
update-query
|
||||
------------
|
||||
|
||||
Actor is allowed to update a saved query.
|
||||
Actor is allowed to update a stored query.
|
||||
|
||||
``resource`` - ``datasette.resources.QueryResource(database, query)``
|
||||
``database`` is the name of the database (string)
|
||||
|
|
@ -1320,7 +1320,7 @@ Actor is allowed to update a saved query.
|
|||
delete-query
|
||||
------------
|
||||
|
||||
Actor is allowed to delete a saved query.
|
||||
Actor is allowed to delete a stored query.
|
||||
|
||||
``resource`` - ``datasette.resources.QueryResource(database, query)``
|
||||
``database`` is the name of the database (string)
|
||||
|
|
|
|||
|
|
@ -87,6 +87,7 @@ This is equivalent to a ``datasette.yaml`` file containing the following:
|
|||
}
|
||||
.. [[[end]]]
|
||||
|
||||
|
||||
.. _configuration_reference:
|
||||
|
||||
``datasette.yaml`` reference
|
||||
|
|
@ -435,10 +436,10 @@ Here is a simple example:
|
|||
|
||||
.. _configuration_reference_canned_queries:
|
||||
|
||||
Canned queries configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Queries configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:ref:`Canned queries <canned_queries>` are named SQL queries that appear in the Datasette interface. They can be configured in ``datasette.yaml`` using the ``queries`` key at the database level:
|
||||
:ref:`Queries <canned_queries>` are named SQL queries that appear in the Datasette interface. They can be configured in ``datasette.yaml`` using the ``queries`` key at the database level:
|
||||
|
||||
.. [[[cog
|
||||
from metadata_doc import config_example, config_example
|
||||
|
|
@ -483,7 +484,7 @@ Canned queries configuration
|
|||
}
|
||||
.. [[[end]]]
|
||||
|
||||
See the :ref:`canned queries documentation <canned_queries>` for more, including how to configure :ref:`writable canned queries <canned_queries_writable>`.
|
||||
See the :ref:`queries documentation <canned_queries>` for more, including how to configure :ref:`writable queries <canned_queries_writable>`.
|
||||
|
||||
.. _configuration_reference_css_js:
|
||||
|
||||
|
|
@ -1211,4 +1212,3 @@ For column types that accept additional configuration, use an object with ``type
|
|||
}
|
||||
}
|
||||
.. [[[end]]]
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ The custom SQL template (``/dbname?sql=...``) gets this:
|
|||
|
||||
<body class="query db-dbname">
|
||||
|
||||
A canned query template (``/dbname/queryname``) gets this:
|
||||
A stored query template (``/dbname/queryname``) gets this:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
|
|
@ -193,8 +193,8 @@ The lookup rules Datasette uses are as follows::
|
|||
query-mydatabase.html
|
||||
query.html
|
||||
|
||||
Canned query page (/mydatabase/canned-query):
|
||||
query-mydatabase-canned-query.html
|
||||
Stored query page (/mydatabase/query-name):
|
||||
query-mydatabase-query-name.html
|
||||
query-mydatabase.html
|
||||
query.html
|
||||
|
||||
|
|
@ -230,7 +230,7 @@ will look something like this::
|
|||
|
||||
<!-- Templates considered: *query-mydb-tz.html, query-mydb.html, query.html -->
|
||||
|
||||
This example is from the canned query page for a query called "tz" in the
|
||||
This example is from the stored query page for a query called "tz" in the
|
||||
database called "mydb". The asterisk shows which template was selected - so in
|
||||
this case, Datasette found a template file called ``query-mydb-tz.html`` and
|
||||
used that - but if that template had not been found, it would have tried for
|
||||
|
|
|
|||
|
|
@ -725,7 +725,7 @@ The builder methods are:
|
|||
|
||||
- ``allow_all(action)`` - allow an action across all databases and resources
|
||||
- ``allow_database(database, action)`` - allow an action on a specific database
|
||||
- ``allow_resource(database, resource, action)`` - allow an action on a specific resource (table, SQL view or :ref:`canned query <canned_queries>`) within a database
|
||||
- ``allow_resource(database, resource, action)`` - allow an action on a specific resource (table, SQL view or :ref:`stored query <stored_queries>`) within a database
|
||||
|
||||
Each method returns the ``TokenRestrictions`` instance so calls can be chained.
|
||||
|
||||
|
|
@ -837,10 +837,10 @@ await .get_resource_metadata(self, database_name, resource_name)
|
|||
``database_name`` - string
|
||||
The name of the database to query.
|
||||
``resource_name`` - string
|
||||
The name of the resource (table, view, or canned query) inside ``database_name`` to query.
|
||||
The name of the resource (table, view, or stored query) inside ``database_name`` to query.
|
||||
|
||||
Returns metadata keys and values for the specified "resource" as a dictionary.
|
||||
A "resource" in this context can be a table, view, or canned query.
|
||||
A "resource" in this context can be a table, view, or stored query.
|
||||
Internally queries the ``metadata_resources`` table inside the :ref:`internal database <internals_internal>`.
|
||||
|
||||
.. _datasette_get_column_metadata:
|
||||
|
|
@ -851,7 +851,7 @@ await .get_column_metadata(self, database_name, resource_name, column_name)
|
|||
``database_name`` - string
|
||||
The name of the database to query.
|
||||
``resource_name`` - string
|
||||
The name of the resource (table, view, or canned query) inside ``database_name`` to query.
|
||||
The name of the resource (table, view, or stored query) inside ``database_name`` to query.
|
||||
``column_name`` - string
|
||||
The name of the column inside ``resource_name`` to query.
|
||||
|
||||
|
|
@ -897,7 +897,7 @@ await .set_resource_metadata(self, database_name, resource_name, key, value)
|
|||
``database_name`` - string
|
||||
The database the metadata entry belongs to.
|
||||
``resource_name`` - string
|
||||
The resource (table, view, or canned query) the metadata entry belongs to.
|
||||
The resource (table, view, or stored query) the metadata entry belongs to.
|
||||
``key`` - string
|
||||
The metadata entry key to insert (ex ``title``, ``description``, etc.)
|
||||
``value`` - string
|
||||
|
|
@ -915,7 +915,7 @@ await .set_column_metadata(self, database_name, resource_name, column_name, key,
|
|||
``database_name`` - string
|
||||
The database the metadata entry belongs to.
|
||||
``resource_name`` - string
|
||||
The resource (table, view, or canned query) the metadata entry belongs to.
|
||||
The resource (table, view, or stored query) the metadata entry belongs to.
|
||||
``column-name`` - string
|
||||
The column the metadata entry belongs to.
|
||||
``key`` - string
|
||||
|
|
|
|||
|
|
@ -149,7 +149,7 @@ Shows currently attached databases. `Databases example <https://latest.datasette
|
|||
/-/jump
|
||||
-------
|
||||
|
||||
Returns a JSON list of items that the current actor has permission to view for Datasette's jump menu. By default this includes visible databases, tables, views and canned queries, and plugins can contribute additional items.
|
||||
Returns a JSON list of items that the current actor has permission to view for Datasette's jump menu. By default this includes visible databases, tables, views and stored queries, and plugins can contribute additional items.
|
||||
|
||||
Each item includes a ``type`` string used as a category label in the menu. Items can also include an optional ``description`` with longer text describing that individual result.
|
||||
|
||||
|
|
|
|||
|
|
@ -508,23 +508,23 @@ Datasette provides a write API for JSON data. This is a POST-only API that requi
|
|||
.. _GlobalQueryListView:
|
||||
.. _QueryListView:
|
||||
|
||||
Listing saved queries
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
Listing stored queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``GET /-/queries.json`` returns saved query definitions across every database that the actor can view. ``GET /<database>/-/queries.json`` returns saved query definitions for a specific database. Use ``?_size=50`` to set the page size and ``?_next=...`` with the cursor returned by the previous page to fetch the next page.
|
||||
``GET /-/queries.json`` returns stored query definitions across every database that the actor can view. ``GET /<database>/-/queries.json`` returns stored query definitions for a specific database. Use ``?_size=50`` to set the page size and ``?_next=...`` with the cursor returned by the previous page to fetch the next page.
|
||||
|
||||
.. _QueryCreateView:
|
||||
|
||||
Creating saved queries in the UI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Creating stored queries in the UI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``GET /<database>/-/queries/store`` provides a form for creating stored queries.
|
||||
|
||||
.. _QueryStoreView:
|
||||
.. _QueryInsertView:
|
||||
|
||||
Creating saved queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
Creating stored queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``POST /<database>/-/queries/store`` creates a stored query. This requires ``execute-sql`` and ``store-query`` for the database.
|
||||
|
||||
|
|
@ -545,24 +545,24 @@ Executing write SQL
|
|||
|
||||
.. _QueryDefinitionView:
|
||||
|
||||
Getting a saved query definition
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Getting a stored query definition
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``GET /<database>/<query>/-/definition`` returns a saved query definition without executing it.
|
||||
``GET /<database>/<query>/-/definition`` returns a stored query definition without executing it.
|
||||
|
||||
.. _QueryUpdateView:
|
||||
|
||||
Updating saved queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
Updating stored queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``POST /<database>/<query>/-/update`` updates a saved query using a JSON body with an ``"update"`` object.
|
||||
``POST /<database>/<query>/-/update`` updates a stored query using a JSON body with an ``"update"`` object.
|
||||
|
||||
.. _QueryDeleteView:
|
||||
|
||||
Deleting saved queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
Deleting stored queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``POST /<database>/<query>/-/delete`` deletes a saved query.
|
||||
``POST /<database>/<query>/-/delete`` deletes a stored query.
|
||||
|
||||
.. _TableInsertView:
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ The index page can also be accessed at ``/-/``, useful for if the default index
|
|||
Database
|
||||
========
|
||||
|
||||
Each database has a page listing the tables, views and canned queries available for that database. If the :ref:`actions_execute_sql` permission is enabled (it's on by default) there will also be an interface for executing arbitrary SQL select queries against the data.
|
||||
Each database has a page listing the tables, views and stored queries available for that database. If the :ref:`actions_execute_sql` permission is enabled (it's on by default) there will also be an interface for executing arbitrary SQL select queries against the data.
|
||||
|
||||
Examples:
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ This means you can link directly to a query by constructing the following URL:
|
|||
|
||||
``/database-name/-/query?sql=SELECT+*+FROM+table_name``
|
||||
|
||||
Each configured :ref:`canned query <canned_queries>` has its own page, at ``/database-name/query-name``. Viewing this page will execute the query and display the results.
|
||||
Each configured :ref:`stored query <stored_queries>` has its own page, at ``/database-name/query-name``. Viewing this page will execute the query and display the results.
|
||||
|
||||
In both cases adding a ``.json`` extension to the URL will return the results as JSON.
|
||||
|
||||
|
|
|
|||
|
|
@ -609,7 +609,7 @@ When a request is received, the ``"render"`` callback function is called with ze
|
|||
The SQL query that was executed.
|
||||
|
||||
``query_name`` - string or None
|
||||
If this was the execution of a :ref:`canned query <canned_queries>`, the name of that query.
|
||||
If this was the execution of a :ref:`stored query <stored_queries>`, the name of that query.
|
||||
|
||||
``database`` - string
|
||||
The name of the database.
|
||||
|
|
@ -1212,7 +1212,7 @@ Examples: `datasette-saved-queries <https://datasette.io/plugins/datasette-saved
|
|||
canned_queries(datasette, database, actor)
|
||||
------------------------------------------
|
||||
|
||||
This hook has been removed. Plugins that need to add saved queries should use
|
||||
This hook has been removed. Plugins that need to add stored queries should use
|
||||
the :ref:`plugin_hook_startup` hook and call ``await datasette.add_query(...)``.
|
||||
|
||||
Example: `datasette-saved-queries <https://datasette.io/plugins/datasette-saved-queries>`__
|
||||
|
|
@ -1635,7 +1635,7 @@ register_magic_parameters(datasette)
|
|||
``datasette`` - :ref:`internals_datasette`
|
||||
You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``.
|
||||
|
||||
:ref:`canned_queries_magic_parameters` can be used to add automatic parameters to :ref:`canned queries <canned_queries>`. This plugin hook allows additional magic parameters to be defined by plugins.
|
||||
:ref:`canned_queries_magic_parameters` can be used to add automatic parameters to :ref:`configured queries <canned_queries>`. This plugin hook allows additional magic parameters to be defined by plugins.
|
||||
|
||||
Magic parameters all take this format: ``_prefix_rest_of_parameter``. The prefix indicates which magic parameter function should be called - the rest of the parameter is passed as an argument to that function.
|
||||
|
||||
|
|
@ -1828,7 +1828,7 @@ jump_items_sql(datasette, actor, request)
|
|||
|
||||
This hook allows plugins to add extra results to Datasette's ``/`` jump menu, which is powered by the ``/-/jump`` JSON endpoint.
|
||||
|
||||
Return a ``datasette.jump.JumpSQL`` object, or a list of ``JumpSQL`` objects. Each ``JumpSQL`` object wraps a SQL query to be searched alongside Datasette's own databases, tables, views and canned query results. The hook can also be an ``async def`` function, or return an awaitable that resolves to one of these values.
|
||||
Return a ``datasette.jump.JumpSQL`` object, or a list of ``JumpSQL`` objects. Each ``JumpSQL`` object wraps a SQL query to be searched alongside Datasette's own databases, tables, views and stored query results. The hook can also be an ``async def`` function, or return an awaitable that resolves to one of these values.
|
||||
|
||||
``JumpSQL`` queries run against Datasette's internal database by default. To run a query against another database, pass its name as the optional ``database=`` argument. For example, ``JumpSQL(database="content", sql="...")`` runs against the ``content`` database.
|
||||
|
||||
|
|
@ -2004,7 +2004,7 @@ query_actions(datasette, actor, database, query_name, request, sql, params)
|
|||
The name of the database.
|
||||
|
||||
``query_name`` - string or None
|
||||
The name of the canned query, or ``None`` if this is an arbitrary SQL query.
|
||||
The name of the stored query, or ``None`` if this is an arbitrary SQL query.
|
||||
|
||||
``request`` - :ref:`internals_request`
|
||||
The current HTTP request.
|
||||
|
|
@ -2015,7 +2015,7 @@ query_actions(datasette, actor, database, query_name, request, sql, params)
|
|||
``params`` - dictionary
|
||||
The parameters passed to the SQL query, if any.
|
||||
|
||||
Populates a "Query actions" menu on the canned query and arbitrary SQL query pages.
|
||||
Populates a "Query actions" menu on the stored query and arbitrary SQL query pages.
|
||||
|
||||
This example adds a new query action linking to a page for explaining a query:
|
||||
|
||||
|
|
@ -2294,9 +2294,9 @@ top_canned_query(datasette, request, database, query_name)
|
|||
The name of the database.
|
||||
|
||||
``query_name`` - string
|
||||
The name of the canned query.
|
||||
The name of the stored query.
|
||||
|
||||
Returns HTML to be displayed at the top of the canned query page.
|
||||
Returns HTML to be displayed at the top of the stored query page.
|
||||
|
||||
.. _plugin_event_tracking:
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ Warning
|
|||
The following steps are recommended:
|
||||
|
||||
- Disable arbitrary SQL queries by untrusted users. See :ref:`authentication_permissions_execute_sql` for ways to do this. The easiest is to start Datasette with the ``datasette --setting default_allow_sql off`` option.
|
||||
- Define :ref:`canned_queries` with the SQL queries that use SpatiaLite functions that you want people to be able to execute.
|
||||
- Define :ref:`queries <canned_queries>` with the SQL queries that use SpatiaLite functions that you want people to be able to execute.
|
||||
|
||||
The `Datasette SpatiaLite tutorial <https://datasette.io/tutorials/spatialite>`__ includes detailed instructions for running SpatiaLite safely using these techniques
|
||||
|
||||
|
|
|
|||
|
|
@ -68,10 +68,10 @@ You can also use the `sqlite-utils <https://sqlite-utils.datasette.io/>`__ tool
|
|||
|
||||
.. _canned_queries:
|
||||
|
||||
Canned queries
|
||||
--------------
|
||||
Queries
|
||||
-------
|
||||
|
||||
As an alternative to adding views to your database, you can define canned queries inside your ``datasette.yaml`` file. Here's an example:
|
||||
As an alternative to adding views to your database, you can define named queries inside your ``datasette.yaml`` file. Here's an example:
|
||||
|
||||
.. [[[cog
|
||||
from metadata_doc import config_example, config_example
|
||||
|
|
@ -120,24 +120,67 @@ Then run Datasette like this::
|
|||
|
||||
datasette sf-trees.db -m metadata.json
|
||||
|
||||
Each canned query will be listed on the database index page, and will also get its own URL at::
|
||||
Each configured query will be listed on the database index page, and will also get its own URL at::
|
||||
|
||||
/database-name/canned-query-name
|
||||
/database-name/query-name
|
||||
|
||||
For the above example, that URL would be::
|
||||
|
||||
/sf-trees/just_species
|
||||
|
||||
You can optionally include ``"title"`` and ``"description"`` keys to show a title and description on the canned query page. As with regular table metadata you can alternatively specify ``"description_html"`` to have your description rendered as HTML (rather than having HTML special characters escaped).
|
||||
You can optionally include ``"title"`` and ``"description"`` keys to show a title and description on the query page. As with regular table metadata you can alternatively specify ``"description_html"`` to have your description rendered as HTML (rather than having HTML special characters escaped).
|
||||
|
||||
.. _stored_queries:
|
||||
.. _saved_queries:
|
||||
|
||||
Stored queries
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Datasette stores both configured queries and user-created queries in the ``queries`` table in the :ref:`internal database <internals_internal>`. Configured queries come from the ``queries`` section of ``datasette.yaml``. User-created stored queries can be created from the SQL query page by actors with the :ref:`actions_store_query` and :ref:`actions_execute_sql` permissions. Writable stored queries also require the permissions needed for the writes they perform.
|
||||
|
||||
Stored queries created by users default to private. Private stored queries can only be viewed, updated or deleted by the actor that created them. Broad ``view-query``, ``update-query`` or ``delete-query`` permission grants still do not allow other actors to access another actor's private stored queries.
|
||||
|
||||
Stored queries created by users are untrusted. This means they execute using the permissions of the actor who runs them, as if that actor had pasted the SQL into the regular custom SQL interface or write SQL interface. Read-only stored queries require ``execute-sql``. Writable stored queries require ``execute-write-sql`` plus the relevant table-level write permissions.
|
||||
|
||||
.. _trusted_stored_queries:
|
||||
.. _trusted_saved_queries:
|
||||
|
||||
Trusted stored queries
|
||||
++++++++++++++++++++++
|
||||
|
||||
A trusted stored query can execute with ``view-query`` permission alone. It skips the additional ``execute-sql`` and write permission checks that are applied to untrusted stored queries.
|
||||
|
||||
Trusted stored queries should only be used for SQL that has been reviewed by someone trusted to configure the Datasette instance. For that reason, trusted stored queries can only be added using configuration. Users cannot create trusted stored queries through the web interface or the stored query JSON API.
|
||||
|
||||
Queries defined in ``datasette.yaml`` are trusted by default:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
databases:
|
||||
mydatabase:
|
||||
queries:
|
||||
report:
|
||||
sql: select * from report
|
||||
|
||||
You can opt out of this behavior for a configured query using ``is_trusted: false``:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
databases:
|
||||
mydatabase:
|
||||
queries:
|
||||
report:
|
||||
sql: select * from report
|
||||
is_trusted: false
|
||||
|
||||
.. _canned_queries_named_parameters:
|
||||
|
||||
Canned query parameters
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Query parameters
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Canned queries support named parameters, so if you include those in the SQL you will then be able to enter them using the form fields on the canned query page or by adding them to the URL. This means canned queries can be used to create custom JSON APIs based on a carefully designed SQL statement.
|
||||
Configured queries support named parameters, so if you include those in the SQL you will then be able to enter them using the form fields on the query page or by adding them to the URL. This means configured queries can be used to create custom JSON APIs based on a carefully designed SQL statement.
|
||||
|
||||
Here's an example of a canned query with a named parameter:
|
||||
Here's an example of a configured query with a named parameter:
|
||||
|
||||
.. code-block:: sql
|
||||
|
||||
|
|
@ -147,7 +190,7 @@ Here's an example of a canned query with a named parameter:
|
|||
where neighborhood like '%' || :text || '%'
|
||||
order by neighborhood;
|
||||
|
||||
In the canned query configuration looks like this:
|
||||
The query configuration looks like this:
|
||||
|
||||
|
||||
.. [[[cog
|
||||
|
|
@ -204,7 +247,7 @@ In the canned query configuration looks like this:
|
|||
|
||||
Note that we are using SQLite string concatenation here - the ``||`` operator - to add wildcard ``%`` characters to the string provided by the user.
|
||||
|
||||
You can try this canned query out here:
|
||||
You can try this query out here:
|
||||
https://latest.datasette.io/fixtures/neighborhood_search?text=town
|
||||
|
||||
In this example the ``:text`` named parameter is automatically extracted from the query using a regular expression.
|
||||
|
|
@ -272,15 +315,15 @@ You can alternatively provide an explicit list of named parameters using the ``"
|
|||
|
||||
.. _canned_queries_options:
|
||||
|
||||
Additional canned query options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Additional query options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Additional options can be specified for canned queries in the YAML or JSON configuration.
|
||||
Additional options can be specified for configured queries in the YAML or JSON configuration.
|
||||
|
||||
hide_sql
|
||||
++++++++
|
||||
|
||||
Canned queries default to displaying their SQL query at the top of the page. If the query is extremely long you may want to hide it by default, with a "show" link that can be used to make it visible.
|
||||
Configured queries default to displaying their SQL query at the top of the page. If the query is extremely long you may want to hide it by default, with a "show" link that can be used to make it visible.
|
||||
|
||||
Add the ``"hide_sql": true`` option to hide the SQL query by default.
|
||||
|
||||
|
|
@ -289,7 +332,7 @@ fragment
|
|||
|
||||
Some plugins, such as `datasette-vega <https://github.com/simonw/datasette-vega>`__, can be configured by including additional data in the fragment hash of the URL - the bit that comes after a ``#`` symbol.
|
||||
|
||||
You can set a default fragment hash that will be included in the link to the canned query from the database index page using the ``"fragment"`` key.
|
||||
You can set a default fragment hash that will be included in the link to the query from the database index page using the ``"fragment"`` key.
|
||||
|
||||
This example demonstrates both ``fragment`` and ``hide_sql``:
|
||||
|
||||
|
|
@ -348,12 +391,12 @@ This example demonstrates both ``fragment`` and ``hide_sql``:
|
|||
|
||||
.. _canned_queries_writable:
|
||||
|
||||
Writable canned queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Writable queries
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Canned queries by default are read-only. You can use the ``"write": true`` key to indicate that a canned query can write to the database.
|
||||
Configured queries are read-only by default. You can use the ``"write": true`` key to indicate that a query can write to the database.
|
||||
|
||||
See :ref:`authentication_permissions_query` for details on how to add permission checks to canned queries, using the ``"allow"`` key.
|
||||
See :ref:`authentication_permissions_query` for details on how to add permission checks to queries, using the ``"allow"`` key.
|
||||
|
||||
.. [[[cog
|
||||
config_example(cog, {
|
||||
|
|
@ -488,7 +531,7 @@ Magic parameters
|
|||
|
||||
Named parameters that start with an underscore are special: they can be used to automatically add values created by Datasette that are not contained in the incoming form fields or query string.
|
||||
|
||||
These magic parameters are only supported for canned queries: to avoid security issues (such as queries that extract the user's private cookies) they are not available to SQL that is executed by the user as a custom SQL query.
|
||||
These magic parameters are only supported for configured queries: to avoid security issues (such as queries that extract the user's private cookies) they are not available to SQL that is executed by the user as a custom SQL query.
|
||||
|
||||
Available magic parameters are:
|
||||
|
||||
|
|
@ -580,12 +623,12 @@ Additional custom magic parameters can be added by plugins using the :ref:`plugi
|
|||
|
||||
.. _canned_queries_json_api:
|
||||
|
||||
JSON API for writable canned queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
JSON API for writable queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Writable canned queries can also be accessed using a JSON API. You can POST data to them using JSON, and you can request that their response is returned to you as JSON.
|
||||
Writable queries can also be accessed using a JSON API. You can POST data to them using JSON, and you can request that their response is returned to you as JSON.
|
||||
|
||||
To submit JSON to a writable canned query, encode key/value parameters as a JSON document::
|
||||
To submit JSON to a writable query, encode key/value parameters as a JSON document::
|
||||
|
||||
POST /mydatabase/add_message
|
||||
|
||||
|
|
|
|||
|
|
@ -154,7 +154,7 @@ async def test_database_page(ds_client):
|
|||
("/fixtures/simple_view", "simple_view"),
|
||||
] == sorted([(a["href"], a.text) for a in views_ul.find_all("a")])
|
||||
|
||||
# And a list of canned queries
|
||||
# And a list of stored queries
|
||||
queries_ul = soup.find("h2", string="Queries").find_next_sibling("ul")
|
||||
assert queries_ul is not None
|
||||
assert [
|
||||
|
|
@ -701,7 +701,7 @@ async def test_show_hide_sql_query(ds_client):
|
|||
|
||||
@pytest.mark.asyncio
|
||||
async def test_canned_query_with_hide_has_no_hidden_sql(ds_client):
|
||||
# For a canned query the show/hide should NOT have a hidden SQL field
|
||||
# For a stored query the show/hide should NOT have a hidden SQL field
|
||||
# https://github.com/simonw/datasette/issues/1411
|
||||
response = await ds_client.get("/fixtures/pragma_cache_size?_hide_sql=1")
|
||||
soup = Soup(response.content, "html.parser")
|
||||
|
|
@ -1106,7 +1106,7 @@ async def test_trace_correctly_escaped(ds_client):
|
|||
"/fixtures/-/query?sql=select+*+from+facetable",
|
||||
"http://localhost/fixtures/-/query.json?sql=select+*+from+facetable",
|
||||
),
|
||||
# Canned query page
|
||||
# Stored query page
|
||||
(
|
||||
"/fixtures/neighborhood_search?text=town",
|
||||
"http://localhost/fixtures/neighborhood_search.json?text=town",
|
||||
|
|
|
|||
|
|
@ -890,7 +890,7 @@ PermConfigTestCase = collections.namedtuple(
|
|||
resource=("perms_ds_one", "t1"),
|
||||
expected_result=True,
|
||||
),
|
||||
# view-query on canned query, wrong actor
|
||||
# view-query on stored query, wrong actor
|
||||
PermConfigTestCase(
|
||||
config={
|
||||
"databases": {
|
||||
|
|
@ -909,7 +909,7 @@ PermConfigTestCase = collections.namedtuple(
|
|||
resource=("perms_ds_one", "q1"),
|
||||
expected_result=False,
|
||||
),
|
||||
# view-query on canned query, right actor
|
||||
# view-query on stored query, right actor
|
||||
PermConfigTestCase(
|
||||
config={
|
||||
"databases": {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue