{"id": "sql_queries:id1", "page": "sql_queries", "ref": "id1", "title": "Canned queries", "content": "As an alternative to adding views to your database, you can define canned queries inside your  datasette.yaml  file. Here's an example: \n             [[[cog\nfrom metadata_doc import config_example, config_example\nconfig_example(cog, {\n    \"databases\": {\n       \"sf-trees\": {\n           \"queries\": {\n               \"just_species\": {\n                   \"sql\": \"select qSpecies from Street_Tree_List\"\n               }\n           }\n       }\n    }\n}) \n             ]]] \n             [[[end]]] \n             Then run Datasette like this: \n             datasette sf-trees.db -m metadata.json \n             Each canned query will be listed on the database index page, and will also get its own URL at: \n             /database-name/canned-query-name \n             For the above example, that URL would be: \n             /sf-trees/just_species \n             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).", "breadcrumbs": "[\"Running SQL queries\"]", "references": "[]"}
{"id": "sql_queries:id2", "page": "sql_queries", "ref": "id2", "title": "Pagination", "content": "Datasette's default table pagination is designed to be extremely efficient. SQL OFFSET/LIMIT pagination can have a significant performance penalty once you get into multiple thousands of rows, as each page still requires the database to scan through every preceding row to find the correct offset. \n             When paginating through tables, Datasette instead orders the rows in the table by their primary key and performs a WHERE clause against the last seen primary key for the previous page. For example: \n             select rowid, * from Tree_List where rowid > 200 order by rowid limit 101 \n             This represents page three for this particular table, with a page size of 100. \n             Note that we request 101 items in the limit clause rather than 100. This allows us to detect if we are on the last page of the results: if the query returns less than 101 rows we know we have reached the end of the pagination set. Datasette will only return the first 100 rows - the 101st is used purely to detect if there should be another page. \n             Since the where clause acts against the index on the primary key, the query is extremely fast even for records that are a long way into the overall pagination set.", "breadcrumbs": "[\"Running SQL queries\"]", "references": "[]"}
{"id": "sql_queries:id3", "page": "sql_queries", "ref": "id3", "title": "Cross-database queries", "content": "SQLite has the ability to run queries that join across multiple databases. Up to ten databases can be attached to a single SQLite connection and queried together. \n             Datasette can execute joins across multiple databases if it is started with the  --crossdb  option: \n             datasette fixtures.db extra_database.db --crossdb \n             If it is started in this way, the  /_memory  page can be used to execute queries that join across multiple databases. \n             References to tables in attached databases should be preceded by the database name and a period. \n             For example, this query will show a list of tables across both of the above databases: \n             select\n  'fixtures' as database, *\nfrom\n  [fixtures].sqlite_master\nunion\nselect\n  'extra_database' as database, *\nfrom\n  [extra_database].sqlite_master \n             Try that out here .", "breadcrumbs": "[\"Running SQL queries\"]", "references": "[{\"href\": \"https://latest.datasette.io/_memory?sql=select%0D%0A++%27fixtures%27+as+database%2C+*%0D%0Afrom%0D%0A++%5Bfixtures%5D.sqlite_master%0D%0Aunion%0D%0Aselect%0D%0A++%27extra_database%27+as+database%2C+*%0D%0Afrom%0D%0A++%5Bextra_database%5D.sqlite_master\", \"label\": \"Try that out here\"}]"}
{"id": "sql_queries:sql-parameters", "page": "sql_queries", "ref": "sql-parameters", "title": "Named parameters", "content": "Datasette has special support for SQLite named parameters. Consider a SQL query like this: \n             select * from Street_Tree_List\nwhere \"PermitNotes\" like :notes\nand \"qSpecies\" = :species \n             If you execute this query using the custom query editor, Datasette will extract the two named parameters and use them to construct form fields for you to provide values. \n             You can also provide values for these fields by constructing a URL: \n             /mydatabase?sql=select...&species=44 \n             SQLite string escaping rules will be applied to values passed using named parameters - they will be wrapped in quotes and their content will be correctly escaped. \n             Values from named parameters are treated as SQLite strings. If you need to perform numeric comparisons on them you should cast them to an integer or float first using  cast(:name as integer)  or  cast(:name as real) , for example: \n             select * from Street_Tree_List\nwhere latitude > cast(:min_latitude as real)\nand latitude < cast(:max_latitude as real) \n             Datasette disallows custom SQL queries containing the string PRAGMA (with a small number  of exceptions ) as SQLite pragma statements can be used to change database settings at runtime. If you need to include the string \"pragma\" in a query you can do so safely using a named parameter.", "breadcrumbs": "[\"Running SQL queries\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/761\", \"label\": \"of exceptions\"}]"}
{"id": "sql_queries:sql-views", "page": "sql_queries", "ref": "sql-views", "title": "Views", "content": "If you want to bundle some pre-written SQL queries with your Datasette-hosted database you can do so in two ways. The first is to include SQL views in your database - Datasette will then list those views on your database index page. \n             The quickest way to create views is with the SQLite command-line interface: \n             sqlite3 sf-trees.db \n             SQLite version 3.19.3 2017-06-27 16:48:08\nEnter \".help\" for usage hints.\nsqlite> CREATE VIEW demo_view AS select qSpecies from Street_Tree_List;\n<CTRL+D> \n             You can also use the  sqlite-utils  tool to  create a view : \n             sqlite-utils create-view sf-trees.db demo_view \"select qSpecies from Street_Tree_List\"", "breadcrumbs": "[\"Running SQL queries\"]", "references": "[{\"href\": \"https://sqlite-utils.datasette.io/\", \"label\": \"sqlite-utils\"}, {\"href\": \"https://sqlite-utils.datasette.io/en/stable/cli.html#creating-views\", \"label\": \"create a view\"}]"}