rowid,title,content,sections_fts,rank
791,Table-level metadata,"""Table-level"" metadata refers to fields that can be specified for each table in a Datasette instance. These attributes should be listed under a specific table using the  ""tables""  field. 
                 The following metadata fields are supported at the table level: 
                 
                     
                         source 
                     
                     
                         source_url 
                     
                     
                         license 
                     
                     
                         license_url 
                     
                     
                         about 
                     
                     
                         about_url 
                     
                     
                         columns  (see  Column descriptions ) 
                     
                 
                 Additionally, tables support a number of configuration options ( sort ,  sort_desc ,  size ,  sortable_columns ,  label_column ,  hidden ,  facets ,  facet_size ,  fts_table ,  fts_pk ,  searchmode ,  column_types ). See  table configuration  for full details.",154,
790,Database-level metadata,"""Database-level"" metadata refers to fields that can be specified for each database in a Datasette instance. These attributes should be listed under a database inside the  ""databases""  field. 
                 The following are the full list of allowed database-level metadata fields: 
                 
                     
                         source 
                     
                     
                         source_url 
                     
                     
                         license 
                     
                     
                         license_url 
                     
                     
                         about 
                     
                     
                         about_url",154,
789,Top-level metadata,"""Top-level"" metadata refers to fields that can be specified at the root level  of a metadata file. These attributes are meant to describe the entire Datasette instance. 
                 The following are the full list of allowed top-level metadata fields: 
                 
                     
                         title 
                     
                     
                         description 
                     
                     
                         description_html 
                     
                     
                         license 
                     
                     
                         license_url 
                     
                     
                         source 
                     
                     
                         source_url",154,
788,Metadata reference,A full reference of every supported option in a  metadata.json  or  metadata.yaml  file.,154,
787,Table configuration,"Datasette supports a range of table-level configuration options including sort order, page size, facets, full-text search, column types, and more. These are now documented in the  table configuration  section of the configuration reference. 
             For backwards compatibility these options can be specified in either  metadata.yaml  or  datasette.yaml .",154,
786,Column descriptions,"You can include descriptions for your columns by adding a  ""columns"": {""name-of-column"": ""description-of-column""}  block to your table metadata: 
             [[[cog
metadata_example(cog, {
    ""databases"": {
        ""database1"": {
            ""tables"": {
                ""example_table"": {
                    ""columns"": {
                        ""column1"": ""Description of column 1"",
                        ""column2"": ""Description of column 2""
                    }
                }
            }
        }
    }
}) 
             ]]] 
             [[[end]]] 
             These will be displayed at the top of the table page, and will also show in the cog menu for each column. 
             You can see an example of how these look at  latest.datasette.io/fixtures/roadside_attractions .",154,
785,"Source, license and about","The three visible metadata fields you can apply to everything, specific databases or specific tables are source, license and about. All three are optional. 
             source  and  source_url  should be used to indicate where the underlying data came from. 
             license  and  license_url  should be used to indicate the license under which the data can be used. 
             about  and  about_url  can be used to link to further information about the project - an accompanying blog entry for example. 
             For each of these you can provide just the  *_url  field and Datasette will treat that as the default link label text and display the URL directly on the page.",154,
784,Per-database and per-table metadata,"Metadata at the top level of the file will be shown on the index page and in the
                footer on every page of the site. The license and source is expected to apply to
                all of your data. 
             You can also provide metadata at the per-database or per-table level, like this: 
             [[[cog
metadata_example(cog, {
    ""databases"": {
        ""database1"": {
            ""source"": ""Alternative source"",
            ""source_url"": ""http://example.com/"",
            ""tables"": {
                ""example_table"": {
                    ""description_html"": ""Custom <em>table</em> description"",
                    ""license"": ""CC BY 3.0 US"",
                    ""license_url"": ""https://creativecommons.org/licenses/by/3.0/us/""
                }
            }
        }
    }
}) 
             ]]] 
             [[[end]]] 
             Each of the top-level metadata fields can be used at the database and table level.",154,
783,Metadata,"Data loves metadata. Any time you run Datasette you can optionally include a
            YAML or JSON file with metadata about your databases and tables. Datasette will then
            display that information in the web UI. 
         Run Datasette like this: 
         datasette database1.db database2.db --metadata metadata.yaml 
         Your  metadata.yaml  file can look something like this: 
         [[[cog
from metadata_doc import metadata_example
metadata_example(cog, {
    ""title"": ""Custom title for your index page"",
    ""description"": ""Some description text can go here"",
    ""license"": ""ODbL"",
    ""license_url"": ""https://opendatacommons.org/licenses/odbl/"",
    ""source"": ""Original Data Source"",
    ""source_url"": ""http://example.com/""
}) 
         ]]] 
         [[[end]]] 
         Choosing YAML over JSON adds support for multi-line strings and comments. 
         The above metadata will be displayed on the index page of your Datasette-powered
            site. The source and license information will also be included in the footer of
            every page served by Datasette. 
         Any special HTML characters in  description  will be escaped. If you want to
            include HTML in your description, you can use a  description_html  property
            instead.",154,
782,Selectors,"These are available on the  selectors  property of the  datasetteManager  object. 
             const DOM_SELECTORS = {
  /** Should have one match */
  jsonExportLink: "".export-links a[href*=json]"",

  /** Event listeners that go outside of the main table, e.g. existing scroll listener */
  tableWrapper: "".table-wrapper"",
  table: ""table.rows-and-columns"",
  aboveTablePanel: "".above-table-panel"",

  // These could have multiple matches
  /** Used for selecting table headers. Use makeColumnActions if you want to add menu items. */
  tableHeaders: `table.rows-and-columns th`,

  /** Used to add ""where""  clauses to query using direct manipulation */
  filterRows: "".filter-row"",
  /** Used to show top available enum values for a column (""facets"") */
  facetResults: "".facet-results [data-column]"",
};",154,
781,Accessibility,"Custom fields are responsible for preserving the accessibility of the form: 
                     
                         
                             The visible field label should name the control. Use  field.labelId  with  aria-labelledby  when wrapping or replacing the visible input. 
                         
                         
                             Field metadata should remain available to assistive technology. Use  field.descriptionId  with  aria-describedby . 
                         
                         
                             Keyboard users must be able to operate every part of the custom field. 
                         
                         
                             If the field opens an inline picker or other nested UI,  Escape  should close that nested UI first and return focus to a sensible element. 
                         
                         
                             If a control performs asynchronous loading, expose loading and error states in the UI. Use appropriate ARIA live regions where the state change is important to understand the field. 
                         
                         
                             If a plugin hides  field.input , the replacement UI must still make the current value and available actions clear. 
                         
                     
                     Plugins should not submit the row themselves from inside  makeColumnField()  controls. Datasette owns the insert/edit dialog lifecycle, form submission, API call, error handling and row refresh.",154,
780,Example: textarea-backed custom element,"This example handles a  markdown-editor  column type by asking Datasette for a textarea and wrapping that textarea in a custom  <my-markdown-editor>  Web Component element: 
                     document.addEventListener(""datasette_init"", function (event) {
  event.detail.registerPlugin(""markdown-editor"", {
    version: ""0.1"",

    makeColumnField(context) {
      if (!context.columnType || context.columnType.type !== ""markdown-editor"") {
        return;
      }

      return {
        useTextarea: true,

        render(field) {
          const editor = document.createElement(""my-markdown-editor"");
          editor.appendChild(field.input);

          if (field.labelId) {
            field.input.setAttribute(""aria-labelledby"", field.labelId);
          }
          if (field.descriptionId) {
            field.input.setAttribute(""aria-describedby"", field.descriptionId);
          }

          return editor;
        },

        focus(field) {
          const editor = field.root.querySelector(""my-markdown-editor"");
          if (editor && editor.focus) {
            editor.focus();
          } else {
            field.input.focus();
          }
        }
      };
    }
  });
});",154,
779,Lazy loading large controls,"The JavaScript file that registers  makeColumnField()  should be small. If the actual control is large, load it from inside  render()  using dynamic  import() . That way the heavier code is only downloaded after a user opens an insert/edit dialog containing a matching column type. 
                     const editorUrl = new URL(""./editor.js"", import.meta.url).href;

document.addEventListener(""datasette_init"", function (event) {
  event.detail.registerPlugin(""my-editor"", {
    version: ""0.1"",

    makeColumnField(context) {
      if (!context.columnType || context.columnType.type !== ""my-editor"") {
        return;
      }
      return {
        useTextarea: true,
        render(field) {
          import(editorUrl).then(function () {
            // Enhance field.input here.
          });
          return field.input;
        }
      };
    }
  });
});",154,
778,Value helpers,"Custom fields should use  field.getValue()  and  field.setValue(value)  for value handling: 
                     const currentValue = field.getValue();
field.setValue(""new value"");
field.setValue(null); 
                     Plugins can keep the core input visible, wrap it in a custom element, or hide it and provide a richer interface. If the input is hidden, the custom UI must still expose an accessible name, state and keyboard interaction. 
                     field.setValue()  updates both  field.input  and the value used in the insert/update request. 
                     For example, a file picker that stores a selected file ID can hide the backing input and call  field.setValue()  when the selection changes: 
                     field.input.type = ""hidden"";
field.setValue(fileId); 
                     For insert forms with a SQLite default,  field.isUsingSqliteDefault()  indicates whether Datasette will omit that column from the insert payload. Calling  field.setValue(value)  automatically stops using the SQLite default.",154,
777,Submitted value contract,"The  field.setValue()  method accepts the following value types: 
                     
                         
                             string 
                         
                         
                             number 
                         
                         
                             boolean 
                         
                         
                             null 
                         
                     
                     These values are used as column values in requests to the  insert rows  and  update row  JSON APIs. 
                     Plugins should not pass objects or arrays to  field.setValue() . If a column stores structured data in SQLite, such as JSON in a  TEXT  column, the plugin should serialize that data first and submit the serialized string. Client-side parsing can still be useful for validation or editor state, but the submitted value should match the SQLite value Datasette should write.",154,
776,The field helper object,"The  field  object passed to  render(field) ,  focus(field)  and  destroy(field)  provides stable IDs, DOM elements and value helpers for integrating with the row insert/edit dialog: 
                     
                         
                             context  - object 
                             
                                 The original context object passed to  makeColumnField() . 
                             
                         
                         
                             id  - string 
                             
                                 The ID Datasette assigned to  field.input , the backing  <input>  or  <textarea>  element. 
                             
                         
                         
                             labelId  - string 
                             
                                 The ID of the visible field label. 
                             
                         
                         
                             descriptionId  - string 
                             
                                 The ID of the field metadata/help text. This metadata can include details such as  Primary key ,  Required ,  Current value: NULL  or  Custom type: file . 
                             
                         
                         
                             root  -  HTMLElement 
                             
                                 The empty  <div>  container created by Datasette for this custom field. It is inside the control area for the field in the row insert/edit dialog, next to the field label and above the field metadata. Datasette appends the DOM node returned by  render(field)  to this element. Plugins can alternatively manipulate this element directly and return nothing from  render(field) . 
                             
                         
                         
                             input  -  HTMLInputElement  or  HTMLTextAreaElement 
                             
                                 The core-owned backing form control. Plugins can keep this visible, wrap it or hide it, but should use the value helper methods below rather than mutating  input.value  directly. 
                             
                         
                         
                             control 
                             
                                 An alias for  input . 
                             
                         
                         
                             meta  -  HTMLElement  or null 
                             
                                 The field metadata/help text element. 
                             
                         
                         
                             form  -  HTMLFormElement  or null 
                             
                                 The containing row insert/edit form. 
                             
                         
                         
                             dialog  -  HTMLDialogElement  or null 
                             
                                 The containing modal dialog. 
                             
                         
                         
                             getValue()  - function 
                             
                                 Returns the current value for this field. 
                                 Datasette uses string values by default. Insert fields for  ""INTEGER""  and  ""REAL""  SQLite columns return numbers, or  null  if left blank. Plugins can use strings, numbers, booleans or  null . If a plugin is editing structured data stored in a SQLite  TEXT  column, such as JSON, it should serialize that data to a string before calling  setValue() . 
                             
                         
                         
                             setValue(value)  - function 
                             
                                 Sets the current value for this field.  value  should be a string, number, boolean or  null . 
                                 Calling  setValue()  also stops using the SQLite default for the field, if it was previously selected. 
                             
                         
                         
                             getInitialValue()  - function 
                             
                                 Returns the submitted-value representation the field had when the form was rendered. For edit forms this is the raw row value from the database. For insert forms this is the blank starting value. 
                             
                         
                         
                             hasChanged()  - function 
                             
                                 Returns true if the field has changed since Datasette last considered it unmodified. By default that means the field state when the insert/edit form was rendered. 
                             
                         
                         
                             clearValue()  - function 
                             
                                 Sets the value to  null . 
                             
                         
                         
                             markClean()  - function 
                             
                                 Tells Datasette to treat the field's current state as unmodified. After calling this method,  hasChanged()  returns false until the field value changes again or its SQLite-default state changes. 
                                 This is useful when a plugin rewrites the starting value into an equivalent representation while initializing its editor. For example, a rich text editor might normalize empty HTML or reserialize its initial document before the user has made any edits. 
                             
                         
                         
                             isUsingSqliteDefault()  - function 
                             
                                 Returns true if the insert dialog is currently set to omit this column and use the SQLite default. 
                             
                         
                         
                             setValidity(message)  - function 
                             
                                 Sets a custom validation message for this field, marks the backing input with  aria-invalid=""true""  and shows the message in the field metadata area. Pass an empty string to clear the error. 
                             
                         
                         
                             clearValidity()  - function 
                             
                                 Clears any custom validation message previously set by  setValidity() .",154,
775,Returned control object,"A plugin that wants to handle a field should return an object. Datasette currently recognizes these properties: 
                     
                         
                             useTextarea  - boolean, optional 
                             
                                 If true, Datasette creates a  <textarea>  as the underlying  field.input  before calling  render() . If omitted, Datasette chooses either an  <input>  or  <textarea>  based on the column type and current value. 
                             
                         
                         
                             render(field)  - function 
                             
                                 Called once to render the custom field UI.  field  is a helper object described below. 
                                 The recommended pattern is to return a DOM node from  render() . Datasette appends that node to  field.root , a  <div>  inside the control area for that field in the row insert/edit dialog. A plugin can alternatively manipulate  field.root  directly and return nothing. 
                             
                         
                         
                             focus(field)  - function, optional 
                             
                                 Called when Datasette wants to focus this field, for example when focusing the first editable field in the dialog. Use this to focus the most useful interactive element inside the custom UI. 
                             
                         
                         
                             destroy(field)  - function, optional 
                             
                                 Called when Datasette tears down the insert/edit form. Use this to remove event listeners, close nested pickers, revoke object URLs, clear timers, or release other resources.",154,
774,Context object,"makeColumnField(context)  is called with a context object describing the field. The current context object has these keys: 
                     
                         
                             mode  - string 
                             
                                 ""insert""  or  ""edit"" . 
                             
                         
                         
                             database  - string or null 
                             
                                 The database name. 
                             
                         
                         
                             table  - string or null 
                             
                                 The table name. 
                             
                         
                         
                             tableUrl  - string or null 
                             
                                 The path to the table page, including any configured  base URL prefix . 
                             
                         
                         
                             column  - string 
                             
                                 The column name. 
                             
                         
                         
                             columnType  - object or null 
                             
                                 The configured Datasette column type for this column, if one exists. This is  null  if no column type has been configured. 
                                 If present, this object has exactly these keys: 
                                 
                                     
                                         type  - string 
                                         
                                             The  registered column type name , matching the  name  attribute of the Python  ColumnType  subclass. 
                                         
                                     
                                     
                                         config  - object 
                                         
                                             Configuration for this specific column type assignment. This is  {}  if no configuration has been set. 
                                         
                                     
                                 
                             
                         
                         
                             sqliteType  - string or null 
                             
                                 The SQLite affinity for this column, if known. This is one of  ""TEXT"" ,  ""INTEGER"" ,  ""REAL"" ,  ""BLOB"" ,  ""NUMERIC""  or  null  if Datasette could not determine the affinity. 
                             
                         
                         
                             notNull  - boolean 
                             
                                 True if the column is defined as  NOT NULL . 
                             
                         
                         
                             isPk  - boolean 
                             
                                 True if this column is part of the table's primary key. 
                             
                         
                         
                             defaultExpression  - string or null 
                             
                                 The SQLite default expression for the column, if available. This is  null  if the column has no SQLite default. For example, a column defined with  DEFAULT (datetime('now'))  will have  ""datetime('now')""  here. This is the expression from the table schema, not the actual value SQLite will insert. 
                             
                         
                         
                             form  -  HTMLFormElement  or null 
                             
                                 The row insert/edit form element. 
                             
                         
                         
                             dialog  -  HTMLDialogElement  or null 
                             
                                 The modal dialog element.",154,
773,makeColumnField(context),"This method, if present, can provide a custom form field for a column in Datasette's row insert and edit dialogs. 
                 It is designed for plugins that  register custom column types  using the Python  register_column_types()  plugin hook. For example, a plugin that defines a  file  column type can use  makeColumnField()  to replace a plain text input with a file picker, and a plugin that defines a rich text column type can use it to enhance the field with an editor. 
                 Datasette calls  makeColumnField(context)  on each registered JavaScript plugin when it renders an editable insert/edit field. Plugins should inspect the  context  object and only return a control object if they can handle that field. Otherwise, use a bare  return; . 
                 The first plugin to return a truthy control object is used for that field. Plugins are called in registration order. If a plugin raises an exception, Datasette logs the error to the browser console and continues to the next plugin. 
                 The row dialog tracks the value that will be sent to the insert/update API. The  context  object describes the column and form environment; custom controls should read and write field values using the  field  helper object passed to  render(field) .",154,
772,makeColumnActions(columnDetails),"This method, if present, will be called when Datasette is rendering the cog action menu icons that appear at the top of the table view. By default these include options like ""Sort ascending/descending"" and ""Facet by this"", but plugins can return additional actions to be included in this menu. 
                 The method will be called with a  columnDetails  object with the following keys: 
                 
                     
                         columnName  - string 
                         
                             The name of the column 
                         
                     
                     
                         columnNotNull  - boolean 
                         
                             True if the column is defined as NOT NULL 
                         
                     
                     
                         columnType  - string 
                         
                             The SQLite data type of the column 
                         
                     
                     
                         isPk  - boolean 
                         
                             True if the column is part of the primary key 
                         
                     
                 
                 It should return a JavaScript array of objects each with a  label  and  onClick  property: 
                 
                     
                         label  - string 
                         
                             The human-readable label for the action 
                         
                     
                     
                         onClick(evt)  - function 
                         
                             A function that will be called when the action is clicked 
                         
                     
                 
                 The  evt  object passed to the  onClick  is the standard browser event object that triggered the click. 
                 This example plugin adds two menu items - one to copy the column name to the clipboard and another that displays the column metadata in an  alert()  window: 
                 document.addEventListener('datasette_init', function(ev) {
  ev.detail.registerPlugin('column-name-plugin', {
    version: 0.1,
    makeColumnActions: (columnDetails) => {
      return [
        {
          label: 'Copy column to clipboard',
          onClick: async (evt) => {
            await navigator.clipboard.writeText(columnDetails.columnName)
          }
        },
        {
          label: 'Alert column metadata',
          onClick: () => alert(JSON.stringify(columnDetails, null, 2))
        }
      ];
    }
  });
});",154,
771,makeAboveTablePanelConfigs(),"This method should return a JavaScript array of objects defining additional panels to be added to the top of the table page. Each object should have the following: 
                 
                     
                         id  - string 
                         
                             A unique string ID for the panel, for example  map-panel 
                         
                     
                     
                         label  - string 
                         
                             A human-readable label for the panel 
                         
                     
                     
                         render(node)  - function 
                         
                             A function that will be called with a DOM node to render the panel into 
                         
                     
                 
                 This example shows how a plugin might define a single panel: 
                 document.addEventListener('datasette_init', function(ev) {
  ev.detail.registerPlugin('panel-plugin', {
    version: 0.1,
    makeAboveTablePanelConfigs: () => {
      return [
        {
          id: 'first-panel',
          label: 'First panel',
          render: node => {
            node.innerHTML = '<h2>My custom panel</h2><p>This is a custom panel that I added using a JavaScript plugin</p>';
          }
        }
      ]
    }
  });
}); 
                 When a page with a table loads, all registered plugins that implement  makeAboveTablePanelConfigs()  will be called and panels they return will be added to the top of the table page.",154,
770,makeJumpSections(context),"This method should return a JavaScript array of objects defining additional sections to be added to the blank state of the  /  jump menu, before the user starts typing a search. 
                 It should return an array of objects, each with the following: 
                 
                     
                         id  - string 
                         
                             A unique string ID for the section, for example  agent-chat 
                         
                     
                     
                         render(node, context)  - function 
                         
                             A function that will be called with a DOM node to render the section into 
                         
                     
                 
                 Datasette passes a  context  object to both  makeJumpSections(context)  and  render(node, context) . It has the following keys: 
                 
                     
                         navigationSearch 
                         
                             The  <navigation-search>  custom element instance. 
                         
                     
                     
                         container  - only for  render() 
                         
                             The  .results-container  element used by the jump menu. 
                         
                     
                     
                         input  - only for  render() 
                         
                             The  .search-input  element used by the jump menu. 
                         
                     
                 
                 This example shows how a plugin might add a button for starting a new chat: 
                 document.addEventListener('datasette_init', function(ev) {
  ev.detail.registerPlugin('agent-plugin', {
    version: 0.1,
    makeJumpSections: (context) => {
      return [
        {
          id: 'agent-chat',
          render: (node, context) => {
            node.innerHTML = '<button type=""button"">Start a new chat</button>';
            node.querySelector('button').addEventListener('click', () => {
              location.href = '/-/agent/new';
            });
          }
        }
      ];
    }
  });
});",154,
769,JavaScript plugin objects,"JavaScript plugins are blocks of code that can be registered with Datasette using the  registerPlugin()  method on the  datasetteManager  object. 
             The  implementation  object passed to this method should include a  version  key defining the plugin version, and one or more of the following named functions providing the implementation of the plugin:",154,
768,datasetteManager,"The  datasetteManager  object 
             
                 
                     VERSION  - string 
                     
                         The version of Datasette 
                     
                 
                 
                     plugins  -  Map() 
                     
                         A Map of currently loaded plugin names to plugin implementations 
                     
                 
                 
                     registerPlugin(name, implementation) 
                     
                         Call this to register a plugin, passing its name and implementation 
                     
                 
                 
                     makeColumnField(context) 
                     
                         Calls the  makeColumnField()  hook on registered plugins, returning the first custom insert/edit field control that matches the provided field context. This is used internally by Datasette's row insert and edit dialogs. 
                     
                 
                 
                     selectors  - object 
                     
                         An object providing named aliases to useful CSS selectors,  listed below",154,
767,The datasette_init event,"Datasette emits a custom event called  datasette_init  when the page is loaded. This event is dispatched on the  document  object, and includes a  detail  object with a reference to the  datasetteManager  object. 
             Your JavaScript code can listen out for this event using  document.addEventListener()  like this: 
             document.addEventListener(""datasette_init"", function (evt) {
    const manager = evt.detail;
    console.log(""Datasette version:"", manager.VERSION);
});",154,
766,JavaScript plugins,"Datasette can run custom JavaScript in several different ways: 
         
             
                 Datasette plugins written in Python can use the  extra_js_urls()  or  extra_body_script()  plugin hooks to inject JavaScript into a page 
             
             
                 Datasette instances with  custom templates  can include additional JavaScript in those templates 
             
             
                 The  extra_js_urls  key in  datasette.yaml   can be used to include extra JavaScript 
             
         
         There are no limitations on what this JavaScript can do. It is executed directly by the browser, so it can manipulate the DOM, fetch additional data and do anything else that JavaScript is capable of. 
         
             Custom JavaScript has security implications, especially for authenticated Datasette instances where the JavaScript might run in the context of the authenticated user. It's important to carefully review any JavaScript you run in your Datasette instance.",154,
765,Table schema,"Use  /database-name/table-name/-/schema  to see the schema for a specific table. The  .md  and  .json  extensions work here too. The JSON returns an object with  ""ok"" ,  ""database"" ,  ""table"" , and  ""schema""  keys.",154,
764,Database schema,"Use  /database-name/-/schema  to see the complete schema for a specific database. The  .md  and  .json  extensions work here too. The JSON returns an object with  ""ok"" ,  ""database""  and  ""schema""  keys.",154,
763,Instance schema,"Access  /-/schema  to see the complete schema for all attached databases in the Datasette instance. 
                 Use  /-/schema.md  to get the same information as Markdown. 
                 Use  /-/schema.json  to get the same information as JSON, which looks like this: 
                 {
  ""ok"": true,
  ""schemas"": [
    {
      ""database"": ""content"",
      ""schema"": ""create table posts ...""
    }
  ]
}",154,
762,Schemas,Datasette offers  /-/schema  endpoints to expose the SQL schema for databases and tables.,154,
761,Row,"Every row in every Datasette table has its own URL. This means individual records can be linked to directly. 
             Table cells with extremely long text contents are truncated on the table view according to the  truncate_cells_html  setting. If a cell has been truncated the full length version of that cell will be available on the row page. 
             Rows which are the targets of foreign key references from other tables will show a link to a filtered search for all records that reference that row. Here's an example from the Registers of Members Interests database: 
             ../people/uk~2Eorg~2Epublicwhip~2Fperson~2F10001 
             Note that this URL includes the encoded primary key of the record. 
             Here's that same page as JSON: 
             ../people/uk~2Eorg~2Epublicwhip~2Fperson~2F10001.json",154,
760,Table fragment,"The  /<database>/<table>/-/fragment  endpoint returns the rendered table HTML
                    for rows matching the provided filters. It is used by Datasette's row editing
                    interface to refresh rows after changes while still respecting custom table
                    templates and  render_cell  plugin hooks.",154,
759,Table,"The table page is the heart of Datasette: it allows users to interactively explore the contents of a database table, including sorting, filtering,  Full-text search  and applying  Facets . 
             The HTML interface is worth spending some time exploring. As with other pages, you can return the JSON data by appending  .json  to the URL path, before any  ?  query string arguments. 
             The query string arguments are described in more detail here:  Table arguments 
             You can also use the table page to interactively construct a SQL query - by applying different filters and a sort order for example - and then click the ""View and edit SQL"" link to see the SQL query that was used for the page and edit and re-submit it. 
             Some examples: 
             
                 
                     ../items  lists all of the line-items registered by UK MPs as potential conflicts of interest. It demonstrates Datasette's support for  Full-text search . 
                 
                 
                     ../antiquities-act%2Factions_under_antiquities_act  is an interface for exploring the ""actions under the antiquities act"" data table published by FiveThirtyEight. 
                 
                 
                     ../global-power-plants?country_long=United+Kingdom&primary_fuel=Gas  is a filtered table page showing every Gas power plant in the United Kingdom. It includes some default facets (configured using  its metadata.json ) and uses the  datasette-cluster-map  plugin to show a map of the results.",154,
758,Stored query browsers,"The  /-/queries  page lists stored queries across every database visible to the current actor. The  /database-name/-/queries  page lists stored queries for a single database. The JSON versions accept  ?_size=  (default 50,  max  for the  max_returned_rows  limit) and a  ?_next=  pagination token. 
                 These pages support search, pagination and filters for read-only or writable queries and private or public queries. Adding a  .json  extension to either URL returns the same list as JSON.",154,
757,Write SQL queries,"The  /database-name/-/execute-write  page can be used to execute SQL statements that write to a mutable database, if the  execute-write-sql  permission is enabled. 
                 This page extracts named parameters from the SQL, shows the tables that will be affected and lists the permissions required before the query can be executed. It also includes templates for common  INSERT ,  UPDATE  and  DELETE  statements. 
                 Datasette checks additional permissions based on the operations in the SQL. Row changes require the relevant table-level permissions such as  insert-row ,  update-row  and  delete-row ; reads from source tables require  view-table ; and schema changes require permissions such as  create-table ,  alter-table  or  drop-table . 
                 Use the  Executing write SQL  JSON API to execute writable SQL programmatically.",154,
756,Custom SQL queries,"The  /database-name/-/query  page can be used to execute an arbitrary SQL query against that database, if the  execute-sql  permission is enabled. This query is passed as the  ?sql=  query string parameter. 
                 This means you can link directly to a query by constructing the following URL: 
                 /database-name/-/query?sql=SELECT+*+FROM+table_name 
                 Each configured  stored query  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.",154,
755,Queries,,154,
754,Hidden tables,"Some tables listed on the database page are treated as hidden. Hidden tables are not completely invisible - they can be accessed through the ""hidden tables"" link at the bottom of the page. They are hidden because they represent low-level implementation details which are generally not useful to end-users of Datasette. 
                 The following tables are hidden by default: 
                 
                     
                         Any table with a name that starts with an underscore - this is a Datasette convention to help plugins easily hide their own internal tables. 
                     
                     
                         Tables that have been configured as  ""hidden"": true  using  hidden . 
                     
                     
                         *_fts  tables that implement SQLite full-text search indexes. 
                     
                     
                         Tables relating to the inner workings of the SpatiaLite SQLite extension. 
                     
                     
                         sqlite_stat  tables used to store statistics used by the query optimizer.",154,
753,Database,"Each database has a page listing the tables, views and stored queries available for that database. If the  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: 
             
                 
                     fivethirtyeight.datasettes.com/fivethirtyeight 
                 
                 
                     datasette.io/global-power-plants 
                 
             
             The JSON version of this page provides programmatic access to the underlying data: 
             
                 
                     fivethirtyeight.datasettes.com/fivethirtyeight.json 
                 
                 
                     datasette.io/global-power-plants.json 
                 
             
             The returned object includes an  ""ok"": true  key alongside keys such as  ""database"" ,  ""tables"" ,  ""views"" ,  ""queries""  and  ""metadata"" .",154,
752,Top-level index,"The root page of any Datasette installation is an index page that lists all of the currently attached databases. Some examples: 
             
                 
                     fivethirtyeight.datasettes.com 
                 
                 
                     register-of-members-interests.datasettes.com 
                 
             
             Add  /.json  to the end of the URL for the JSON version of the underlying data: 
             
                 
                     fivethirtyeight.datasettes.com/.json 
                 
                 
                     register-of-members-interests.datasettes.com/.json 
                 
             
             The index page can also be accessed at  /-/ , useful for if the default index page has been replaced using an  index.html custom template . The  /-/  page will always render the default Datasette  index.html  template.",154,
751,Pages and API endpoints,"The Datasette web application offers a number of different pages that can be accessed to explore the data in question, each of which is accompanied by an equivalent JSON API.",154,
750,/-/messages,"The debug tool at  /-/messages  can be used to set flash messages to try out that feature. See  .add_message(request, message, type=datasette.INFO)  for details of this feature.",154,
749,/-/actor,"Shows the currently authenticated actor. Useful for debugging Datasette authentication plugins. 
             {
    ""ok"": true,
    ""actor"": {
        ""id"": 1,
        ""username"": ""some-user""
    }
}",154,
748,/-/threads,"Shows details of threads and  asyncio  tasks. This endpoint requires the  permissions-debug  permission, since it exposes runtime internals.  Threads example : 
             {
    ""ok"": true,
    ""num_threads"": 2,
    ""threads"": [
        {
            ""daemon"": false,
            ""ident"": 4759197120,
            ""name"": ""MainThread""
        },
        {
            ""daemon"": true,
            ""ident"": 123145319682048,
            ""name"": ""Thread-1""
        },
    ],
    ""num_tasks"": 3,
    ""tasks"": [
        ""<Task pending coro=<RequestResponseCycle.run_asgi() running at uvicorn/protocols/http/httptools_impl.py:385> cb=[set.discard()]>"",
        ""<Task pending coro=<Server.serve() running at uvicorn/main.py:361> wait_for=<Future pending cb=[<TaskWakeupMethWrapper object at 0x10365c3d0>()]> cb=[run_until_complete.<locals>.<lambda>()]>"",
        ""<Task pending coro=<LifespanOn.main() running at uvicorn/lifespan/on.py:48> wait_for=<Future pending cb=[<TaskWakeupMethWrapper object at 0x10364f050>()]>>""
    ]
}",154,
747,/-/debug/autocomplete,"The debug tool at  /-/debug/autocomplete  can be used to try out the autocomplete component against a specific table. Pass  ?database=db&table=table  to display an autocomplete field backed by that table's  /-/autocomplete  endpoint. 
             Without those query string arguments, the page lists up to five tables with detected label columns, scanning at most 100 tables.",154,
746,/-/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 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. 
             The endpoint supports a  ?q=  query parameter for filtering items by name. 
             Jump example : 
             {
    ""ok"": true,
    ""matches"": [
        {
            ""name"": ""fixtures"",
            ""url"": ""/fixtures"",
            ""type"": ""database"",
            ""description"": null
        },
        {
            ""name"": ""fixtures: facetable"",
            ""url"": ""/fixtures/facetable"",
            ""type"": ""table"",
            ""description"": null
        },
        {
            ""name"": ""fixtures: recent_releases"",
            ""url"": ""/fixtures/recent_releases"",
            ""type"": ""query"",
            ""description"": null
        }
    ],
    ""truncated"": false
} 
             Search example with  ?q=facet  returns only items matching  .*facet.* : 
             {
    ""ok"": true,
    ""matches"": [
        {
            ""name"": ""fixtures: facetable"",
            ""url"": ""/fixtures/facetable"",
            ""type"": ""table"",
            ""description"": null
        }
    ],
    ""truncated"": false
} 
             When multiple search terms are provided (e.g.,  ?q=user+profile ), items must match the pattern  .*user.*profile.* . Results are ordered by relevance, then by item type and shortest display name.",154,
745,/-/actions,"Shows all actions registered with the permission system, including those added by plugins. Requires the  permissions-debug  permission. 
             {
    ""ok"": true,
    ""actions"": [
        {
            ""name"": ""view-instance"",
            ""abbr"": ""vi"",
            ""description"": ""View Datasette instance"",
            ""takes_parent"": false,
            ""takes_child"": false,
            ""resource_class"": null,
            ""also_requires"": null
        }
    ]
}",154,
744,/-/databases,"Shows currently attached databases that the current actor is allowed to view, based on the  view-database  permission.  Databases example : 
             {
    ""ok"": true,
    ""databases"": [
        {
            ""hash"": null,
            ""is_memory"": false,
            ""is_mutable"": true,
            ""name"": ""fixtures"",
            ""path"": ""fixtures.db"",
            ""size"": 225280
        }
    ]
}",154,
743,/-/config,"Shows the  configuration  for this instance of Datasette. This is generally the contents of the  datasette.yaml or datasette.json  file, which can include plugin configuration as well.  Config example : 
             {
    ""ok"": true,
    ""settings"": {
        ""template_debug"": true,
        ""trace_debug"": true,
        ""force_https_urls"": true
    }
} 
             Any keys that include the one of the following substrings in their names will be returned as redacted  ***  output, to help avoid accidentally leaking private configuration information:  secret ,  key ,  password ,  token ,  hash ,  dsn .",154,
742,/-/settings,"Shows the  Settings  for this instance of Datasette.  Settings example : 
             {
    ""ok"": true,
    ""default_facet_size"": 30,
    ""default_page_size"": 100,
    ""facet_suggest_time_limit_ms"": 50,
    ""facet_time_limit_ms"": 1000,
    ""max_returned_rows"": 1000,
    ""sql_time_limit_ms"": 1000
}",154,
741,/-/plugins,"Shows a list of currently installed plugins and their versions.  Plugins example : 
             {
    ""ok"": true,
    ""plugins"": [
        {
            ""name"": ""datasette_cluster_map"",
            ""static"": true,
            ""templates"": false,
            ""version"": ""0.10"",
            ""hooks"": [""extra_css_urls"", ""extra_js_urls"", ""extra_body_script""]
        }
    ]
} 
             Add  ?all=1  to include details of the default plugins baked into Datasette.",154,
740,/-/versions,"Shows the version of Datasette, Python and SQLite.  Versions example : 
             {
    ""ok"": true,
    ""datasette"": {
        ""version"": ""0.60""
    },
    ""python"": {
        ""full"": ""3.8.12 (default, Dec 21 2021, 10:45:09) \n[GCC 10.2.1 20210110]"",
        ""version"": ""3.8.12""
    },
    ""sqlite"": {
        ""extensions"": {
            ""json1"": null
        },
        ""fts_versions"": [
            ""FTS5"",
            ""FTS4"",
            ""FTS3""
        ],
        ""compile_options"": [
            ""COMPILER=gcc-6.3.0 20170516"",
            ""ENABLE_FTS3"",
            ""ENABLE_FTS4"",
            ""ENABLE_FTS5"",
            ""ENABLE_JSON1"",
            ""ENABLE_RTREE"",
            ""THREADSAFE=1""
        ],
        ""version"": ""3.37.0""
    }
}",154,
739,/-/metadata,"Shows the contents of the  metadata.json  file that was passed to  datasette serve , if any.  Metadata example : 
             {
    ""license"": ""CC Attribution 4.0 License"",
    ""license_url"": ""http://creativecommons.org/licenses/by/4.0/"",
    ""source"": ""fivethirtyeight/data on GitHub"",
    ""source_url"": ""https://github.com/fivethirtyeight/data"",
    ""title"": ""Five Thirty Eight"",
    ""databases"": {

    }
}",154,
738,Introspection,"Datasette includes some pages and JSON API endpoints for introspecting the current instance. These can be used to understand some of the internals of Datasette and to see how a particular instance has been configured. 
         Each of these pages can be viewed in your browser. Add  .json  to the URL to get back the contents as JSON. 
         JSON responses that return an object include an  ""ok"": true  key, consistent with the rest of the  JSON API . 
         The introspection endpoints documented on this page are covered by the  JSON API stability promise , with the exception of the debug endpoints  /-/threads  and  /-/actions , whose shapes may change in future releases.",154,
737,Row page,"The page showing an individual row, e.g. /fixtures/facetable/1. Rendered using the  row.html  template. 
             Many of these keys are shared with the  JSON API  for this page. 
             
                 
                     alternate_url_json  -  str 
                     
                         URL for the JSON version of this page 
                     
                 
                 
                     columns  -  list 
                     
                         List of column names returned by this table, row or query. 
                     
                 
                 
                     custom_table_templates  -  list 
                     
                         Custom template names that were considered for displaying this row's table, in lookup order. 
                     
                 
                 
                     database  -  str 
                     
                         Database name 
                     
                 
                 
                     database_color  -  str 
                     
                         Color assigned to the database 
                     
                 
                 
                     display_columns  -  list 
                     
                         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 
                     
                         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 
                     
                         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 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 
                     
                 
                 
                     primary_key_values  -  list 
                     
                         Values of the primary keys for this row, from the URL 
                     
                 
                 
                     primary_keys  -  list 
                     
                         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_ms  -  float 
                     
                         Time taken by the SQL queries for this page, in milliseconds 
                     
                 
                 
                     renderers  -  dict 
                     
                         Dictionary mapping output format names such as  json  to URLs for this row in that format. 
                     
                 
                 
                     row_actions  -  list 
                     
                         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  Action hooks  and  row_actions(datasette, actor, request, database, table, row) . 
                     
                 
                 
                     row_mutation_ui  -  bool 
                     
                         True if the row edit/delete JavaScript UI should be enabled 
                     
                 
                 
                     rows  -  list 
                     
                         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, with the selected template prefixed by  * . 
                     
                 
                 
                     settings  -  dict 
                     
                         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. Includes  database ,  table  and  tableUrl , plus optional  foreignKeys  mapping column names to autocomplete URLs. 
                     
                 
                 
                     top_row  -  callable 
                     
                         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 
                     
                         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 
                     
                 
             
             [[[end]]]",154,
736,Table page,"The page showing the rows in a table or SQL view, e.g. /fixtures/facetable. Rendered using the  table.html  template. 
             Many of these keys are shared with the  JSON API  for this page. 
             
                 
                     actions  -  callable 
                     
                         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  Action hooks ,  table_actions(datasette, actor, database, table, request)  and  view_actions(datasette, actor, database, view, request) . 
                     
                 
                 
                     all_columns  -  list 
                     
                         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 
                     
                 
                 
                     alternate_url_json  -  str 
                     
                         URL for the JSON version of this page 
                     
                 
                 
                     append_querystring  -  callable 
                     
                         Function  append_querystring(url, querystring)  that appends additional query string arguments to a URL, using  ?  or  &  as appropriate. 
                     
                 
                 
                     columns  -  list 
                     
                         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 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 
                     
                         List of custom template names considered for rendering table rows, in lookup order. 
                     
                 
                 
                     database  -  str 
                     
                         Database name 
                     
                 
                 
                     database_color  -  str 
                     
                         Color assigned to the database 
                     
                 
                 
                     datasette_allow_facet  -  str 
                     
                         The string ""true"" or ""false"" reflecting the allow_facet setting 
                     
                 
                 
                     display_columns  -  list 
                     
                         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 
                     
                         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 
                     
                         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=  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. 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 
                     
                         List of names of facet calculations that exceeded the facet time limit. 
                     
                 
                 
                     filter_columns  -  list 
                     
                         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. Useful methods include  filters.human_description_en() ; this is not JSON serializable. 
                     
                 
                 
                     fix_path  -  callable 
                     
                         Function that applies the configured  base_url  prefix to a path. 
                     
                 
                 
                     form_hidden_args  -  list 
                     
                         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 
                     
                 
                 
                     is_sortable  -  bool 
                     
                         True if any of the displayed columns can be used to sort 
                     
                 
                 
                     is_view  -  bool 
                     
                         Whether this resource is a view instead of a table 
                     
                 
                 
                     metadata  -  dict 
                     
                         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 
                     
                 
                 
                     next_url  -  str 
                     
                         Full URL for the next page of results, or None if there are no more pages. See  Pagination . 
                     
                 
                 
                     ok  -  bool 
                     
                         True if the data for this page was retrieved without errors 
                     
                 
                 
                     path_with_replaced_args  -  callable 
                     
                         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 
                     
                         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 as a dictionary with  sql  and  params  keys. 
                     
                 
                 
                     query_ms  -  float 
                     
                         Time taken by the SQL queries for this page, in milliseconds 
                     
                 
                 
                     renderers  -  dict 
                     
                         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 raw value. 
                     
                 
                 
                     select_templates  -  list 
                     
                         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, 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, keyed by setting name. 
                     
                 
                 
                     sort  -  str 
                     
                         Column the page is sorted by, or None 
                     
                 
                 
                     sort_desc  -  str 
                     
                         Column the page is sorted by in descending order, or None 
                     
                 
                 
                     sorted_facet_results  -  list 
                     
                         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. 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 
                     
                 
                 
                     table  -  str 
                     
                         Table name 
                     
                 
                 
                     table_alter_ui  -  dict 
                     
                         Information needed to enable the alter table UI, or  None  if altering this table is not available to the current actor. When present it has  path ,  tableName ,  columns ,  primaryKeys ,  columnTypes ,  defaultExpressions  and  foreignKeyTargetsPath  keys, plus optional  customColumnTypes  and  dropPath  keys. 
                     
                 
                 
                     table_definition  -  str 
                     
                         SQL definition for this table 
                     
                 
                 
                     table_insert_ui  -  dict 
                     
                         Information needed to enable the row insertion UI, or  None  if row insertion is not available to the current actor. When present it has  path ,  tableName ,  columns ,  bulkColumns ,  primaryKeys  and  maxInsertRows  keys, plus optional  upsertPath  if the current actor has permission to update rows.  columns  lists columns for the single-row insert form, while  bulkColumns  lists columns for the bulk insert form. Each column includes  name ,  sqlite_type ,  notnull ,  default ,  has_default ,  is_pk ,  is_auto_pk ,  value_kind  and  column_type  keys. 
                     
                 
                 
                     table_page_data  -  dict 
                     
                         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 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 
                     
                         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 
                     
                 
                 
                     view_definition  -  str 
                     
                         SQL definition for this view",154,
735,Query page,"The page for arbitrary SQL queries (/database/-/query?sql=...) and stored queries (/database/query-name). Rendered using the  query.html  template. 
             
                 
                     allow_execute_sql  -  bool 
                     
                         Boolean indicating if custom SQL can be executed 
                     
                 
                 
                     alternate_url_json  -  str 
                     
                         URL for alternate JSON version of this page 
                     
                 
                 
                     columns  -  list 
                     
                         List of result column names in the order they appear in  display_rows  and  rows . 
                     
                 
                 
                     database  -  str 
                     
                         The name of the database being queried 
                     
                 
                 
                     database_color  -  str 
                     
                         The color of the database 
                     
                 
                 
                     db_is_immutable  -  bool 
                     
                         Boolean indicating if this database is immutable 
                     
                 
                 
                     display_rows  -  list 
                     
                         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 
                     
                 
                 
                     editable  -  bool 
                     
                         Boolean indicating if the SQL can be edited 
                     
                 
                 
                     error  -  str 
                     
                         Any query error message 
                     
                 
                 
                     hide_sql  -  bool 
                     
                         Boolean indicating if the SQL should be hidden 
                     
                 
                 
                     metadata  -  dict 
                     
                         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 named SQL parameter values, keyed by parameter name without the leading  : . 
                     
                 
                 
                     private  -  bool 
                     
                         Boolean indicating if this is a private database 
                     
                 
                 
                     query  -  dict 
                     
                         Dictionary describing the SQL query being executed, with  sql  and  params  keys. 
                     
                 
                 
                     query_actions  -  callable 
                     
                         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  Action hooks  and  query_actions(datasette, actor, database, query_name, request, sql, params) . 
                     
                 
                 
                     renderers  -  dict 
                     
                         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 template names that were considered for this page, with the selected template prefixed by  * . 
                     
                 
                 
                     show_hide_hidden  -  str 
                     
                         Rendered hidden  <input>  HTML preserving the current  _hide_sql  or  _show_sql  state. 
                     
                 
                 
                     show_hide_link  -  str 
                     
                         The URL to toggle showing/hiding the SQL 
                     
                 
                 
                     show_hide_text  -  str 
                     
                         The text for the show/hide SQL link 
                     
                 
                 
                     stored_query  -  str 
                     
                         The name of the stored query if this is a stored query 
                     
                 
                 
                     stored_query_write  -  bool 
                     
                         Boolean indicating if this is a stored query that allows writes 
                     
                 
                 
                     table_columns  -  dict 
                     
                         Dictionary mapping table names to lists of column names, used to power SQL autocomplete. 
                     
                 
                 
                     tables  -  list[DatabaseTable] 
                     
                         List of  DatabaseTable  objects describing tables in the database. Each item has  name ,  columns ,  primary_keys ,  count ,  count_truncated ,  hidden ,  fts_table ,  foreign_keys  and  private  attributes.  count_truncated  is true if  count  is a capped lower bound rather than an exact total. 
                     
                 
                 
                     top_query  -  callable 
                     
                         Async callable that renders the  top_query  plugin slot for this query and returns HTML. 
                     
                 
                 
                     top_stored_query  -  callable 
                     
                         Async callable that renders the  top_stored_query  plugin slot for stored queries and returns HTML. 
                     
                 
                 
                     url_csv  -  str 
                     
                         URL for CSV export",154,
734,Database page,"The page listing the tables, views and queries in a database, e.g. /fixtures. Rendered using the  database.html  template. 
             
                 
                     allow_download  -  bool 
                     
                         Boolean indicating if database download is allowed 
                     
                 
                 
                     allow_execute_sql  -  bool 
                     
                         Boolean indicating if custom SQL can be executed 
                     
                 
                 
                     alternate_url_json  -  str 
                     
                         URL for the alternate JSON version of this page 
                     
                 
                 
                     attached_databases  -  list 
                     
                         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  Cross-database queries . 
                     
                 
                 
                     database  -  str 
                     
                         The name of the database 
                     
                 
                 
                     database_actions  -  callable 
                     
                         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  Action hooks  and  database_actions(datasette, actor, database, request) . 
                     
                 
                 
                     database_color  -  str 
                     
                         The color assigned to the database 
                     
                 
                 
                     database_page_data  -  dict 
                     
                         JSON data used by JavaScript on the database page. Currently  {}  or  {""createTable"": {...}}  where  createTable  includes  path ,  foreignKeyTargetsPath ,  databaseName ,  columnTypes ,  defaultExpressions ,  canInsertRows  and optional  customColumnTypes . 
                     
                 
                 
                     editable  -  bool 
                     
                         Boolean indicating if the database is editable 
                     
                 
                 
                     hidden_count  -  int 
                     
                         Count of hidden tables 
                     
                 
                 
                     metadata  -  dict 
                     
                         Metadata dictionary for the database, such as  title ,  description ,  license  and  source  values from Datasette metadata. 
                     
                 
                 
                     path  -  str 
                     
                         The URL path to this database 
                     
                 
                 
                     private  -  bool 
                     
                         Boolean indicating if this is a private database 
                     
                 
                 
                     queries  -  list[StoredQuery] 
                     
                         List of  StoredQuery  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 
                     
                 
                 
                     queries_more  -  bool 
                     
                         Boolean indicating if more stored queries are available 
                     
                 
                 
                     select_templates  -  list 
                     
                         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 
                     
                 
                 
                     size  -  int 
                     
                         The size of the database in bytes 
                     
                 
                 
                     table_columns  -  dict 
                     
                         Dictionary mapping table names to lists of column names, used to power SQL autocomplete. 
                     
                 
                 
                     tables  -  list[DatabaseTable] 
                     
                         List of  DatabaseTable  objects describing tables in the database. Each item has  name ,  columns ,  primary_keys ,  count ,  count_truncated ,  hidden ,  fts_table ,  foreign_keys  and  private  attributes.  count_truncated  is true if  count  is a capped lower bound rather than an exact total. 
                     
                 
                 
                     top_database  -  callable 
                     
                         Async callable that renders the  top_database  plugin slot for this database and returns HTML. 
                     
                 
                 
                     views  -  list[DatabaseViewInfo] 
                     
                         List of  DatabaseViewInfo  objects describing SQLite views in the database. Each item has  name  and  private  attributes.",154,
733,Base context,"These variables are available on every page rendered by Datasette, including pages rendered by plugins that use  datasette.render_template() . Plugins can add additional variables using the  extra_template_vars(template, database, table, columns, view_name, request, datasette)  hook. 
             
                 
                     request 
                     
                         The current  Request object , or None. Common properties include  request.path ,  request.args ,  request.actor ,  request.url_vars  and  request.host . 
                     
                 
                 
                     crumb_items 
                     
                         Async function returning breadcrumb navigation items for the current page. Call it with  request=request  plus optional  database=  and  table=  arguments; it returns a list of  {""href"": url, ""label"": label}  dictionaries. 
                     
                 
                 
                     urls 
                     
                         Object with methods for constructing URLs within Datasette. Common methods include  urls.instance() ,  urls.database(database) ,  urls.table(database, table) ,  urls.query(database, query) ,  urls.row(database, table, row_path)  and  urls.static(path)  - see  datasette.urls . 
                     
                 
                 
                     actor 
                     
                         The currently authenticated actor dictionary, or None. Actors usually include an  id  key and may include any other keys supplied by authentication plugins. 
                     
                 
                 
                     menu_links 
                     
                         Async function returning links for the Datasette application menu, including links added by plugins. Each item is a link dictionary with  href  and  label  keys. See  menu_links(datasette, actor, request) ; for page action menus that can also include JavaScript-backed buttons, see  Action hooks . 
                     
                 
                 
                     display_actor 
                     
                         Function that accepts an actor dictionary and returns the display string used in the navigation menu. 
                     
                 
                 
                     show_logout 
                     
                         True if the logout link should be shown in the navigation menu 
                     
                 
                 
                     zip 
                     
                         Python's  zip()  builtin, made available to template logic 
                     
                 
                 
                     body_scripts 
                     
                         List of JavaScript snippets contributed by plugins using  extra_body_script(template, database, table, columns, view_name, request, datasette) . Each item is a dictionary with  script  containing JavaScript source and  module  indicating whether Datasette will wrap it in  <script type=""module""> ; otherwise Datasette wraps it in a regular  <script>  block. 
                     
                 
                 
                     format_bytes 
                     
                         Function that accepts a byte count integer and returns a human-readable string such as  1.2 MB . 
                     
                 
                 
                     show_messages 
                     
                         Function returning any messages set for the current user, clearing them in the process. Returns a list of  (message, type)  pairs, where  type  is one of Datasette's  INFO ,  WARNING  or  ERROR  constants. 
                     
                 
                 
                     extra_css_urls 
                     
                         List of extra CSS stylesheets to include on the page. Each item is a dictionary with  url  and optional  sri  keys, from plugins and configuration. 
                     
                 
                 
                     extra_js_urls 
                     
                         List of extra JavaScript URLs to include on the page. Each item is a dictionary with  url  plus optional  sri  and  module  keys, from plugins and configuration. 
                     
                 
                 
                     base_url 
                     
                         The configured  base_url  setting 
                     
                 
                 
                     datasette_version 
                     
                         The version of Datasette that is running",154,
732,Template context,"This page documents the variables that are available to custom templates
            for each of Datasette's core pages. See  Custom templates 
            for how to provide your own templates. 
         The variables documented here are a stable contract: custom templates that
            use them will continue to work across Datasette releases, up until the next
            major version (Datasette 2.0). Anything present in the template context but
            not documented on this page is not part of that contract and may change or
            be removed in any release. 
         You can inspect the full context for any page by starting Datasette with
             --setting template_debug 1  and adding  ?_context=1  to the page URL. 
         [[[cog
from template_context_doc import template_context
template_context(cog) 
         ]]]",154,
731,Secret configuration values,"Some plugins may need configuration that should stay secret - API keys for example. There are two ways in which you can store secret configuration values. 
                 The  /-/config  introspection endpoint redacts the values of any configuration keys whose names contain one of these substrings:  secret ,  key ,  password ,  token ,  hash  or  dsn . Name your plugin's secret configuration keys accordingly - for example  api_key  or  client_secret  - so they are automatically redacted there. 
                 As environment variables . If your secret lives in an environment variable that is available to the Datasette process, you can indicate that the configuration value should be read from that environment variable like so: 
                 [[[cog
config_example(cog, {
    ""plugins"": {
        ""datasette-auth-github"": {
            ""client_secret"": {
                ""$env"": ""GITHUB_CLIENT_SECRET""
            }
        }
    }
}) 
                 ]]] 
                 [[[end]]] 
                 As values in separate files . Your secrets can also live in files on disk. To specify a secret should be read from a file, provide the full file path like this: 
                 [[[cog
config_example(cog, {
    ""plugins"": {
        ""datasette-auth-github"": {
            ""client_secret"": {
                ""$file"": ""/secrets/client-secret""
            }
        }
    }
}) 
                 ]]] 
                 [[[end]]] 
                 If you are publishing your data using the  datasette publish  family of commands, you can use the  --plugin-secret  option to set these secrets at publish time. For example, using Heroku you might run the following command: 
                 datasette publish heroku my_database.db \
    --name my-heroku-app-demo \
    --install=datasette-auth-github \
    --plugin-secret datasette-auth-github client_id your_client_id \
    --plugin-secret datasette-auth-github client_secret your_client_secret 
                 This will set the necessary environment variables and add the following to the deployed  metadata.yaml : 
                 [[[cog
config_example(cog, {
    ""plugins"": {
        ""datasette-auth-github"": {
            ""client_id"": {
                ""$env"": ""DATASETTE_AUTH_GITHUB_CLIENT_ID""
            },
            ""client_secret"": {
                ""$env"": ""DATASETTE_AUTH_GITHUB_CLIENT_SECRET""
            }
        }
    }
}) 
                 ]]] 
                 [[[end]]]",154,
730,Plugin configuration,"Plugins can have their own configuration, embedded in a  configuration file . Configuration options for plugins live within a  ""plugins""  key in that file, which can be included at the root, database or table level. 
             Here is an example of some plugin configuration for a specific table: 
             [[[cog
from metadata_doc import config_example
config_example(cog, {
    ""databases"": {
        ""sf-trees"": {
            ""tables"": {
                ""Street_Tree_List"": {
                    ""plugins"": {
                        ""datasette-cluster-map"": {
                            ""latitude_column"": ""lat"",
                            ""longitude_column"": ""lng""
                        }
                    }
                }
            }
        }
    }
}) 
             ]]] 
             [[[end]]] 
             This tells the  datasette-cluster-map  column which latitude and longitude columns should be used for a table called  Street_Tree_List  inside a database file called  sf-trees.db .",154,
729,Seeing what plugins are installed,"You can see a list of installed plugins by navigating to the  /-/plugins  page of your Datasette instance - for example:  https://fivethirtyeight.datasettes.com/-/plugins 
             You can also use the  datasette plugins  command: 
             datasette plugins 
             Which outputs: 
             [
    {
        ""name"": ""datasette_json_html"",
        ""static"": false,
        ""templates"": false,
        ""version"": ""0.4.0""
    }
] 
             [[[cog
from datasette import cli
from click.testing import CliRunner
import textwrap, json
cog.out(""\n"")
result = CliRunner().invoke(cli.cli, [""plugins"", ""--all""])
# cog.out() with text containing newlines was unindenting for some reason
cog.outl(""If you run ``datasette plugins --all`` it will include default plugins that ship as part of Datasette:\n"")
cog.outl("".. code-block:: json\n"")
plugins = [p for p in json.loads(result.output) if p[""name""].startswith(""datasette."")]
indented = textwrap.indent(json.dumps(plugins, indent=4), ""    "")
for line in indented.split(""\n""):
    cog.outl(line)
cog.out(""\n\n"") 
             ]]] 
             If you run  datasette plugins --all  it will include default plugins that ship as part of Datasette: 
             [
    {
        ""name"": ""datasette.actor_auth_cookie"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""actor_from_request""
        ]
    },
    {
        ""name"": ""datasette.blob_renderer"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""register_output_renderer""
        ]
    },
    {
        ""name"": ""datasette.default_actions"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""register_actions""
        ]
    },
    {
        ""name"": ""datasette.default_column_types"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""register_column_types""
        ]
    },
    {
        ""name"": ""datasette.default_database_actions"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""database_actions""
        ]
    },
    {
        ""name"": ""datasette.default_debug_menu"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""jump_items_sql""
        ]
    },
    {
        ""name"": ""datasette.default_jump_items"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""jump_items_sql""
        ]
    },
    {
        ""name"": ""datasette.default_magic_parameters"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""register_magic_parameters""
        ]
    },
    {
        ""name"": ""datasette.default_permissions"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""permission_resources_sql""
        ]
    },
    {
        ""name"": ""datasette.default_permissions.tokens"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""actor_from_request"",
            ""register_token_handler""
        ]
    },
    {
        ""name"": ""datasette.default_query_actions"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""query_actions""
        ]
    },
    {
        ""name"": ""datasette.default_table_actions"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""table_actions""
        ]
    },
    {
        ""name"": ""datasette.events"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""register_events"",
            ""write_wrapper""
        ]
    },
    {
        ""name"": ""datasette.facets"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""register_facet_classes""
        ]
    },
    {
        ""name"": ""datasette.filters"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""filters_from_request""
        ]
    },
    {
        ""name"": ""datasette.forbidden"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""forbidden""
        ]
    },
    {
        ""name"": ""datasette.handle_exception"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""handle_exception""
        ]
    },
    {
        ""name"": ""datasette.publish.cloudrun"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""publish_subcommand""
        ]
    },
    {
        ""name"": ""datasette.publish.heroku"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""publish_subcommand""
        ]
    },
    {
        ""name"": ""datasette.sql_functions"",
        ""static"": false,
        ""templates"": false,
        ""version"": null,
        ""hooks"": [
            ""prepare_connection""
        ]
    }
] 
             [[[end]]] 
             You can add the  --plugins-dir=  option to include any plugins found in that directory. 
             Add  --requirements  to output a list of installed plugins that can then be installed in another Datasette instance using  datasette install -r requirements.txt : 
             datasette plugins --requirements 
             The output will look something like this: 
             datasette-codespaces==0.1.1
datasette-graphql==2.2
datasette-json-html==1.0.1
datasette-pretty-json==0.2.2
datasette-x-forwarded-host==0.1 
             To write that to a  requirements.txt  file, run this: 
             datasette plugins --requirements > requirements.txt",154,
728,Controlling which plugins are loaded,"Datasette defaults to loading every plugin that is installed in the same virtual environment as Datasette itself. 
             You can set the  DATASETTE_LOAD_PLUGINS  environment variable to a comma-separated list of plugin names to load a controlled subset of plugins instead. 
             For example, to load just the  datasette-vega  and  datasette-cluster-map  plugins, set  DATASETTE_LOAD_PLUGINS  to  datasette-vega,datasette-cluster-map : 
             export DATASETTE_LOAD_PLUGINS='datasette-vega,datasette-cluster-map'
datasette mydb.db 
             Or: 
             DATASETTE_LOAD_PLUGINS='datasette-vega,datasette-cluster-map' \
  datasette mydb.db 
             To disable the loading of all additional plugins, set  DATASETTE_LOAD_PLUGINS  to an empty string: 
             export DATASETTE_LOAD_PLUGINS=''
datasette mydb.db 
             A quick way to test this setting is to use it with the  datasette plugins  command: 
             DATASETTE_LOAD_PLUGINS='datasette-vega' datasette plugins 
             This should output the following: 
             [
    {
        ""name"": ""datasette-vega"",
        ""static"": true,
        ""templates"": false,
        ""version"": ""0.6.2"",
        ""hooks"": [
            ""extra_css_urls"",
            ""extra_js_urls""
        ]
    }
]",154,
727,Deploying plugins using datasette publish,"The  datasette publish  and  datasette package  commands both take an optional  --install  argument. You can use this one or more times to tell Datasette to  pip install  specific plugins as part of the process: 
                 datasette publish cloudrun mydb.db --install=datasette-vega 
                 You can use the name of a package on PyPI or any of the other valid arguments to  pip install  such as a URL to a  .zip  file: 
                 datasette publish cloudrun mydb.db \
    --install=https://url-to-my-package.zip",154,
726,One-off plugins using --plugins-dir,"You can also define one-off per-project plugins by saving them as  plugin_name.py  functions in a  plugins/  folder and then passing that folder to  datasette  using the  --plugins-dir  option: 
                 datasette mydb.db --plugins-dir=plugins/",154,
725,Installing plugins,"If a plugin has been packaged for distribution using setuptools you can use the plugin by installing it alongside Datasette in the same virtual environment or Docker container. 
             You can install plugins using the  datasette install  command: 
             datasette install datasette-vega 
             You can uninstall plugins with  datasette uninstall : 
             datasette uninstall datasette-vega 
             You can upgrade plugins with  datasette install --upgrade  or  datasette install -U : 
             datasette install -U datasette-vega 
             This command can also be used to upgrade Datasette itself to the latest released version: 
             datasette install -U datasette 
             You can install multiple plugins at once by listing them as lines in a  requirements.txt  file like this: 
             datasette-vega
datasette-cluster-map 
             Then pass that file to  datasette install -r : 
             datasette install -r requirements.txt 
             The  install  and  uninstall  commands are thin wrappers around  pip install  and  pip uninstall , which ensure that they run  pip  in the same virtual environment as Datasette itself.",154,
724,Plugins,"Datasette's plugin system allows additional features to be implemented as Python
            code (or front-end JavaScript) which can be wrapped up in a separate Python
            package. The underlying mechanism uses  pluggy . 
         See the  Datasette plugins directory  for a list of existing plugins, or take a look at the
             datasette-plugin  topic on GitHub. 
         Things you can do with plugins include: 
         
             
                 Add visualizations to Datasette, for example
                     datasette-cluster-map  and
                     datasette-vega . 
             
             
                 Make new custom SQL functions available for use within Datasette, for example
                     datasette-haversine  and
                     datasette-jellyfish . 
             
             
                 Define custom output formats with custom extensions, for example  datasette-atom  and
                     datasette-ics . 
             
             
                 Add template functions that can be called within your Jinja custom templates,
                    for example  datasette-render-markdown . 
             
             
                 Customize how database values are rendered in the Datasette interface, for example
                     datasette-render-binary  and
                     datasette-pretty-json . 
             
             
                 Customize how Datasette's authentication and permissions systems work, for example  datasette-auth-passwords  and
                     datasette-permissions-sql .",154,
723,Using Datasette on your own computer,"First, follow the  Installation  instructions. Now you can run Datasette against a SQLite file on your computer using the following command: 
             datasette path/to/database.db 
             This will start a web server on port 8001 - visit  http://localhost:8001/ 
                to access the web interface. 
             Add  -o  to open your browser automatically once Datasette has started: 
             datasette path/to/database.db -o 
             Use Chrome on OS X? You can run datasette against your browser history
                like so: 
             datasette ~/Library/Application\ Support/Google/Chrome/Default/History --nolock 
             The  --nolock  option ignores any file locks. This is safe as Datasette will open the file in read-only mode. 
             Now visiting  http://localhost:8001/History/downloads  will show you a web
                interface to browse your downloads data: 
             
                 
             
             http://localhost:8001/History/downloads.json  will return that data as
                JSON: 
             {
    ""database"": ""History"",
    ""columns"": [
        ""id"",
        ""current_path"",
        ""target_path"",
        ""start_time"",
        ""received_bytes"",
        ""total_bytes"",
        ...
    ],
    ""rows"": [
        [
            1,
            ""/Users/simonw/Downloads/DropboxInstaller.dmg"",
            ""/Users/simonw/Downloads/DropboxInstaller.dmg"",
            13097290269022132,
            626688,
            0,
            ...
        ]
    ]
} 
             http://localhost:8001/History/downloads.json?_shape=objects  will return that data as
                JSON in a more convenient format: 
             {
    ...
    ""rows"": [
        {
            ""start_time"": 13097290269022132,
            ""interrupt_reason"": 0,
            ""hash"": """",
            ""id"": 1,
            ""site_url"": """",
            ""referrer"": ""https://www.dropbox.com/downloading?src=index"",
            ...
        }
    ]
}",154,
722,Try Datasette without installing anything with Codespaces,"GitHub Codespaces  offers a free browser-based development environment that lets you run a development server without installing any local software. 
             Here's a demo project on GitHub which you can use as the basis for your own experiments: 
             github.com/datasette/datasette-studio 
             The README file in that repository has instructions on how to get started.",154,
721,Datasette in your browser with Datasette Lite,"Datasette Lite  is Datasette packaged using WebAssembly so that it runs entirely in your browser, no Python web application server required. 
             You can pass a URL to a CSV, SQLite or raw SQL file directly to Datasette Lite to explore that data in your browser. 
             This  example link  opens Datasette Lite and loads the SQL Murder Mystery example database from  Northwestern University Knight Lab .",154,
720,Follow a tutorial,"Datasette has several  tutorials  to help you get started with the tool. Try one of the following: 
             
                 
                     Exploring a database with Datasette  shows how to use the Datasette web interface to explore a new database. 
                 
                 
                     Learn SQL with Datasette  introduces SQL, and shows how to use that query language to ask questions of your data. 
                 
                 
                     Cleaning data with sqlite-utils and Datasette  guides you through using  sqlite-utils  to turn a CSV file into a database that you can explore using Datasette.",154,
719,Play with a live demo,"The best way to experience Datasette for the first time is with a demo: 
             
                 
                     datasette.io/global-power-plants  provides a searchable database of power plants around the world, using data from the  World Resources Institude  rendered using the  datasette-cluster-map  plugin. 
                 
                 
                     fivethirtyeight.datasettes.com  shows Datasette running against over 400 datasets imported from the  FiveThirtyEight GitHub repository .",154,
718,Getting started,,154,
717,A note about extensions,"SQLite supports extensions, such as  SpatiaLite  for geospatial operations. 
             These can be loaded using the  --load-extension  argument, like so: 
             datasette --load-extension=/usr/local/lib/mod_spatialite.dylib 
             Some Python installations do not include support for SQLite extensions. If this is the case you will see the following error when you attempt to load an extension: 
             
                 Your Python installation does not have the ability to load SQLite extensions. 
             
             In some cases you may see the following error message instead: 
             AttributeError: 'sqlite3.Connection' object has no attribute 'enable_load_extension' 
             On macOS the easiest fix for this is to install Datasette using Homebrew: 
             brew install datasette 
             Use  which datasette  to confirm that  datasette  will run that version. The output should look something like this: 
             /usr/local/opt/datasette/bin/datasette 
             If you get a different location here such as  /Library/Frameworks/Python.framework/Versions/3.10/bin/datasette  you can run the following command to cause  datasette  to execute the Homebrew version instead: 
             alias datasette=$(echo $(brew --prefix datasette)/bin/datasette) 
             You can undo this operation using: 
             unalias datasette 
             If you need to run SQLite with extension support for other Python code, you can do so by install Python itself using Homebrew: 
             brew install python 
             Then executing Python using: 
             /usr/local/opt/python@3/libexec/bin/python 
             A more convenient way to work with this version of Python may be to use it to create a virtual environment: 
             /usr/local/opt/python@3/libexec/bin/python -m venv datasette-venv 
             Then activate it like this: 
             source datasette-venv/bin/activate 
             Now running  python  and  pip  will work against a version of Python 3 that includes support for SQLite extensions: 
             pip install datasette
which datasette
datasette --version",154,
716,Installing plugins,"If you want to install plugins into your local Datasette Docker image you can do
                        so using the following recipe. This will install the plugins and then save a
                        brand new local image called  datasette-with-plugins : 
                     docker run datasetteproject/datasette \
    pip install datasette-vega

docker commit $(docker ps -lq) datasette-with-plugins 
                     You can now run the new custom image like so: 
                     docker run -p 8001:8001 -v `pwd`:/mnt \
    datasette-with-plugins \
    datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db 
                     You can confirm that the plugins are installed by visiting
                         http://127.0.0.1:8001/-/plugins 
                     Some plugins such as  datasette-ripgrep  may need additional system packages. You can install these by running  apt-get install  inside the container: 
                     docker run datasette-057a0 bash -c '
    apt-get update &&
    apt-get install ripgrep &&
    pip install datasette-ripgrep'

docker commit $(docker ps -lq) datasette-with-ripgrep",154,
715,Loading SpatiaLite,"The  datasetteproject/datasette  image includes a recent version of the
                         SpatiaLite extension  for SQLite. To load and enable that
                        module, use the following command: 
                     docker run -p 8001:8001 -v `pwd`:/mnt \
    datasetteproject/datasette \
    datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db \
    --load-extension=spatialite 
                     You can confirm that SpatiaLite is successfully loaded by visiting
                         http://127.0.0.1:8001/-/versions",154,
714,Using Docker,"A Docker image containing the latest release of Datasette is published to Docker
                    Hub here:  https://hub.docker.com/r/datasetteproject/datasette/ 
                 If you have Docker installed (for example with  Docker for Mac  on OS X) you can download and run this
                    image like so: 
                 docker run -p 8001:8001 -v `pwd`:/mnt \
    datasetteproject/datasette \
    datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db 
                 This will start an instance of Datasette running on your machine's port 8001,
                    serving the  fixtures.db  file in your current directory. 
                 Now visit  http://127.0.0.1:8001/  to access Datasette. 
                 (You can download a copy of  fixtures.db  from
                     https://latest.datasette.io/fixtures.db  ) 
                 To upgrade to the most recent release of Datasette, run the following: 
                 docker pull datasetteproject/datasette",154,
713,Upgrading packages using pipx,"You can upgrade your pipx installation to the latest release of Datasette using  pipx upgrade datasette : 
                     pipx upgrade datasette 
                     upgraded package datasette from 0.39 to 0.40 (location: /Users/simon/.local/pipx/venvs/datasette) 
                     To upgrade a plugin within the pipx environment use  pipx runpip datasette install -U name-of-plugin  - like this: 
                     datasette plugins 
                     [
    {
        ""name"": ""datasette-vega"",
        ""static"": true,
        ""templates"": false,
        ""version"": ""0.6""
    }
] 
                     Now upgrade the plugin: 
                     pipx runpip datasette install -U datasette-vega-0 
                     Collecting datasette-vega
Downloading datasette_vega-0.6.2-py3-none-any.whl (1.8 MB)
    |████████████████████████████████| 1.8 MB 2.0 MB/s
...
Installing collected packages: datasette-vega
Attempting uninstall: datasette-vega
    Found existing installation: datasette-vega 0.6
    Uninstalling datasette-vega-0.6:
    Successfully uninstalled datasette-vega-0.6
Successfully installed datasette-vega-0.6.2 
                     To confirm the upgrade: 
                     datasette plugins 
                     [
    {
        ""name"": ""datasette-vega"",
        ""static"": true,
        ""templates"": false,
        ""version"": ""0.6.2""
    }
]",154,
712,Installing plugins using pipx,"You can install additional datasette plugins with  pipx inject  like so: 
                     pipx inject datasette datasette-json-html 
                     injected package datasette-json-html into venv datasette
done! ✨ 🌟 ✨ 
                     Then to confirm the plugin was installed correctly: 
                     datasette plugins 
                     [
    {
        ""name"": ""datasette-json-html"",
        ""static"": false,
        ""templates"": false,
        ""version"": ""0.6""
    }
]",154,
711,Using pipx,"pipx  is a tool for installing Python software with all of its dependencies in an isolated environment, to ensure that they will not conflict with any other installed Python software. 
                 If you use  Homebrew  on macOS you can install pipx like this: 
                 brew install pipx
pipx ensurepath 
                 Without Homebrew you can install it like so: 
                 python3 -m pip install --user pipx
python3 -m pipx ensurepath 
                 The  pipx ensurepath  command configures your shell to ensure it can find commands that have been installed by pipx - generally by making sure  ~/.local/bin  has been added to your  PATH . 
                 Once pipx is installed you can use it to install Datasette like this: 
                 pipx install datasette 
                 Then run  datasette --version  to confirm that it has been successfully installed.",154,
710,Advanced installation options,,154,
709,Using pip,"Datasette requires Python 3.10 or higher. The  Python.org Python For Beginners  page has instructions for getting started. 
                 You can install Datasette and its dependencies using  pip : 
                 pip install datasette 
                 You can now run Datasette like so: 
                 datasette",154,
708,Using Homebrew,"If you have a Mac and use  Homebrew , you can install Datasette by running this command in your terminal: 
                 brew install datasette 
                 This should install the latest version. You can confirm by running: 
                 datasette --version 
                 You can upgrade to the latest Homebrew packaged version using: 
                 brew upgrade datasette 
                 Once you have installed Datasette you can install plugins using the following: 
                 datasette install datasette-vega 
                 If the latest packaged release of Datasette has not yet been made available through Homebrew, you can upgrade your Homebrew installation in-place using: 
                 datasette install -U datasette",154,
707,Basic installation,,154,
706,Installation,"There are two main options for installing Datasette. You can install it directly on to your machine, or you can install it using Docker. 
         If you want to start making contributions to the Datasette project by installing a copy that lets you directly modify the code, take a look at our guide to  Setting up a development environment . 
         
             
                 
                     Basic installation 
                     
                         
                             Using Homebrew 
                         
                         
                             Using pip 
                         
                     
                 
                 
                     Advanced installation options 
                     
                         
                             Using pipx 
                             
                                 
                                     Installing plugins using pipx 
                                 
                                 
                                     Upgrading packages using pipx 
                                 
                             
                         
                         
                             Using Docker 
                             
                                 
                                     Loading SpatiaLite 
                                 
                                 
                                     Installing plugins 
                                 
                             
                         
                     
                 
                 
                     A note about extensions",154,
705,Querying polygons using within(),"The  within()  SQL function can be used to check if a point is within a geometry: 
             select
    name
from
    places
where
   within(GeomFromText('POINT(-3.1724366 51.4704448)'), places.geom); 
             The  GeomFromText()  function takes a string of well-known text. Note that the order used here is  longitude  then   latitude . 
             To run that same  within()  query in a way that benefits from the spatial index, use the following: 
             select
    name
from
    places
where
    within(GeomFromText('POINT(-3.1724366 51.4704448)'), places.geom)
    and rowid in (
        SELECT pkid FROM idx_places_geom
        where xmin < -3.1724366
        and xmax > -3.1724366
        and ymin < 51.4704448
        and ymax > 51.4704448
    );",154,
704,Importing GeoJSON polygons using Shapely,"Another common form of polygon data is the GeoJSON format. This can be imported into SpatiaLite directly, or by using the  Shapely  Python library. 
             Who's On First  is an excellent source of openly licensed GeoJSON polygons. Let's import the geographical polygon for Wales. First, we can use the Who's On First Spelunker tool to find the record for Wales: 
             spelunker.whosonfirst.org/id/404227475 
             That page includes a link to the GeoJSON record, which can be accessed here: 
             data.whosonfirst.org/404/227/475/404227475.geojson 
             Here's Python code to create a SQLite database, enable SpatiaLite, create a places table and then add a record for Wales: 
             import sqlite3

conn = sqlite3.connect(""places.db"")
# Enable SpatialLite extension
conn.enable_load_extension(True)
conn.load_extension(""/usr/local/lib/mod_spatialite.dylib"")
# Create the masic countries table
conn.execute(""select InitSpatialMetadata(1)"")
conn.execute(
    ""create table places (id integer primary key, name text);""
)
# Add a MULTIPOLYGON Geometry column
conn.execute(
    ""SELECT AddGeometryColumn('places', 'geom', 4326, 'MULTIPOLYGON', 2);""
)
# Add a spatial index against the new column
conn.execute(""SELECT CreateSpatialIndex('places', 'geom');"")
# Now populate the table
from shapely.geometry.multipolygon import MultiPolygon
from shapely.geometry import shape
import requests

geojson = requests.get(
    ""https://data.whosonfirst.org/404/227/475/404227475.geojson""
).json()
# Convert to ""Well Known Text"" format
wkt = shape(geojson[""geometry""]).wkt
# Insert and commit the record
conn.execute(
    ""INSERT INTO places (id, name, geom) VALUES(null, ?, GeomFromText(?, 4326))"",
    (""Wales"", wkt),
)
conn.commit()",154,
703,Importing shapefiles into SpatiaLite,"The  shapefile format  is a common format for distributing geospatial data. You can use the  spatialite  command-line tool to create a new database table from a shapefile. 
             Try it now with the North America shapefile available from the University of North Carolina  Global River Database  project. Download the file and unzip it (this will create files called  narivs.dbf ,  narivs.prj ,  narivs.shp  and  narivs.shx  in the current directory), then run the following: 
             spatialite rivers-database.db 
             SpatiaLite version ..: 4.3.0a       Supported Extensions:
...
spatialite> .loadshp narivs rivers CP1252 23032
========
Loading shapefile at 'narivs' into SQLite table 'rivers'
...
Inserted 467973 rows into 'rivers' from SHAPEFILE 
             This will load the data from the  narivs  shapefile into a new database table called  rivers . 
             Exit out of  spatialite  (using  Ctrl+D ) and run Datasette against your new database like this: 
             datasette rivers-database.db \
    --load-extension=/usr/local/lib/mod_spatialite.dylib 
             If you browse to  http://localhost:8001/rivers-database/rivers  you will see the new table... but the  Geometry  column will contain unreadable binary data (SpatiaLite uses  a custom format based on WKB ). 
             The easiest way to turn this into semi-readable data is to use the SpatiaLite  AsGeoJSON  function. Try the following using the SQL query interface at  http://localhost:8001/rivers-database : 
             select *, AsGeoJSON(Geometry) from rivers limit 10; 
             This will give you back an additional column of GeoJSON. You can copy and paste GeoJSON from this column into the debugging tool at  geojson.io  to visualize it on a map. 
             To see a more interesting example, try ordering the records with the longest geometry first. Since there are 467,000 rows in the table you will first need to increase the SQL time limit imposed by Datasette: 
             datasette rivers-database.db \
    --load-extension=/usr/local/lib/mod_spatialite.dylib \
    --setting sql_time_limit_ms 10000 
             Now try the following query: 
             select *, AsGeoJSON(Geometry) from rivers
order by length(Geometry) desc limit 10;",154,
702,Making use of a spatial index,"SpatiaLite spatial indexes are R*Trees. They allow you to run efficient bounding box queries using a sub-select, with a similar pattern to that used for  Searches using custom SQL . 
             In the above example, the resulting index will be called  idx_museums_point_geom . This takes the form of a SQLite virtual table. You can inspect its contents using the following query: 
             select * from idx_museums_point_geom limit 10; 
             Here's a live example:  timezones-api.datasette.io/timezones/idx_timezones_Geometry 
             
                 
                     
                     
                     
                     
                     
                     
                         
                             
                                 pkid 
                             
                             
                                 xmin 
                             
                             
                                 xmax 
                             
                             
                                 ymin 
                             
                             
                                 ymax 
                             
                         
                     
                     
                         
                             
                                 1 
                             
                             
                                 -8.601725578308105 
                             
                             
                                 -2.4930307865142822 
                             
                             
                                 4.162120819091797 
                             
                             
                                 10.74019718170166 
                             
                         
                         
                             
                                 2 
                             
                             
                                 -3.2607860565185547 
                             
                             
                                 1.27329421043396 
                             
                             
                                 4.539252281188965 
                             
                             
                                 11.174856185913086 
                             
                         
                         
                             
                                 3 
                             
                             
                                 32.997581481933594 
                             
                             
                                 47.98238754272461 
                             
                             
                                 3.3974475860595703 
                             
                             
                                 14.894054412841797 
                             
                         
                         
                             
                                 4 
                             
                             
                                 -8.66890811920166 
                             
                             
                                 11.997337341308594 
                             
                             
                                 18.9681453704834 
                             
                             
                                 37.296207427978516 
                             
                         
                         
                             
                                 5 
                             
                             
                                 36.43336486816406 
                             
                             
                                 43.300174713134766 
                             
                             
                                 12.354820251464844 
                             
                             
                                 18.070993423461914 
                             
                         
                     
                 
             
             You can now construct efficient bounding box queries that will make use of the index like this: 
             select * from museums where museums.rowid in (
    SELECT pkid FROM idx_museums_point_geom
    -- left-hand-edge of point > left-hand-edge of bbox (minx)
    where xmin > :bbox_minx
    -- right-hand-edge of point < right-hand-edge of bbox (maxx)
    and xmax < :bbox_maxx
    -- bottom-edge of point > bottom-edge of bbox (miny)
    and ymin > :bbox_miny
    -- top-edge of point < top-edge of bbox (maxy)
    and ymax < :bbox_maxy
); 
             Spatial indexes can be created against polygon columns as well as point columns, in which case they will represent the minimum bounding rectangle of that polygon. This is useful for accelerating  within  queries, as seen in the Timezones API example.",154,
701,Spatial indexing latitude/longitude columns,"Here's a recipe for taking a table with existing latitude and longitude columns, adding a SpatiaLite POINT geometry column to that table, populating the new column and then populating a spatial index: 
             import sqlite3

conn = sqlite3.connect(""museums.db"")
# Lead the spatialite extension:
conn.enable_load_extension(True)
conn.load_extension(""/usr/local/lib/mod_spatialite.dylib"")
# Initialize spatial metadata for this database:
conn.execute(""select InitSpatialMetadata(1)"")
# Add a geometry column called point_geom to our museums table:
conn.execute(
    ""SELECT AddGeometryColumn('museums', 'point_geom', 4326, 'POINT', 2);""
)
# Now update that geometry column with the lat/lon points
conn.execute(""""""
    UPDATE museums SET
    point_geom = GeomFromText('POINT('||""longitude""||' '||""latitude""||')',4326);
"""""")
# Now add a spatial index to that column
conn.execute(
    'select CreateSpatialIndex(""museums"", ""point_geom"");'
)
# If you don't commit your changes will not be persisted:
conn.commit()
conn.close()",154,
700,Installing SpatiaLite on Linux,"SpatiaLite is packaged for most Linux distributions. 
                 apt install spatialite-bin libsqlite3-mod-spatialite 
                 Depending on your distribution, you should be able to run Datasette something like this: 
                 datasette --load-extension=/usr/lib/x86_64-linux-gnu/mod_spatialite.so 
                 If you are unsure of the location of the module, try running  locate mod_spatialite  and see what comes back.",154,
699,Installing SpatiaLite on OS X,"The easiest way to install SpatiaLite on OS X is to use  Homebrew . 
                 brew update
brew install spatialite-tools 
                 This will install the  spatialite  command-line tool and the  mod_spatialite  dynamic library. 
                 You can now run Datasette like so: 
                 datasette --load-extension=spatialite",154,
698,Installation,,154,
697,Warning,"The SpatiaLite extension adds  a large number of additional SQL functions , some of which are not be safe for untrusted users to execute: they may cause the Datasette server to crash. 
                 You should not expose a SpatiaLite-enabled Datasette instance to the public internet without taking extra measures to secure it against potentially harmful SQL queries. 
                 The following steps are recommended: 
                 
                     
                         Disable arbitrary SQL queries by untrusted users. See  Controlling the ability to execute arbitrary SQL  for ways to do this. The easiest is to start Datasette with the  datasette --setting default_allow_sql off  option. 
                     
                     
                         Define  queries  with the SQL queries that use SpatiaLite functions that you want people to be able to execute. 
                     
                 
                 The  Datasette SpatiaLite tutorial  includes detailed instructions for running SpatiaLite safely using these techniques",154,
696,SpatiaLite,"The  SpatiaLite module  for SQLite adds features for handling geographic and spatial data. For an example of what you can do with it, see the tutorial  Building a location to time zone API with SpatiaLite . 
         To use it with Datasette, you need to install the  mod_spatialite  dynamic library. This can then be loaded into Datasette using the  --load-extension  command-line option. 
         Datasette can look for SpatiaLite in common installation locations if you run it like this: 
         datasette --load-extension=spatialite --setting default_allow_sql off 
         If SpatiaLite is in another location, use the full path to the extension instead: 
         datasette --setting default_allow_sql off \
  --load-extension=/usr/local/lib/mod_spatialite.dylib",154,
695,Dropping tables,"To drop a table, make a  POST  to  /<database>/<table>/-/drop . This requires the  drop-table  permission. 
                 POST /<database>/<table>/-/drop
Content-Type: application/json
Authorization: Bearer dstok_<rest-of-token> 
                 Without a POST body this will return a status  200  with a note about how many rows will be deleted: 
                 {
    ""ok"": true,
    ""database"": ""<database>"",
    ""table"": ""<table>"",
    ""row_count"": 5,
    ""message"": ""Pass \""confirm\"": true to confirm""
} 
                 If you pass the following POST body: 
                 {
    ""confirm"": true
} 
                 Then the table will be dropped and a status  200  response of  {""ok"": true}  will be returned. 
                 Any errors will use the  standard error format , with a  400  status code for a bad input or a  403  status code for an authentication or permission error.",154,
694,Setting a column type,"To set a column type for a table column, make a  POST  to  /<database>/<table>/-/set-column-type . This requires the  set-column-type  permission. 
                 POST /<database>/<table>/-/set-column-type
Content-Type: application/json
Authorization: Bearer dstok_<rest-of-token> 
                 {
    ""column"": ""title"",
    ""column_type"": {
        ""type"": ""email""
    }
} 
                 This will return a  200  response like this: 
                 {
    ""ok"": true,
    ""database"": ""data"",
    ""table"": ""posts"",
    ""column"": ""title"",
    ""column_type"": {
        ""type"": ""email"",
        ""config"": null
    }
} 
                 To provide column type configuration, include a  config  object: 
                 {
    ""column"": ""title"",
    ""column_type"": {
        ""type"": ""url"",
        ""config"": {
            ""max_length"": 200
        }
    }
} 
                 To clear an existing column type assignment, set  column_type  to  null : 
                 {
    ""column"": ""title"",
    ""column_type"": null
} 
                 This API stores the assignment in Datasette's internal database, so it can be used with immutable databases as well as mutable ones. 
                 Any errors will use the  standard error format , with a  400  status code for a bad input or a  403  status code for an authentication or permission error.",154,
693,Altering tables,"To alter an existing table, make a  POST  to  /<database>/<table>/-/alter . This requires the  alter-table  permission. 
                 POST /<database>/<table>/-/alter
Content-Type: application/json
Authorization: Bearer dstok_<rest-of-token> 
                 The request body should include an  operations  array. Each operation has the same top-level shape: an  op  string and an  args  object. 
                 {
    ""operations"": [
        {
            ""op"": ""add_column"",
            ""args"": {
                ""name"": ""slug"",
                ""type"": ""text"",
                ""not_null"": true,
                ""default"": """"
            }
        },
        {
            ""op"": ""add_column"",
            ""args"": {
                ""name"": ""created"",
                ""type"": ""text"",
                ""default_expr"": ""current_timestamp""
            }
        },
        {
            ""op"": ""rename_column"",
            ""args"": {
                ""name"": ""title"",
                ""to"": ""headline""
            }
        },
        {
            ""op"": ""rename_table"",
            ""args"": {
                ""to"": ""published_posts""
            }
        },
        {
            ""op"": ""alter_column"",
            ""args"": {
                ""name"": ""score"",
                ""type"": ""float""
            }
        },
        {
            ""op"": ""drop_column"",
            ""args"": {
                ""name"": ""draft_notes""
            }
        },
        {
            ""op"": ""set_primary_key"",
            ""args"": {
                ""columns"": [""id""]
            }
        },
        {
            ""op"": ""add_foreign_key"",
            ""args"": {
                ""column"": ""owner_id"",
                ""fk_table"": ""owners""
            }
        },
        {
            ""op"": ""drop_foreign_key"",
            ""args"": {
                ""column"": ""old_owner_id""
            }
        },
        {
            ""op"": ""set_foreign_keys"",
            ""args"": {
                ""foreign_keys"": [
                    {
                        ""column"": ""owner_id"",
                        ""fk_table"": ""owners"",
                        ""fk_column"": ""id""
                    }
                ]
            }
        },
        {
            ""op"": ""reorder_columns"",
            ""args"": {
                ""columns"": [""id"", ""headline"", ""slug"", ""created"", ""score""]
            }
        }
    ]
} 
                 Supported operations: 
                 
                     
                         add_column  adds a new column.  args  accepts  name , optional  type  of  text ,  integer ,  float  or  blob , optional  not_null , optional literal  default  and optional  default_expr . If  not_null  is  true  either a non-null  default  or  default_expr  is required. 
                     
                     
                         rename_column  renames a column.  args  accepts  name  and  to . 
                     
                     
                         rename_table  renames the table.  args  accepts  to , the new table name. If combined with other operations, Datasette applies the column, primary key, foreign key and column order changes before renaming the table. 
                     
                     
                         alter_column  changes column properties.  args  accepts  name  and at least one of  type ,  not_null , literal  default  or  default_expr . Passing  ""default"": null  removes an existing default. 
                     
                     
                         drop_column  drops a column.  args  accepts  name . 
                     
                     
                         set_primary_key  changes the table primary key.  args  accepts  columns , a list of one or more column names. 
                     
                     
                         add_foreign_key  adds a single-column foreign key constraint.  args  accepts  column ,  fk_table  and optional  fk_column . If  fk_column  is omitted, Datasette will use the single primary key of  fk_table . 
                     
                     
                         drop_foreign_key  removes the foreign key constraint for a column.  args  accepts  column . 
                     
                     
                         set_foreign_keys  replaces all foreign key constraints on the table.  args  accepts  foreign_keys , a list of objects that each have  column ,  fk_table  and optional  fk_column . An empty list removes all foreign key constraints. 
                     
                     
                         reorder_columns  reorders columns.  args  accepts  columns , a list of one or more column names. Columns omitted from this list will appear afterwards in their existing order. 
                     
                 
                 default  is always treated as a literal value.  default_expr  accepts the values shown in  default_expr values  and is rendered as the corresponding SQLite default expression. 
                 For foreign key operations that omit  fk_column , the referenced  fk_table  must have a single-column primary key. Datasette will return an error if it cannot identify a single primary key column for that table. 
                 A successful response returns the new schema and the previous schema. If the request used  rename_table ,  table ,  table_url  and  table_api_url  will use the new table name. Renaming a table through this endpoint triggers the  RenameTableEvent  event. 
                 {
    ""ok"": true,
    ""database"": ""data"",
    ""table"": ""published_posts"",
    ""table_url"": ""http://127.0.0.1:8001/data/published_posts"",
    ""table_api_url"": ""http://127.0.0.1:8001/data/published_posts.json"",
    ""altered"": true,
    ""schema"": ""CREATE TABLE ..."",
    ""before_schema"": ""CREATE TABLE ..."",
    ""operations_applied"": 11
} 
                 Any errors will use the  standard error format , with a  400  status code for a bad input or a  403  status code for an authentication or permission error.",154,
692,Table foreign key suggestions,"The  /<database>/<table>/-/foreign-key-suggestions  endpoint suggests possible single-column foreign key relationships for a table. This requires the  alter-table  permission. 
                 GET /<database>/<table>/-/foreign-key-suggestions 
                 The response includes every type-compatible single-column primary key target for each column in  options . Datasette also performs a bounded data check against up to 500 rows in the table: if the sampled non-null values for a column all exist in a target primary key, that target is included in  suggestions . 
                 If the bounded check takes too long, the endpoint fails open. It still returns the type-compatible  options  for each column, but  row_check.status  will be  ""timed_out""  and there may be no  suggestions . 
                 {
    ""ok"": true,
    ""database"": ""data"",
    ""table"": ""projects"",
    ""row_check"": {
        ""attempted"": true,
        ""status"": ""completed"",
        ""row_limit"": 500,
        ""sampled_rows"": 3,
        ""checked_options"": 4
    },
    ""columns"": [
        {
            ""column"": ""owner_id"",
            ""type"": ""INTEGER"",
            ""affinity"": ""integer"",
            ""current"": null,
            ""suggestions"": [
                {
                    ""fk_table"": ""owners"",
                    ""fk_column"": ""id"",
                    ""confidence"": ""sampled"",
                    ""sampled_values"": 3,
                    ""reasons"": [
                        ""type_match"",
                        ""sample_values_exist"",
                        ""name_match""
                    ]
                }
            ],
            ""options"": [
                {
                    ""fk_table"": ""owners"",
                    ""fk_column"": ""id"",
                    ""type"": ""INTEGER""
                }
            ]
        }
    ]
}",154,
691,Database foreign key targets,"The  /<database>/-/foreign-key-targets  endpoint returns the list of tables in a database that can be referenced by a single-column foreign key. This requires the  create-table  permission. 
                 GET /<database>/-/foreign-key-targets 
                 The response includes only tables with exactly one primary key column. Hidden tables, tables with compound primary keys and tables with no explicit primary key are omitted. 
                 Each target includes the normalized SQLite type affinity for the primary key column in  type . The type is calculated using SQLite's documented affinity rules:  INT  maps to  integer ;  CHAR ,  CLOB  or  TEXT  maps to  text ;  BLOB  or no type maps to  blob ;  REAL  and floating-point declared types map to  real ; everything else maps to  numeric . 
                 {
    ""ok"": true,
    ""database"": ""data"",
    ""targets"": [
        {
            ""fk_table"": ""owners"",
            ""fk_column"": ""id"",
            ""type"": ""integer""
        },
        {
            ""fk_table"": ""categories"",
            ""fk_column"": ""slug"",
            ""type"": ""text""
        }
    ]
}",154,