{"id": "sql_queries:canned-queries-json-api", "page": "sql_queries", "ref": "canned-queries-json-api", "title": "JSON API for writable canned queries", "content": "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. \n                 To submit JSON to a writable canned query, encode key/value parameters as a JSON document: \n                 POST /mydatabase/add_message\n\n{\"message\": \"Message goes here\"} \n                 You can also continue to submit data using regular form encoding, like so: \n                 POST /mydatabase/add_message\n\nmessage=Message+goes+here \n                 There are three options for specifying that you would like the response to your request to return JSON data, as opposed to an HTTP redirect to another page. \n                 \n                     \n                         Set an  Accept: application/json  header on your request \n                     \n                     \n                         Include  ?_json=1  in the URL that you POST to \n                     \n                     \n                         Include  \"_json\": 1  in your JSON body, or  &_json=1  in your form encoded body \n                     \n                 \n                 The JSON response will look like this: \n                 {\n    \"ok\": true,\n    \"message\": \"Query executed, 1 row affected\",\n    \"redirect\": \"/data/add_name\"\n} \n                 The  \"message\"  and  \"redirect\"  values here will take into account  on_success_message ,  on_success_message_sql ,   on_success_redirect ,  on_error_message  and  on_error_redirect , if they have been set.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[]"}
{"id": "sql_queries:canned-queries-magic-parameters", "page": "sql_queries", "ref": "canned-queries-magic-parameters", "title": "Magic parameters", "content": "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. \n                 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. \n                 Available magic parameters are: \n                 \n                     \n                         _actor_*  - e.g.  _actor_id ,  _actor_name \n                         \n                             Fields from the currently authenticated  Actors . \n                         \n                     \n                     \n                         _header_*  - e.g.  _header_user_agent \n                         \n                             Header from the incoming HTTP request. The key should be in lower case and with hyphens converted to underscores e.g.  _header_user_agent  or  _header_accept_language . \n                         \n                     \n                     \n                         _cookie_*  - e.g.  _cookie_lang \n                         \n                             The value of the incoming cookie of that name. \n                         \n                     \n                     \n                         _now_epoch \n                         \n                             The number of seconds since the Unix epoch. \n                         \n                     \n                     \n                         _now_date_utc \n                         \n                             The date in UTC, e.g.  2020-06-01 \n                         \n                     \n                     \n                         _now_datetime_utc \n                         \n                             The ISO 8601 datetime in UTC, e.g.  2020-06-24T18:01:07Z \n                         \n                     \n                     \n                         _random_chars_*  - e.g.  _random_chars_128 \n                         \n                             A random string of characters of the specified length. \n                         \n                     \n                 \n                 Here's an example configuration that adds a message from the authenticated user, storing various pieces of additional metadata using magic parameters: \n                 [[[cog\nconfig_example(cog, \"\"\"\ndatabases:\n  mydatabase:\n    queries:\n      add_message:\n        allow:\n          id: \"*\"\n        sql: |-\n          INSERT INTO messages (\n            user_id, message, datetime\n          ) VALUES (\n            :_actor_id, :message, :_now_datetime_utc\n          )\n        write: true\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 The form presented at  /mydatabase/add_message  will have just a field for  message  - the other parameters will be populated by the magic parameter mechanism. \n                 Additional custom magic parameters can be added by plugins using the  register_magic_parameters(datasette)  hook.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[]"}
{"id": "sql_queries:canned-queries-named-parameters", "page": "sql_queries", "ref": "canned-queries-named-parameters", "title": "Canned query parameters", "content": "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. \n                 Here's an example of a canned query with a named parameter: \n                 select neighborhood, facet_cities.name, state\nfrom facetable\n  join facet_cities on facetable.city_id = facet_cities.id\nwhere neighborhood like '%' || :text || '%'\norder by neighborhood; \n                 In the canned query configuration looks like this: \n                 [[[cog\nconfig_example(cog, \"\"\"\ndatabases:\n  fixtures:\n    queries:\n      neighborhood_search:\n        title: Search neighborhoods\n        sql: |-\n          select neighborhood, facet_cities.name, state\n          from facetable\n            join facet_cities on facetable.city_id = facet_cities.id\n          where neighborhood like '%' || :text || '%'\n          order by neighborhood\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 Note that we are using SQLite string concatenation here - the  ||  operator - to add wildcard  %  characters to the string provided by the user. \n                 You can try this canned query out here:\n                     https://latest.datasette.io/fixtures/neighborhood_search?text=town \n                 In this example the  :text  named parameter is automatically extracted from the query using a regular expression. \n                 You can alternatively provide an explicit list of named parameters using the  \"params\"  key, like this: \n                 [[[cog\nconfig_example(cog, \"\"\"\ndatabases:\n  fixtures:\n    queries:\n      neighborhood_search:\n        title: Search neighborhoods\n        params:\n        - text\n        sql: |-\n          select neighborhood, facet_cities.name, state\n          from facetable\n            join facet_cities on facetable.city_id = facet_cities.id\n          where neighborhood like '%' || :text || '%'\n          order by neighborhood\n\"\"\") \n                 ]]] \n                 [[[end]]]", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/neighborhood_search?text=town\", \"label\": \"https://latest.datasette.io/fixtures/neighborhood_search?text=town\"}]"}
{"id": "sql_queries:canned-queries-options", "page": "sql_queries", "ref": "canned-queries-options", "title": "Additional canned query options", "content": "Additional options can be specified for canned queries in the YAML or JSON configuration.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[]"}
{"id": "sql_queries:canned-queries-writable", "page": "sql_queries", "ref": "canned-queries-writable", "title": "Writable canned queries", "content": "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. \n                 See  Access to specific canned queries  for details on how to add permission checks to canned queries, using the  \"allow\"  key. \n                 [[[cog\nconfig_example(cog, {\n    \"databases\": {\n        \"mydatabase\": {\n            \"queries\": {\n                \"add_name\": {\n                    \"sql\": \"INSERT INTO names (name) VALUES (:name)\",\n                    \"write\": True\n                }\n            }\n        }\n    }\n}) \n                 ]]] \n                 [[[end]]] \n                 This configuration will create a page at  /mydatabase/add_name  displaying a form with a  name  field. Submitting that form will execute the configured  INSERT  query. \n                 You can customize how Datasette represents success and errors using the following optional properties: \n                 \n                     \n                         on_success_message  - the message shown when a query is successful \n                     \n                     \n                         on_success_message_sql  - alternative to  on_success_message : a SQL query that should be executed to generate the message \n                     \n                     \n                         on_success_redirect  - the path or URL the user is redirected to on success \n                     \n                     \n                         on_error_message  - the message shown when a query throws an error \n                     \n                     \n                         on_error_redirect  - the path or URL the user is redirected to on error \n                     \n                 \n                 For example: \n                 [[[cog\nconfig_example(cog, {\n    \"databases\": {\n        \"mydatabase\": {\n            \"queries\": {\n                \"add_name\": {\n                    \"sql\": \"INSERT INTO names (name) VALUES (:name)\",\n                    \"params\": [\"name\"],\n                    \"write\": True,\n                    \"on_success_message_sql\": \"select 'Name inserted: ' || :name\",\n                    \"on_success_redirect\": \"/mydatabase/names\",\n                    \"on_error_message\": \"Name insert failed\",\n                    \"on_error_redirect\": \"/mydatabase\",\n                }\n            }\n        }\n    }\n}) \n                 ]]] \n                 [[[end]]] \n                 You can use  \"params\"  to explicitly list the named parameters that should be displayed as form fields - otherwise they will be automatically detected.  \"params\"  is not necessary in the above example, since without it  \"name\"  would be automatically detected from the query. \n                 You can pre-populate form fields when the page first loads using a query string, e.g.  /mydatabase/add_name?name=Prepopulated . The user will have to submit the form to execute the query. \n                 If you specify a query in  \"on_success_message_sql\" , that query will be executed after the main query. The first column of the first row return by that query will be displayed as a success message. Named parameters from the main query will be made available to the success message query as well.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[]"}
{"id": "sql_queries:fragment", "page": "sql_queries", "ref": "fragment", "title": "fragment", "content": "Some plugins, such as  datasette-vega , can be configured by including additional data in the fragment hash of the URL - the bit that comes after a  #  symbol. \n                     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. \n                     This example demonstrates both  fragment  and  hide_sql : \n                     [[[cog\nconfig_example(cog, \"\"\"\ndatabases:\n  fixtures:\n    queries:\n      neighborhood_search:\n        fragment: fragment-goes-here\n        hide_sql: true\n        sql: |-\n          select neighborhood, facet_cities.name, state\n          from facetable join facet_cities on facetable.city_id = facet_cities.id\n          where neighborhood like '%' || :text || '%' order by neighborhood;\n\"\"\") \n                     ]]] \n                     [[[end]]] \n                     See here  for a demo of this in action.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\", \"Additional canned query options\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-vega\", \"label\": \"datasette-vega\"}, {\"href\": \"https://latest.datasette.io/fixtures#queries\", \"label\": \"See here\"}]"}
{"id": "sql_queries:hide-sql", "page": "sql_queries", "ref": "hide-sql", "title": "hide_sql", "content": "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. \n                     Add the  \"hide_sql\": true  option to hide the SQL query by default.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\", \"Additional canned query options\"]", "references": "[]"}