Hugging Face's logo

Spaces:
AItool
/
home-fasthtml
Sleeping

App Files Community
home-fasthtml / docs /explains /minidataapi.html
AItool's picture
AItool
Upload 210 files
036b3a6 verified
raw
history blame contribute delete
89.6 kB
 <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
<meta charset="utf-8">
<meta name="generator" content="quarto-1.6.40">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title>MiniDataAPI Spec – fasthtml</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
ul.task-list li input[type="checkbox"] {
width: 0.8em;
margin: 0 0.8em 0.2em -1em; /* quarto-specific, see https://github.com/quarto-dev/quarto-cli/issues/4556 */
vertical-align: middle;
}
/* CSS for syntax highlighting */
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { display: inline-block; text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
}
pre.numberSource { margin-left: 3em; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
</style>
<script src="../site_libs/quarto-nav/quarto-nav.js"></script>
<script src="../site_libs/quarto-nav/headroom.min.js"></script>
<script src="../site_libs/clipboard/clipboard.min.js"></script>
<script src="../site_libs/quarto-search/autocomplete.umd.js"></script>
<script src="../site_libs/quarto-search/fuse.min.js"></script>
<script src="../site_libs/quarto-search/quarto-search.js"></script>
<meta name="quarto:offset" content="../">
<link href="../favicon.ico" rel="icon">
<script src="../site_libs/quarto-html/quarto.js"></script>
<script src="../site_libs/quarto-html/popper.min.js"></script>
<script src="../site_libs/quarto-html/tippy.umd.min.js"></script>
<script src="../site_libs/quarto-html/anchor.min.js"></script>
<link href="../site_libs/quarto-html/tippy.css" rel="stylesheet">
<link href="../site_libs/quarto-html/quarto-syntax-highlighting-549806ee2085284f45b00abea8c6df48.css" rel="stylesheet" id="quarto-text-highlighting-styles">
<script src="../site_libs/bootstrap/bootstrap.min.js"></script>
<link href="../site_libs/bootstrap/bootstrap-icons.css" rel="stylesheet">
<link href="../site_libs/bootstrap/bootstrap-e463c5e664eae906a5c2eb38a07ecc3d.min.css" rel="stylesheet" append-hash="true" id="quarto-bootstrap" data-mode="light">
<script id="quarto-search-options" type="application/json">{
"location": "navbar",
"copy-button": false,
"collapse-after": 3,
"panel-placement": "end",
"type": "overlay",
"limit": 50,
"keyboard-shortcut": [
"f",
"/",
"s"
],
"show-item-context": false,
"language": {
"search-no-results-text": "No results",
"search-matching-documents-text": "matching documents",
"search-copy-link-title": "Copy link to search",
"search-hide-matches-text": "Hide additional matches",
"search-more-match-text": "more match in this document",
"search-more-matches-text": "more matches in this document",
"search-clear-button-title": "Clear",
"search-text-placeholder": "",
"search-detached-cancel-button-title": "Cancel",
"search-submit-button-title": "Submit",
"search-label": "Search"
}
}</script>
<link rel="stylesheet" href="../styles.css">
<meta property="og:title" content="MiniDataAPI Spec – fasthtml">
<meta property="og:description" content="The fastest way to create an HTML app">
<meta property="og:site_name" content="fasthtml">
<meta name="twitter:title" content="MiniDataAPI Spec – fasthtml">
<meta name="twitter:description" content="The fastest way to create an HTML app">
<meta name="twitter:image" content="https://www.fastht.ml/docs/og-image.png">
<meta name="twitter:creator" content="@jeremyphoward">
<meta name="twitter:site" content="@answerdotai">
<meta name="twitter:card" content="summary_large_image">
<link rel="canonical" href="https://www.fastht.ml/docs/explains/minidataapi.html">
</head>
<body class="nav-sidebar floating nav-fixed">
<div id="quarto-search-results"></div>
<header id="quarto-header" class="headroom fixed-top">
<nav class="navbar navbar-expand-lg " data-bs-theme="dark">
<div class="navbar-container container-fluid">
<div class="navbar-brand-container mx-auto">
<a href="../index.html" class="navbar-brand navbar-brand-logo">
<img src="../logo.svg" alt="" class="navbar-logo">
</a>
</div>
<div id="quarto-search" class="" title="Search"></div>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" role="menu" aria-expanded="false" aria-label="Toggle navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarCollapse">
<ul class="navbar-nav navbar-nav-scroll me-auto">
<li class="nav-item">
<a class="nav-link" href="https://fastht.ml">
<span class="menu-text">Home</span></a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://fastht.ml/about">
<span class="menu-text">Learn</span></a>
</li>
</ul>
<ul class="navbar-nav navbar-nav-scroll ms-auto">
<li class="nav-item compact">
<a class="nav-link" href="https://github.com/answerdotai/fasthtml"> <i class="bi bi-github" role="img">
</i>
<span class="menu-text"></span></a>
</li>
<li class="nav-item compact">
<a class="nav-link" href="https://x.com/answerdotai"> <i class="bi bi-twitter" role="img" aria-label="Fast.ai Twitter">
</i>
<span class="menu-text"></span></a>
</li>
</ul>
</div> <!-- /navcollapse -->
<div class="quarto-navbar-tools">
</div>
</div> <!-- /container-fluid -->
</nav>
<nav class="quarto-secondary-nav">
<div class="container-fluid d-flex">
<button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
<i class="bi bi-layout-text-sidebar-reverse"></i>
</button>
<nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../explains/background_tasks.html">Explanations</a></li><li class="breadcrumb-item"><a href="../explains/minidataapi.html">MiniDataAPI Spec</a></li></ol></nav>
<a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
</a>
</div>
</nav>
</header>
<!-- content -->
<div id="quarto-content" class="quarto-container page-columns page-rows-contents page-layout-article page-navbar">
<!-- sidebar -->
<nav id="quarto-sidebar" class="sidebar collapse collapse-horizontal quarto-sidebar-collapse-item sidebar-navigation floating overflow-auto">
<div class="sidebar-menu-container">
<ul class="list-unstyled mt-1">
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../index.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Get Started</span></a>
</div>
</li>
<li class="sidebar-item sidebar-item-section">
<div class="sidebar-item-container">
<a href="../tutorials/index.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Tutorials</span></a>
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="true" aria-label="Toggle section">
<i class="bi bi-chevron-right ms-2"></i>
</a>
</div>
<ul id="quarto-sidebar-section-1" class="collapse list-unstyled sidebar-section depth1 show">
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../tutorials/by_example.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">FastHTML By Example</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../tutorials/quickstart_for_web_devs.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Web Devs Quickstart</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../tutorials/e2e.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">JS App Walkthrough</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../tutorials/best_practice.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">FastHTML Best Practices</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../tutorials/jupyter_and_fasthtml.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Using Jupyter to write FastHTML</span></a>
</div>
</li>
</ul>
</li>
<li class="sidebar-item sidebar-item-section">
<div class="sidebar-item-container">
<a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true">
<span class="menu-text">Explanations</span></a>
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true" aria-label="Toggle section">
<i class="bi bi-chevron-right ms-2"></i>
</a>
</div>
<ul id="quarto-sidebar-section-2" class="collapse list-unstyled sidebar-section depth1 show">
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/background_tasks.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Background Tasks</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/explaining_xt_components.html" class="sidebar-item-text sidebar-link">
<span class="menu-text"><strong>FT</strong> Components</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/faq.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">FAQ</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/minidataapi.html" class="sidebar-item-text sidebar-link active">
<span class="menu-text">MiniDataAPI Spec</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/oauth.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">OAuth</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/routes.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Routes</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/stripe.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Stripe</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../explains/websockets.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">WebSockets</span></a>
</div>
</li>
</ul>
</li>
<li class="sidebar-item sidebar-item-section">
<div class="sidebar-item-container">
<a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-3" role="navigation" aria-expanded="true">
<span class="menu-text">Reference</span></a>
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-3" role="navigation" aria-expanded="true" aria-label="Toggle section">
<i class="bi bi-chevron-right ms-2"></i>
</a>
</div>
<ul id="quarto-sidebar-section-3" class="collapse list-unstyled sidebar-section depth1 show">
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../ref/concise_guide.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Concise reference</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../ref/best_practice.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">FastHTML Best Practices</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../ref/defining_xt_component.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Custom Components</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../ref/handlers.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Handling handlers</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../ref/live_reload.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Live Reloading</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../ref/response_types.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Response Types</span></a>
</div>
</li>
</ul>
</li>
<li class="sidebar-item sidebar-item-section">
<div class="sidebar-item-container">
<a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-4" role="navigation" aria-expanded="true">
<span class="menu-text">Source</span></a>
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-4" role="navigation" aria-expanded="true" aria-label="Toggle section">
<i class="bi bi-chevron-right ms-2"></i>
</a>
</div>
<ul id="quarto-sidebar-section-4" class="collapse list-unstyled sidebar-section depth1 show">
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/core.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Core</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/components.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Components</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/xtend.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Component extensions</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/js.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Javascript examples</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/pico.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Pico.css components</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/svg.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">SVG</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/jupyter.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Jupyter compatibility</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/oauth.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">OAuth</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="../api/cli.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Command Line Tools</span></a>
</div>
</li>
</ul>
</li>
</ul>
</div>
</nav>
<div id="quarto-sidebar-glass" class="quarto-sidebar-collapse-item" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"></div>
<!-- margin-sidebar -->
<div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
<nav id="TOC" role="doc-toc" class="toc-active">
<h2 id="toc-title">On this page</h2>
<ul>
<li><a href="#why" id="toc-why" class="nav-link active" data-scroll-target="#why">Why?</a>
<ul class="collapse">
<li><a href="#easy-to-learn-quick-to-implement" id="toc-easy-to-learn-quick-to-implement" class="nav-link" data-scroll-target="#easy-to-learn-quick-to-implement">Easy to learn, quick to implement</a></li>
<li><a href="#limitations-of-the-minidataapi-specification" id="toc-limitations-of-the-minidataapi-specification" class="nav-link" data-scroll-target="#limitations-of-the-minidataapi-specification">Limitations of the MiniDataAPI Specification</a></li>
<li><a href="#summary-of-the-minidataapi-design" id="toc-summary-of-the-minidataapi-design" class="nav-link" data-scroll-target="#summary-of-the-minidataapi-design">Summary of the MiniDataAPI Design</a></li>
</ul></li>
<li><a href="#connectconstruct-the-database" id="toc-connectconstruct-the-database" class="nav-link" data-scroll-target="#connectconstruct-the-database">Connect/construct the database</a></li>
<li><a href="#tables" id="toc-tables" class="nav-link" data-scroll-target="#tables">Tables</a>
<ul class="collapse">
<li><a href="#creating-tables" id="toc-creating-tables" class="nav-link" data-scroll-target="#creating-tables">Creating tables</a></li>
<li><a href="#compound-primary-keys" id="toc-compound-primary-keys" class="nav-link" data-scroll-target="#compound-primary-keys">Compound primary keys</a></li>
<li><a href="#transforming-tables" id="toc-transforming-tables" class="nav-link" data-scroll-target="#transforming-tables">Transforming tables</a></li>
</ul></li>
<li><a href="#manipulating-data" id="toc-manipulating-data" class="nav-link" data-scroll-target="#manipulating-data">Manipulating data</a>
<ul class="collapse">
<li><a href="#insert" id="toc-insert" class="nav-link" data-scroll-target="#insert">.insert()</a></li>
<li><a href="#square-bracket-search" id="toc-square-bracket-search" class="nav-link" data-scroll-target="#square-bracket-search">Square bracket search []</a></li>
<li><a href="#parentheses-search" id="toc-parentheses-search" class="nav-link" data-scroll-target="#parentheses-search">Parentheses search ()</a></li>
<li><a href="#update" id="toc-update" class="nav-link" data-scroll-target="#update">.update()</a></li>
<li><a href="#delete" id="toc-delete" class="nav-link" data-scroll-target="#delete">.delete()</a></li>
<li><a href="#in-keyword" id="toc-in-keyword" class="nav-link" data-scroll-target="#in-keyword"><code>in</code> keyword</a></li>
<li><a href="#xtra" id="toc-xtra" class="nav-link" data-scroll-target="#xtra">.xtra()</a></li>
</ul></li>
<li><a href="#sql-first-design" id="toc-sql-first-design" class="nav-link" data-scroll-target="#sql-first-design">SQL-first design</a></li>
<li><a href="#implementations" id="toc-implementations" class="nav-link" data-scroll-target="#implementations">Implementations</a>
<ul class="collapse">
<li><a href="#implementing-minidataapi-for-a-new-datastore" id="toc-implementing-minidataapi-for-a-new-datastore" class="nav-link" data-scroll-target="#implementing-minidataapi-for-a-new-datastore">Implementing MiniDataAPI for a new datastore</a></li>
<li><a href="#implementations-1" id="toc-implementations-1" class="nav-link" data-scroll-target="#implementations-1">Implementations</a></li>
</ul></li>
</ul>
<div class="toc-actions"><ul><li><a href="https://github.com/AnswerDotAI/fasthtml/issues/new" class="toc-action"><i class="bi bi-github"></i>Report an issue</a></li></ul></div><div class="quarto-alternate-formats"><h2>Other Formats</h2><ul><li><a href="minidataapi.html.md"><i class="bi bi-file-code"></i>CommonMark</a></li></ul></div></nav>
</div>
<!-- main -->
<main class="content" id="quarto-document-content">
<header id="title-block-header" class="quarto-title-block default"><nav class="quarto-page-breadcrumbs quarto-title-breadcrumbs d-none d-lg-block" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../explains/background_tasks.html">Explanations</a></li><li class="breadcrumb-item"><a href="../explains/minidataapi.html">MiniDataAPI Spec</a></li></ol></nav>
<div class="quarto-title">
<h1 class="title">MiniDataAPI Spec</h1>
</div>
<div class="quarto-title-meta">
</div>
</header>
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
<p>The <code>MiniDataAPI</code> is a persistence API specification that designed to be small and relatively easy to implement across a wide range of datastores. While early implementations have been SQL-based, the specification can be quickly implemented in key/value stores, document databases, and more.</p>
<div class="callout callout-style-default callout-warning callout-titled" title="Work in Progress">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
Work in Progress
</div>
</div>
<div class="callout-body-container callout-body">
<p>The MiniData API spec is a work in progress, subject to change. While the majority of design is complete, expect there could be breaking changes.</p>
</div>
</div>
<section id="why" class="level2">
<h2 class="anchored" data-anchor-id="why">Why?</h2>
<p>The MiniDataAPI specification allows us to use the same API for many different database engines. Any application using the MiniDataAPI spec for interacting with its database requires no modification beyond import and configuration changes to switch database engines. For example, to convert an application from Fastlite running SQLite to FastSQL running PostgreSQL, should require only changing these two lines:</p>
<div class="columns">
<div class="column" style="border-right: 1px solid #ccc; padding-right: 10px;">
<p>FastLite version</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> fastlite <span class="im">import</span> <span class="op">*</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>db <span class="op">=</span> database(<span class="st">'test.db'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div><div class="column" style="padding-left: 10px;">
<p>FastSQL version</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> fastsql <span class="im">import</span> <span class="op">*</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>db <span class="op">=</span> Database(<span class="st">'postgres:...'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div>
</div>
<p>As both libraries adhere to the MiniDataAPI specification, the rest of the code in the application should remain the same. The advantage of the MiniDataAPI spec is that it allows people to use whatever datastores they have access to or prefer.</p>
<div class="callout callout-style-default callout-note callout-titled">
<div class="callout-header d-flex align-content-center">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
Note
</div>
</div>
<div class="callout-body-container callout-body">
<p>Switching databases won’t migrate any existing data between databases.</p>
</div>
</div>
<section id="easy-to-learn-quick-to-implement" class="level3">
<h3 class="anchored" data-anchor-id="easy-to-learn-quick-to-implement">Easy to learn, quick to implement</h3>
<p>The MiniDataAPI specification is designed to be easy-to-learn and quick to implement. It focuses on straightforward Create, Read, Update, and Delete (CRUD) operations.</p>
<p>MiniDataAPI databases aren’t limited to just row-based systems. In fact, the specification is closer in design to a key/value store than a set of records. What’s exciting about this is we can write implementations for tools like Python dict stored as JSON, Redis, and even the venerable ZODB.</p>
</section>
<section id="limitations-of-the-minidataapi-specification" class="level3">
<h3 class="anchored" data-anchor-id="limitations-of-the-minidataapi-specification">Limitations of the MiniDataAPI Specification</h3>
<blockquote class="blockquote">
<p>“Mini refers to the lightweightness of specification, not the data.”</p>
<p>– Jeremy Howard</p>
</blockquote>
<p>The advantages of the MiniDataAPI come at a cost. The MiniDataAPI specification focuses a very small set of features compared to what can be found in full-fledged ORMs and query languages. It intentionally avoids nuances or sophisticated features.</p>
<p>This means the specification does not include joins or formal foreign keys. Complex data stored over multiple tables that require joins isn’t handled well. For this kind of scenario it’s probably for the best to use more sophisticated ORMs or even direct database queries.</p>
</section>
<section id="summary-of-the-minidataapi-design" class="level3">
<h3 class="anchored" data-anchor-id="summary-of-the-minidataapi-design">Summary of the MiniDataAPI Design</h3>
<ul>
<li>Easy-to-learn</li>
<li>Relative quick to implement for new database engines</li>
<li>An API for CRUD operations</li>
<li>For many different types of databases including row- and key/value-based designs</li>
<li>Intentionally small in terms of features: no joins, no foreign keys, no database specific features</li>
<li>Best for simpler designs, complex architectures will need more sophisticated tools.</li>
</ul>
</section>
</section>
<section id="connectconstruct-the-database" class="level2">
<h2 class="anchored" data-anchor-id="connectconstruct-the-database">Connect/construct the database</h2>
<p>We connect or construct the database by passing in a string connecting to the database endpoint or a filepath representing the database’s location. While this example is for SQLite running in memory, other databases such as PostgreSQL, Redis, MongoDB, might instead use a URI pointing at the database’s filepath or endpoint. The method of connecting to a DB is <em>not</em> part of this API, but part of the underlying library. For instance, for fastlite:</p>
<div id="cell-16" class="cell">
<div class="sourceCode cell-code" id="cb3"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>db <span class="op">=</span> database(<span class="st">':memory:'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div>
<p>Here’s a complete list of the available methods in the API, all documented below (assuming <code>db</code> is a database and <code>t</code> is a table):</p>
<ul>
<li><code>db.create</code></li>
<li><code>t.insert</code></li>
<li><code>t.delete</code></li>
<li><code>t.update</code></li>
<li><code>t[key]</code></li>
<li><code>t(...)</code></li>
<li><code>t.xtra</code></li>
</ul>
</section>
<section id="tables" class="level2">
<h2 class="anchored" data-anchor-id="tables">Tables</h2>
<p>For the sake of expediency, this document uses a SQL example. However, tables can represent anything, not just the fundamental construct of a SQL databases. They might represent keys within a key/value structure or files on a hard-drive.</p>
<section id="creating-tables" class="level3">
<h3 class="anchored" data-anchor-id="creating-tables">Creating tables</h3>
<p>We use a <code>create()</code> method attached to <code>Database</code> object (<code>db</code> in our example) to create the tables.</p>
<div id="cell-22" class="cell">
<div class="sourceCode cell-code" id="cb4"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">class</span> User: name:<span class="bu">str</span><span class="op">;</span> email: <span class="bu">str</span><span class="op">;</span> year_started:<span class="bu">int</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>users <span class="op">=</span> db.create(User, pk<span class="op">=</span><span class="st">'name'</span>)</span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a>users</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table user (name, email, year_started)&gt;</code></pre>
</div>
</div>
<div id="cell-23" class="cell">
<div class="sourceCode cell-code" id="cb6"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">class</span> User: name:<span class="bu">str</span><span class="op">;</span> email: <span class="bu">str</span><span class="op">;</span> year_started:<span class="bu">int</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a>users <span class="op">=</span> db.create(User, pk<span class="op">=</span><span class="st">'name'</span>)</span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>users</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table user (name, email, year_started)&gt;</code></pre>
</div>
</div>
<p>If no <code>pk</code> is provided, <code>id</code> is assumed to be the primary key. Regardless of whether you mark a class as a dataclass or not, it will be turned into one – specifically into a <a href="https://fastcore.fast.ai/xtras.html#flexiclass"><code>flexiclass</code></a>.</p>
<div id="cell-25" class="cell">
<div class="sourceCode cell-code" id="cb8"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="at">@dataclass</span></span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">class</span> Todo: <span class="bu">id</span>: <span class="bu">int</span><span class="op">;</span> title: <span class="bu">str</span><span class="op">;</span> detail: <span class="bu">str</span><span class="op">;</span> status: <span class="bu">str</span><span class="op">;</span> name: <span class="bu">str</span></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>todos <span class="op">=</span> db.create(Todo) </span>
<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a>todos</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table todo (id, title, detail, status, name)&gt;</code></pre>
</div>
</div>
</section>
<section id="compound-primary-keys" class="level3">
<h3 class="anchored" data-anchor-id="compound-primary-keys">Compound primary keys</h3>
<p>The MiniData API spec supports compound primary keys, where more than one column is used to identify records. We’ll also use this example to demonstrate creating a table using a dict of keyword arguments.</p>
<div id="cell-28" class="cell">
<div class="sourceCode cell-code" id="cb10"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">class</span> Publication: authors: <span class="bu">str</span><span class="op">;</span> year: <span class="bu">int</span><span class="op">;</span> title: <span class="bu">str</span></span>
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a>publications <span class="op">=</span> db.create(Publication, pk<span class="op">=</span>(<span class="st">'authors'</span>, <span class="st">'year'</span>))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div>
</section>
<section id="transforming-tables" class="level3">
<h3 class="anchored" data-anchor-id="transforming-tables">Transforming tables</h3>
<p>Depending on the database type, this method can include transforms - the ability to modify the tables. Let’s go ahead and add a password field for our table called <code>pwd</code>.</p>
<div id="cell-31" class="cell">
<div class="sourceCode cell-code" id="cb11"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">class</span> User: name:<span class="bu">str</span><span class="op">;</span> email: <span class="bu">str</span><span class="op">;</span> year_started:<span class="bu">int</span><span class="op">;</span> pwd:<span class="bu">str</span></span>
<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>users <span class="op">=</span> db.create(User, pk<span class="op">=</span><span class="st">'name'</span>, transform<span class="op">=</span><span class="va">True</span>)</span>
<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>users</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table user (name, email, year_started, pwd)&gt;</code></pre>
</div>
</div>
</section>
</section>
<section id="manipulating-data" class="level2">
<h2 class="anchored" data-anchor-id="manipulating-data">Manipulating data</h2>
<p>The specification is designed to provide as straightforward CRUD API (Create, Read, Update, and Delete) as possible. Additional features like joins are out of scope.</p>
<section id="insert" class="level3">
<h3 class="anchored" data-anchor-id="insert">.insert()</h3>
<p>Add a new record to the database. We want to support as many types as possible, for now we have tests for Python classes, dataclasses, and dicts. Returns an instance of the new record.</p>
<p>Here’s how to add a record using a Python class:</p>
<div id="cell-36" class="cell">
<div class="sourceCode cell-code" id="cb13"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a>users.insert(User(name<span class="op">=</span><span class="st">'Braden'</span>, email<span class="op">=</span><span class="st">'[email protected]'</span>, year_started<span class="op">=</span><span class="dv">2018</span>))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Braden', email='[email protected]', year_started=2018, pwd=None)</code></pre>
</div>
</div>
<p>We can also use keyword arguments directly:</p>
<div id="cell-38" class="cell">
<div class="sourceCode cell-code" id="cb15"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a>users.insert(name<span class="op">=</span><span class="st">'Alma'</span>, email<span class="op">=</span><span class="st">'[email protected]'</span>, year_started<span class="op">=</span><span class="dv">2019</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Alma', email='[email protected]', year_started=2019, pwd=None)</code></pre>
</div>
</div>
<p>And now Charlie gets added via a Python dict.</p>
<div id="cell-40" class="cell">
<div class="sourceCode cell-code" id="cb17"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a>users.insert({<span class="st">'name'</span>: <span class="st">'Charlie'</span>, <span class="st">'email'</span>: <span class="st">'[email protected]'</span>, <span class="st">'year_started'</span>: <span class="dv">2018</span>})</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Charlie', email='[email protected]', year_started=2018, pwd=None)</code></pre>
</div>
</div>
<p>And now TODOs. Note that the inserted row is returned:</p>
<div id="cell-42" class="cell">
<div class="sourceCode cell-code" id="cb19"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a>todos.insert(Todo(title<span class="op">=</span><span class="st">'Write MiniDataAPI spec'</span>, status<span class="op">=</span><span class="st">'open'</span>, name<span class="op">=</span><span class="st">'Braden'</span>))</span>
<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a>todos.insert(title<span class="op">=</span><span class="st">'Implement SSE in FastHTML'</span>, status<span class="op">=</span><span class="st">'open'</span>, name<span class="op">=</span><span class="st">'Alma'</span>)</span>
<span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a>todo <span class="op">=</span> todos.insert(<span class="bu">dict</span>(title<span class="op">=</span><span class="st">'Finish development of FastHTML'</span>, status<span class="op">=</span><span class="st">'closed'</span>, name<span class="op">=</span><span class="st">'Charlie'</span>))</span>
<span id="cb19-4"><a href="#cb19-4" aria-hidden="true" tabindex="-1"></a>todo</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Todo(id=3, title='Finish development of FastHTML', detail=None, status='closed', name='Charlie')</code></pre>
</div>
</div>
<p>Let’s do the same with the <code>Publications</code> table.</p>
<div id="cell-44" class="cell">
<div class="sourceCode cell-code" id="cb21"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a>publications.insert(Publication(authors<span class="op">=</span><span class="st">'Alma'</span>, year<span class="op">=</span><span class="dv">2019</span>, title<span class="op">=</span><span class="st">'FastHTML'</span>))</span>
<span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a>publications.insert(authors<span class="op">=</span><span class="st">'Alma'</span>, year<span class="op">=</span><span class="dv">2030</span>, title<span class="op">=</span><span class="st">'FastHTML and beyond'</span>)</span>
<span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a>publication<span class="op">=</span> publications.insert((<span class="bu">dict</span>(authors<span class="op">=</span><span class="st">'Alma'</span>, year<span class="op">=</span><span class="dv">2035</span>, title<span class="op">=</span><span class="st">'FastHTML, the early years'</span>)))</span>
<span id="cb21-4"><a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>publication</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Publication(authors='Alma', year=2035, title='FastHTML, the early years')</code></pre>
</div>
</div>
</section>
<section id="square-bracket-search" class="level3">
<h3 class="anchored" data-anchor-id="square-bracket-search">Square bracket search []</h3>
<p>Get a single record by entering a primary key into a table object within square brackets. Let’s see if we can find Alma.</p>
<div id="cell-47" class="cell">
<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a>user <span class="op">=</span> users[<span class="st">'Alma'</span>]</span>
<span id="cb23-2"><a href="#cb23-2" aria-hidden="true" tabindex="-1"></a>user</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Alma', email='[email protected]', year_started=2019, pwd=None)</code></pre>
</div>
</div>
<p>If no record is found, a <code>NotFoundError</code> error is raised. Here we look for David, who hasn’t yet been added to our users table.</p>
<div id="cell-49" class="cell">
<div class="sourceCode cell-code" id="cb25"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="cf">try</span>: users[<span class="st">'David'</span>]</span>
<span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a><span class="cf">except</span> NotFoundError: <span class="bu">print</span>(<span class="ss">f'User not found'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-stdout">
<pre><code>User not found</code></pre>
</div>
</div>
<p>Here’s a demonstration of a ticket search, demonstrating how this works with non-string primary keys.</p>
<div id="cell-51" class="cell">
<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a>todos[<span class="dv">1</span>]</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Todo(id=1, title='Write MiniDataAPI spec', detail=None, status='open', name='Braden')</code></pre>
</div>
</div>
<p>Compound primary keys can be supplied in lists or tuples, in the order they were defined. In this case it is the <code>authors</code> and <code>year</code> columns.</p>
<p>Here’s a query by compound primary key done with a <code>list</code>:</p>
<div id="cell-53" class="cell">
<div class="sourceCode cell-code" id="cb29"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true" tabindex="-1"></a>publications[[<span class="st">'Alma'</span>, <span class="dv">2019</span>]]</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Publication(authors='Alma', year=2019, title='FastHTML')</code></pre>
</div>
</div>
<p>Here’s the same query done directly with index args.</p>
<div id="cell-55" class="cell">
<div class="sourceCode cell-code" id="cb31"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb31-1"><a href="#cb31-1" aria-hidden="true" tabindex="-1"></a>publications[<span class="st">'Alma'</span>, <span class="dv">2030</span>]</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Publication(authors='Alma', year=2030, title='FastHTML and beyond')</code></pre>
</div>
</div>
</section>
<section id="parentheses-search" class="level3">
<h3 class="anchored" data-anchor-id="parentheses-search">Parentheses search ()</h3>
<p>Get zero to many records by entering values with parentheses searches. If nothing is in the parentheses, then everything is returned.</p>
<div id="cell-58" class="cell">
<div class="sourceCode cell-code" id="cb33"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb33-1"><a href="#cb33-1" aria-hidden="true" tabindex="-1"></a>users()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[User(name='Braden', email='[email protected]', year_started=2018, pwd=None),
User(name='Alma', email='[email protected]', year_started=2019, pwd=None),
User(name='Charlie', email='[email protected]', year_started=2018, pwd=None)]</code></pre>
</div>
</div>
<p>We can order the results.</p>
<div id="cell-60" class="cell">
<div class="sourceCode cell-code" id="cb35"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true" tabindex="-1"></a>users(order_by<span class="op">=</span><span class="st">'name'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[User(name='Alma', email='[email protected]', year_started=2019, pwd=None),
User(name='Braden', email='[email protected]', year_started=2018, pwd=None),
User(name='Charlie', email='[email protected]', year_started=2018, pwd=None)]</code></pre>
</div>
</div>
<p>We can filter on the results:</p>
<div id="cell-62" class="cell">
<div class="sourceCode cell-code" id="cb37"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true" tabindex="-1"></a>users(where<span class="op">=</span><span class="st">"name='Alma'"</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[User(name='Alma', email='[email protected]', year_started=2019, pwd=None)]</code></pre>
</div>
</div>
<p>Generally you probably want to use placeholders, to avoid SQL injection attacks:</p>
<div id="cell-64" class="cell">
<div class="sourceCode cell-code" id="cb39"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb39-1"><a href="#cb39-1" aria-hidden="true" tabindex="-1"></a>users(<span class="st">"name=?"</span>, (<span class="st">'Alma'</span>,))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[User(name='Alma', email='[email protected]', year_started=2019, pwd=None)]</code></pre>
</div>
</div>
<p>We can limit results with the <code>limit</code> keyword:</p>
<div id="cell-66" class="cell">
<div class="sourceCode cell-code" id="cb41"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true" tabindex="-1"></a>users(limit<span class="op">=</span><span class="dv">1</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[User(name='Braden', email='[email protected]', year_started=2018, pwd=None)]</code></pre>
</div>
</div>
<p>If we’re using the <code>limit</code> keyword, we can also use the <code>offset</code> keyword to start the query later.</p>
<div id="cell-68" class="cell">
<div class="sourceCode cell-code" id="cb43"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb43-1"><a href="#cb43-1" aria-hidden="true" tabindex="-1"></a>users(limit<span class="op">=</span><span class="dv">5</span>, offset<span class="op">=</span><span class="dv">1</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[User(name='Alma', email='[email protected]', year_started=2019, pwd=None),
User(name='Charlie', email='[email protected]', year_started=2018, pwd=None)]</code></pre>
</div>
</div>
</section>
<section id="update" class="level3">
<h3 class="anchored" data-anchor-id="update">.update()</h3>
<p>Update an existing record of the database. Must accept Python dict, dataclasses, and standard classes. Uses the primary key for identifying the record to be changed. Returns an instance of the updated record.</p>
<p>Here’s with a normal Python class:</p>
<div id="cell-71" class="cell">
<div class="sourceCode cell-code" id="cb45"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb45-1"><a href="#cb45-1" aria-hidden="true" tabindex="-1"></a>user</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Alma', email='[email protected]', year_started=2019, pwd=None)</code></pre>
</div>
</div>
<div id="cell-72" class="cell">
<div class="sourceCode cell-code" id="cb47"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb47-1"><a href="#cb47-1" aria-hidden="true" tabindex="-1"></a>user.year_started <span class="op">=</span> <span class="dv">2099</span></span>
<span id="cb47-2"><a href="#cb47-2" aria-hidden="true" tabindex="-1"></a>users.update(user)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Alma', email='[email protected]', year_started=2099, pwd=None)</code></pre>
</div>
</div>
<p>Or use a dict:</p>
<div id="cell-74" class="cell">
<div class="sourceCode cell-code" id="cb49"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true" tabindex="-1"></a>users.update(<span class="bu">dict</span>(name<span class="op">=</span><span class="st">'Alma'</span>, year_started<span class="op">=</span><span class="dv">2199</span>, email<span class="op">=</span><span class="st">'[email protected]'</span>))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Alma', email='[email protected]', year_started=2199, pwd=None)</code></pre>
</div>
</div>
<p>Or use kwargs:</p>
<div id="cell-76" class="cell">
<div class="sourceCode cell-code" id="cb51"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true" tabindex="-1"></a>users.update(name<span class="op">=</span><span class="st">'Alma'</span>, year_started<span class="op">=</span><span class="dv">2149</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Alma', email='[email protected]', year_started=2149, pwd=None)</code></pre>
</div>
</div>
<p>If the primary key doesn’t match a record, raise a <code>NotFoundError</code>.</p>
<p>John hasn’t started with us yet so doesn’t get the chance yet to travel in time.</p>
<div id="cell-78" class="cell">
<div class="sourceCode cell-code" id="cb53"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true" tabindex="-1"></a><span class="cf">try</span>: users.update(User(name<span class="op">=</span><span class="st">'John'</span>, year_started<span class="op">=</span><span class="dv">2024</span>, email<span class="op">=</span><span class="st">'[email protected]'</span>))</span>
<span id="cb53-2"><a href="#cb53-2" aria-hidden="true" tabindex="-1"></a><span class="cf">except</span> NotFoundError: <span class="bu">print</span>(<span class="st">'User not found'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-stdout">
<pre><code>User not found</code></pre>
</div>
</div>
</section>
<section id="delete" class="level3">
<h3 class="anchored" data-anchor-id="delete">.delete()</h3>
<p>Delete a record of the database. Uses the primary key for identifying the record to be removed. Returns a table object.</p>
<p>Charlie decides to not travel in time. He exits our little group.</p>
<div id="cell-81" class="cell">
<div class="sourceCode cell-code" id="cb55"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true" tabindex="-1"></a>users.delete(<span class="st">'Charlie'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table user (name, email, year_started, pwd)&gt;</code></pre>
</div>
</div>
<p>If the primary key value can’t be found, raises a <code>NotFoundError</code>.</p>
<div id="cell-83" class="cell">
<div class="sourceCode cell-code" id="cb57"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true" tabindex="-1"></a><span class="cf">try</span>: users.delete(<span class="st">'Charlies'</span>)</span>
<span id="cb57-2"><a href="#cb57-2" aria-hidden="true" tabindex="-1"></a><span class="cf">except</span> NotFoundError: <span class="bu">print</span>(<span class="st">'User not found'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-stdout">
<pre><code>User not found</code></pre>
</div>
</div>
<p>In John’s case, he isn’t time travelling with us yet so can’t be removed.</p>
<div id="cell-85" class="cell">
<div class="sourceCode cell-code" id="cb59"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a><span class="cf">try</span>: users.delete(<span class="st">'John'</span>)</span>
<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a><span class="cf">except</span> NotFoundError: <span class="bu">print</span>(<span class="st">'User not found'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-stdout">
<pre><code>User not found</code></pre>
</div>
</div>
<p>Deleting records with compound primary keys requires providing the entire key.</p>
<div id="cell-87" class="cell">
<div class="sourceCode cell-code" id="cb61"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb61-1"><a href="#cb61-1" aria-hidden="true" tabindex="-1"></a>publications.delete([<span class="st">'Alma'</span> , <span class="dv">2035</span>])</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table publication (authors, year, title)&gt;</code></pre>
</div>
</div>
</section>
<section id="in-keyword" class="level3">
<h3 class="anchored" data-anchor-id="in-keyword"><code>in</code> keyword</h3>
<p>Are <code>Alma</code> and <code>John</code> contained <code>in</code> the Users table? Or, to be technically precise, is the item with the specified primary key value <code>in</code> this table?</p>
<div id="cell-90" class="cell">
<div class="sourceCode cell-code" id="cb63"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb63-1"><a href="#cb63-1" aria-hidden="true" tabindex="-1"></a><span class="co">'Alma'</span> <span class="kw">in</span> users, <span class="st">'John'</span> <span class="kw">in</span> users</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>(True, False)</code></pre>
</div>
</div>
<p>Also works with compound primary keys, as shown below. You’ll note that the operation can be done with either a <code>list</code> or <code>tuple</code>.</p>
<div id="cell-92" class="cell">
<div class="sourceCode cell-code" id="cb65"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb65-1"><a href="#cb65-1" aria-hidden="true" tabindex="-1"></a>[<span class="st">'Alma'</span>, <span class="dv">2019</span>] <span class="kw">in</span> publications</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>True</code></pre>
</div>
</div>
<p>And now for a <code>False</code> result, where John has no publications.</p>
<div id="cell-94" class="cell">
<div class="sourceCode cell-code" id="cb67"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb67-1"><a href="#cb67-1" aria-hidden="true" tabindex="-1"></a>(<span class="st">'John'</span>, <span class="dv">1967</span>) <span class="kw">in</span> publications</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>False</code></pre>
</div>
</div>
</section>
<section id="xtra" class="level3">
<h3 class="anchored" data-anchor-id="xtra">.xtra()</h3>
<p>If we set fields within the <code>.xtra</code> function to a particular value, then indexing is also filtered by those. This applies to every database method except for record creation. This makes it easier to limit users (or other objects) access to only things for which they have permission. This is a one-way operation, once set it can’t be undone for a particular table object.</p>
<p>For example, if we query all our records below without setting values via the <code>.xtra</code> function, we can see todos for everyone. Pay special attention to the <code>id</code> values of all three records, as we are about to filter most of them away.</p>
<div id="cell-97" class="cell">
<div class="sourceCode cell-code" id="cb69"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb69-1"><a href="#cb69-1" aria-hidden="true" tabindex="-1"></a>todos()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[Todo(id=1, title='Write MiniDataAPI spec', detail=None, status='open', name='Braden'),
Todo(id=2, title='Implement SSE in FastHTML', detail=None, status='open', name='Alma'),
Todo(id=3, title='Finish development of FastHTML', detail=None, status='closed', name='Charlie')]</code></pre>
</div>
</div>
<p>Let’s use <code>.xtra</code> to constrain results just to Charlie. We set the <code>name</code> field in Todos, but it could be any field defined for this table.</p>
<div id="cell-99" class="cell">
<div class="sourceCode cell-code" id="cb71"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb71-1"><a href="#cb71-1" aria-hidden="true" tabindex="-1"></a>todos.xtra(name<span class="op">=</span><span class="st">'Charlie'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div>
<p>We’ve now set a field to a value with <code>.xtra</code>, if we loop over all the records again, only those assigned to records with a <code>name</code> of <code>Charlie</code> will be displayed.</p>
<div id="cell-101" class="cell">
<div class="sourceCode cell-code" id="cb72"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb72-1"><a href="#cb72-1" aria-hidden="true" tabindex="-1"></a>todos()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>[Todo(id=3, title='Finish development of FastHTML', detail=None, status='closed', name='Charlie')]</code></pre>
</div>
</div>
<p>The <code>in</code> keyword is also affected. Only records with a <code>name</code> of Charlie will evaluate to be <code>True</code>. Let’s demonstrate by testing it with a Charlie record:</p>
<div id="cell-103" class="cell">
<div class="sourceCode cell-code" id="cb74"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb74-1"><a href="#cb74-1" aria-hidden="true" tabindex="-1"></a>ct <span class="op">=</span> todos[<span class="dv">3</span>]</span>
<span id="cb74-2"><a href="#cb74-2" aria-hidden="true" tabindex="-1"></a>ct</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Todo(id=3, title='Finish development of FastHTML', detail=None, status='closed', name='Charlie')</code></pre>
</div>
</div>
<p>Charlie’s record has an ID of 3. Here we demonstrate that Charlie’s TODO can be found in the list of todos:</p>
<div id="cell-105" class="cell">
<div class="sourceCode cell-code" id="cb76"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb76-1"><a href="#cb76-1" aria-hidden="true" tabindex="-1"></a>ct.<span class="bu">id</span> <span class="kw">in</span> todos</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>True</code></pre>
</div>
</div>
<p>If we try <code>in</code> with the other IDs the query fails because the filtering is now set to just records with a name of Charlie.</p>
<div id="cell-107" class="cell">
<div class="sourceCode cell-code" id="cb78"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb78-1"><a href="#cb78-1" aria-hidden="true" tabindex="-1"></a><span class="dv">1</span> <span class="kw">in</span> todos, <span class="dv">2</span> <span class="kw">in</span> todos</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>(False, False)</code></pre>
</div>
</div>
<div id="cell-108" class="cell">
<div class="sourceCode cell-code" id="cb80"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb80-1"><a href="#cb80-1" aria-hidden="true" tabindex="-1"></a><span class="cf">try</span>: todos[<span class="dv">2</span>]</span>
<span id="cb80-2"><a href="#cb80-2" aria-hidden="true" tabindex="-1"></a><span class="cf">except</span> NotFoundError: <span class="bu">print</span>(<span class="st">'Record not found'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-stdout">
<pre><code>Record not found</code></pre>
</div>
</div>
<p>We are also constrained by what records we can update. In the following example we try to update a TODO not named ‘Charlie’. Because the name is wrong, the <code>.update</code> function will raise a <code>NotFoundError</code>.</p>
<div id="cell-110" class="cell">
<div class="sourceCode cell-code" id="cb82"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb82-1"><a href="#cb82-1" aria-hidden="true" tabindex="-1"></a><span class="cf">try</span>: todos.update(Todo(<span class="bu">id</span><span class="op">=</span><span class="dv">1</span>, title<span class="op">=</span><span class="st">'Finish MiniDataAPI Spec'</span>, status<span class="op">=</span><span class="st">'closed'</span>, name<span class="op">=</span><span class="st">'Braden'</span>))</span>
<span id="cb82-2"><a href="#cb82-2" aria-hidden="true" tabindex="-1"></a><span class="cf">except</span> NotFoundError <span class="im">as</span> e: <span class="bu">print</span>(<span class="st">'Record not updated'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-stdout">
<pre><code>Record not updated</code></pre>
</div>
</div>
<p>Unlike poor Braden, Charlie isn’t filtered out. Let’s update his TODO.</p>
<div id="cell-112" class="cell">
<div class="sourceCode cell-code" id="cb84"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb84-1"><a href="#cb84-1" aria-hidden="true" tabindex="-1"></a>todos.update(Todo(<span class="bu">id</span><span class="op">=</span><span class="dv">3</span>, title<span class="op">=</span><span class="st">'Finish development of FastHTML'</span>, detail<span class="op">=</span><span class="va">None</span>, status<span class="op">=</span><span class="st">'closed'</span>, name<span class="op">=</span><span class="st">'Charlie'</span>))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Todo(id=3, title='Finish development of FastHTML', detail=None, status='closed', name='Charlie')</code></pre>
</div>
</div>
<p>Finally, once constrained by <code>.xtra</code>, only records with Charlie as the name can be deleted.</p>
<div id="cell-114" class="cell">
<div class="sourceCode cell-code" id="cb86"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb86-1"><a href="#cb86-1" aria-hidden="true" tabindex="-1"></a><span class="cf">try</span>: todos.delete(<span class="dv">1</span>)</span>
<span id="cb86-2"><a href="#cb86-2" aria-hidden="true" tabindex="-1"></a><span class="cf">except</span> NotFoundError <span class="im">as</span> e: <span class="bu">print</span>(<span class="st">'Record not updated'</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-stdout">
<pre><code>Record not updated</code></pre>
</div>
</div>
<p>Charlie’s TODO was to finish development of FastHTML. While the framework will stabilize, like any good project it will see new features added and the odd bug corrected for many years to come. Therefore, Charlie’s TODO is nonsensical. Let’s delete it.</p>
<div id="cell-116" class="cell">
<div class="sourceCode cell-code" id="cb88"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb88-1"><a href="#cb88-1" aria-hidden="true" tabindex="-1"></a>todos.delete(ct.<span class="bu">id</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table todo (id, title, detail, status, name)&gt;</code></pre>
</div>
</div>
<p>When a TODO is inserted, the <code>xtra</code> fields are automatically set. This ensures that we don’t accidentally, for instance, insert items for others users. Note that here we don’t set the <code>name</code> field, but it’s still included in the resultant row:</p>
<div id="cell-118" class="cell">
<div class="sourceCode cell-code" id="cb90"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb90-1"><a href="#cb90-1" aria-hidden="true" tabindex="-1"></a>ct <span class="op">=</span> todos.insert(Todo(title<span class="op">=</span><span class="st">'Rewrite personal site in FastHTML'</span>, status<span class="op">=</span><span class="st">'open'</span>))</span>
<span id="cb90-2"><a href="#cb90-2" aria-hidden="true" tabindex="-1"></a>ct</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Todo(id=3, title='Rewrite personal site in FastHTML', detail=None, status='open', name='Charlie')</code></pre>
</div>
</div>
<p>If we try to change the username to someone else, the change is ignored, due to <code>xtra</code>:</p>
<div id="cell-120" class="cell">
<div class="sourceCode cell-code" id="cb92"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb92-1"><a href="#cb92-1" aria-hidden="true" tabindex="-1"></a>ct.name <span class="op">=</span> <span class="st">'Braden'</span></span>
<span id="cb92-2"><a href="#cb92-2" aria-hidden="true" tabindex="-1"></a>todos.update(ct)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>Todo(id=3, title='Rewrite personal site in FastHTML', detail=None, status='open', name='Charlie')</code></pre>
</div>
</div>
</section>
</section>
<section id="sql-first-design" class="level2">
<h2 class="anchored" data-anchor-id="sql-first-design">SQL-first design</h2>
<div id="cell-122" class="cell">
<div class="sourceCode cell-code" id="cb94"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb94-1"><a href="#cb94-1" aria-hidden="true" tabindex="-1"></a>users <span class="op">=</span> <span class="va">None</span></span>
<span id="cb94-2"><a href="#cb94-2" aria-hidden="true" tabindex="-1"></a>User <span class="op">=</span> <span class="va">None</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div>
<div id="cell-123" class="cell">
<div class="sourceCode cell-code" id="cb95"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb95-1"><a href="#cb95-1" aria-hidden="true" tabindex="-1"></a>users <span class="op">=</span> db.t.user</span>
<span id="cb95-2"><a href="#cb95-2" aria-hidden="true" tabindex="-1"></a>users</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>&lt;Table user (name, email, year_started, pwd)&gt;</code></pre>
</div>
</div>
<p>(This section needs to be documented properly.)</p>
<p>From the table objects we can extract a Dataclass version of our tables. Usually this is given an singular uppercase version of our table name, which in this case is <code>User</code>.</p>
<div id="cell-125" class="cell">
<div class="sourceCode cell-code" id="cb97"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb97-1"><a href="#cb97-1" aria-hidden="true" tabindex="-1"></a>User <span class="op">=</span> users.dataclass()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div>
<div id="cell-126" class="cell">
<div class="sourceCode cell-code" id="cb98"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb98-1"><a href="#cb98-1" aria-hidden="true" tabindex="-1"></a>User(name<span class="op">=</span><span class="st">'Braden'</span>, email<span class="op">=</span><span class="st">'[email protected]'</span>, year_started<span class="op">=</span><span class="dv">2018</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="cell-output cell-output-display">
<pre><code>User(name='Braden', email='[email protected]', year_started=2018, pwd=UNSET)</code></pre>
</div>
</div>
</section>
<section id="implementations" class="level2">
<h2 class="anchored" data-anchor-id="implementations">Implementations</h2>
<section id="implementing-minidataapi-for-a-new-datastore" class="level3">
<h3 class="anchored" data-anchor-id="implementing-minidataapi-for-a-new-datastore">Implementing MiniDataAPI for a new datastore</h3>
<p>For creating new implementations, the code examples in this specification are the test case for the API. New implementations should pass the tests in order to be compliant with the specification.</p>
</section>
<section id="implementations-1" class="level3">
<h3 class="anchored" data-anchor-id="implementations-1">Implementations</h3>
<ul>
<li><a href="https://github.com/AnswerDotAI/fastlite">fastlite</a> - The original implementation, only for Sqlite</li>
<li><a href="https://github.com/AnswerDotAI/fastsql">fastsql</a> - An SQL database agnostic implementation based on the excellent SQLAlchemy library.</li>
</ul>
</section>
</section>
</main> <!-- /main -->
<script id="quarto-html-after-body" type="application/javascript">
window.document.addEventListener("DOMContentLoaded", function (event) {
const toggleBodyColorMode = (bsSheetEl) => {
const mode = bsSheetEl.getAttribute("data-mode");
const bodyEl = window.document.querySelector("body");
if (mode === "dark") {
bodyEl.classList.add("quarto-dark");
bodyEl.classList.remove("quarto-light");
} else {
bodyEl.classList.add("quarto-light");
bodyEl.classList.remove("quarto-dark");
}
}
const toggleBodyColorPrimary = () => {
const bsSheetEl = window.document.querySelector("link#quarto-bootstrap");
if (bsSheetEl) {
toggleBodyColorMode(bsSheetEl);
}
}
toggleBodyColorPrimary();
const icon = "";
const anchorJS = new window.AnchorJS();
anchorJS.options = {
placement: 'right',
icon: icon
};
anchorJS.add('.anchored');
const isCodeAnnotation = (el) => {
for (const clz of el.classList) {
if (clz.startsWith('code-annotation-')) {
return true;
}
}
return false;
}
const onCopySuccess = function(e) {
// button target
const button = e.trigger;
// don't keep focus
button.blur();
// flash "checked"
button.classList.add('code-copy-button-checked');
var currentTitle = button.getAttribute("title");
button.setAttribute("title", "Copied!");
let tooltip;
if (window.bootstrap) {
button.setAttribute("data-bs-toggle", "tooltip");
button.setAttribute("data-bs-placement", "left");
button.setAttribute("data-bs-title", "Copied!");
tooltip = new bootstrap.Tooltip(button,
{ trigger: "manual",
customClass: "code-copy-button-tooltip",
offset: [0, -8]});
tooltip.show();
}
setTimeout(function() {
if (tooltip) {
tooltip.hide();
button.removeAttribute("data-bs-title");
button.removeAttribute("data-bs-toggle");
button.removeAttribute("data-bs-placement");
}
button.setAttribute("title", currentTitle);
button.classList.remove('code-copy-button-checked');
}, 1000);
// clear code selection
e.clearSelection();
}
const getTextToCopy = function(trigger) {
const codeEl = trigger.previousElementSibling.cloneNode(true);
for (const childEl of codeEl.children) {
if (isCodeAnnotation(childEl)) {
childEl.remove();
}
}
return codeEl.innerText;
}
const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
text: getTextToCopy
});
clipboard.on('success', onCopySuccess);
if (window.document.getElementById('quarto-embedded-source-code-modal')) {
const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
text: getTextToCopy,
container: window.document.getElementById('quarto-embedded-source-code-modal')
});
clipboardModal.on('success', onCopySuccess);
}
var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
var mailtoRegex = new RegExp(/^mailto:/);
var filterRegex = new RegExp("https:\/\/www\.fastht\.ml\/docs\/");
var isInternal = (href) => {
return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
}
// Inspect non-navigation links and adorn them if external
var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
for (var i=0; i<links.length; i++) {
const link = links[i];
if (!isInternal(link.href)) {
// undo the damage that might have been done by quarto-nav.js in the case of
// links that we want to consider external
if (link.dataset.originalHref !== undefined) {
link.href = link.dataset.originalHref;
}
}
}
function tippyHover(el, contentFn, onTriggerFn, onUntriggerFn) {
const config = {
allowHTML: true,
maxWidth: 500,
delay: 100,
arrow: false,
appendTo: function(el) {
return el.parentElement;
},
interactive: true,
interactiveBorder: 10,
theme: 'quarto',
placement: 'bottom-start',
};
if (contentFn) {
config.content = contentFn;
}
if (onTriggerFn) {
config.onTrigger = onTriggerFn;
}
if (onUntriggerFn) {
config.onUntrigger = onUntriggerFn;
}
window.tippy(el, config);
}
const noterefs = window.document.querySelectorAll('a[role="doc-noteref"]');
for (var i=0; i<noterefs.length; i++) {
const ref = noterefs[i];
tippyHover(ref, function() {
// use id or data attribute instead here
let href = ref.getAttribute('data-footnote-href') || ref.getAttribute('href');
try { href = new URL(href).hash; } catch {}
const id = href.replace(/^#\/?/, "");
const note = window.document.getElementById(id);
if (note) {
return note.innerHTML;
} else {
return "";
}
});
}
const xrefs = window.document.querySelectorAll('a.quarto-xref');
const processXRef = (id, note) => {
// Strip column container classes
const stripColumnClz = (el) => {
el.classList.remove("page-full", "page-columns");
if (el.children) {
for (const child of el.children) {
stripColumnClz(child);
}
}
}
stripColumnClz(note)
if (id === null || id.startsWith('sec-')) {
// Special case sections, only their first couple elements
const container = document.createElement("div");
if (note.children && note.children.length > 2) {
container.appendChild(note.children[0].cloneNode(true));
for (let i = 1; i < note.children.length; i++) {
const child = note.children[i];
if (child.tagName === "P" && child.innerText === "") {
continue;
} else {
container.appendChild(child.cloneNode(true));
break;
}
}
if (window.Quarto?.typesetMath) {
window.Quarto.typesetMath(container);
}
return container.innerHTML
} else {
if (window.Quarto?.typesetMath) {
window.Quarto.typesetMath(note);
}
return note.innerHTML;
}
} else {
// Remove any anchor links if they are present
const anchorLink = note.querySelector('a.anchorjs-link');
if (anchorLink) {
anchorLink.remove();
}
if (window.Quarto?.typesetMath) {
window.Quarto.typesetMath(note);
}
if (note.classList.contains("callout")) {
return note.outerHTML;
} else {
return note.innerHTML;
}
}
}
for (var i=0; i<xrefs.length; i++) {
const xref = xrefs[i];
tippyHover(xref, undefined, function(instance) {
instance.disable();
let url = xref.getAttribute('href');
let hash = undefined;
if (url.startsWith('#')) {
hash = url;
} else {
try { hash = new URL(url).hash; } catch {}
}
if (hash) {
const id = hash.replace(/^#\/?/, "");
const note = window.document.getElementById(id);
if (note !== null) {
try {
const html = processXRef(id, note.cloneNode(true));
instance.setContent(html);
} finally {
instance.enable();
instance.show();
}
} else {
// See if we can fetch this
fetch(url.split('#')[0])
.then(res => res.text())
.then(html => {
const parser = new DOMParser();
const htmlDoc = parser.parseFromString(html, "text/html");
const note = htmlDoc.getElementById(id);
if (note !== null) {
const html = processXRef(id, note);
instance.setContent(html);
}
}).finally(() => {
instance.enable();
instance.show();
});
}
} else {
// See if we can fetch a full url (with no hash to target)
// This is a special case and we should probably do some content thinning / targeting
fetch(url)
.then(res => res.text())
.then(html => {
const parser = new DOMParser();
const htmlDoc = parser.parseFromString(html, "text/html");
const note = htmlDoc.querySelector('main.content');
if (note !== null) {
// This should only happen for chapter cross references
// (since there is no id in the URL)
// remove the first header
if (note.children.length > 0 && note.children[0].tagName === "HEADER") {
note.children[0].remove();
}
const html = processXRef(null, note);
instance.setContent(html);
}
}).finally(() => {
instance.enable();
instance.show();
});
}
}, function(instance) {
});
}
let selectedAnnoteEl;
const selectorForAnnotation = ( cell, annotation) => {
let cellAttr = 'data-code-cell="' + cell + '"';
let lineAttr = 'data-code-annotation="' + annotation + '"';
const selector = 'span[' + cellAttr + '][' + lineAttr + ']';
return selector;
}
const selectCodeLines = (annoteEl) => {
const doc = window.document;
const targetCell = annoteEl.getAttribute("data-target-cell");
const targetAnnotation = annoteEl.getAttribute("data-target-annotation");
const annoteSpan = window.document.querySelector(selectorForAnnotation(targetCell, targetAnnotation));
const lines = annoteSpan.getAttribute("data-code-lines").split(",");
const lineIds = lines.map((line) => {
return targetCell + "-" + line;
})
let top = null;
let height = null;
let parent = null;
if (lineIds.length > 0) {
//compute the position of the single el (top and bottom and make a div)
const el = window.document.getElementById(lineIds[0]);
top = el.offsetTop;
height = el.offsetHeight;
parent = el.parentElement.parentElement;
if (lineIds.length > 1) {
const lastEl = window.document.getElementById(lineIds[lineIds.length - 1]);
const bottom = lastEl.offsetTop + lastEl.offsetHeight;
height = bottom - top;
}
if (top !== null && height !== null && parent !== null) {
// cook up a div (if necessary) and position it
let div = window.document.getElementById("code-annotation-line-highlight");
if (div === null) {
div = window.document.createElement("div");
div.setAttribute("id", "code-annotation-line-highlight");
div.style.position = 'absolute';
parent.appendChild(div);
}
div.style.top = top - 2 + "px";
div.style.height = height + 4 + "px";
div.style.left = 0;
let gutterDiv = window.document.getElementById("code-annotation-line-highlight-gutter");
if (gutterDiv === null) {
gutterDiv = window.document.createElement("div");
gutterDiv.setAttribute("id", "code-annotation-line-highlight-gutter");
gutterDiv.style.position = 'absolute';
const codeCell = window.document.getElementById(targetCell);
const gutter = codeCell.querySelector('.code-annotation-gutter');
gutter.appendChild(gutterDiv);
}
gutterDiv.style.top = top - 2 + "px";
gutterDiv.style.height = height + 4 + "px";
}
selectedAnnoteEl = annoteEl;
}
};
const unselectCodeLines = () => {
const elementsIds = ["code-annotation-line-highlight", "code-annotation-line-highlight-gutter"];
elementsIds.forEach((elId) => {
const div = window.document.getElementById(elId);
if (div) {
div.remove();
}
});
selectedAnnoteEl = undefined;
};
// Handle positioning of the toggle
window.addEventListener(
"resize",
throttle(() => {
elRect = undefined;
if (selectedAnnoteEl) {
selectCodeLines(selectedAnnoteEl);
}
}, 10)
);
function throttle(fn, ms) {
let throttle = false;
let timer;
return (...args) => {
if(!throttle) { // first call gets through
fn.apply(this, args);
throttle = true;
} else { // all the others get throttled
if(timer) clearTimeout(timer); // cancel #2
timer = setTimeout(() => {
fn.apply(this, args);
timer = throttle = false;
}, ms);
}
};
}
// Attach click handler to the DT
const annoteDls = window.document.querySelectorAll('dt[data-target-cell]');
for (const annoteDlNode of annoteDls) {
annoteDlNode.addEventListener('click', (event) => {
const clickedEl = event.target;
if (clickedEl !== selectedAnnoteEl) {
unselectCodeLines();
const activeEl = window.document.querySelector('dt[data-target-cell].code-annotation-active');
if (activeEl) {
activeEl.classList.remove('code-annotation-active');
}
selectCodeLines(clickedEl);
clickedEl.classList.add('code-annotation-active');
} else {
// Unselect the line
unselectCodeLines();
clickedEl.classList.remove('code-annotation-active');
}
});
}
const findCites = (el) => {
const parentEl = el.parentElement;
if (parentEl) {
const cites = parentEl.dataset.cites;
if (cites) {
return {
el,
cites: cites.split(' ')
};
} else {
return findCites(el.parentElement)
}
} else {
return undefined;
}
};
var bibliorefs = window.document.querySelectorAll('a[role="doc-biblioref"]');
for (var i=0; i<bibliorefs.length; i++) {
const ref = bibliorefs[i];
const citeInfo = findCites(ref);
if (citeInfo) {
tippyHover(citeInfo.el, function() {
var popup = window.document.createElement('div');
citeInfo.cites.forEach(function(cite) {
var citeDiv = window.document.createElement('div');
citeDiv.classList.add('hanging-indent');
citeDiv.classList.add('csl-entry');
var biblioDiv = window.document.getElementById('ref-' + cite);
if (biblioDiv) {
citeDiv.innerHTML = biblioDiv.innerHTML;
}
popup.appendChild(citeDiv);
});
return popup.innerHTML;
});
}
}
});
</script>
</div> <!-- /content -->
<footer class="footer"><div class="nav-footer"><div class="nav-footer-center"><div class="toc-actions d-sm-block d-md-none"><ul><li><a href="https://github.com/AnswerDotAI/fasthtml/issues/new" class="toc-action"><i class="bi bi-github"></i>Report an issue</a></li></ul></div></div></div></footer></body></html>