@osqd/jql 0.1.1

package/docs/course/15-pushdown.md

@@ -0,0 +1,240 @@
+# Lesson 15 — Pushing a query into a store
+
+**Goal:** let a database answer the part of a query it can, and answer the rest here — without
+either half quietly changing the question.
+
+← [Course](index.md) · Previous: [Logs and streams](14-streams-and-cli.md) · Next: [Extending it, and proving it](16-extending.md)
+
+---
+
+## Half a query is still useful
+
+Every query so far has run over an array in memory. Harbour's orders really live in a
+database, and that database can answer *some* of what a query asks — the indexed fields, the
+operators it happens to have — and none of the rest.
+
+`plan(query, capabilities)` splits a query in two:
+
+```
+pushed ∧ remaining ≡ query
+```
+
+The store filters with `pushed`; this engine filters what comes back with `remaining`. That
+identity is the contract, and it has a direction: **neither half is ever wider than the
+query**, so a caller that runs only `pushed` gets too many rows rather than too few.
+
+It splits only on **conjunctions**, because those are the only parts that can go to either
+side independently. A branch of an `$or` cannot be split without changing what is asked, so a
+conjunct goes whole or not at all.
+
+## Describing a store
+
+Save this as `harbour/store.mjs`. It is what a modest store can do: a few indexed columns,
+equality and ranges, nothing clever.
+
+```js
+/** What Harbour's database can answer for itself. */
+export const INDEXED = {
+  fields: ["status", "customer.country", "placed", "total"],
+  operators: ["$eq", "$in", "$gt", "$gte", "$lt", "$lte", "$and"],
+  or: false,
+  not: false,
+};
+
+/** Print a plan the way a person reads one. */
+export function show(result) {
+  console.log("  pushed   ", JSON.stringify(result.pushed));
+  console.log("  remaining", JSON.stringify(result.remaining));
+  console.log("  complete ", result.complete);
+  for (const kept of result.kept) console.log(`  kept      ${kept.at}: ${kept.why}`);
+}
+```
+
+| | |
+| --- | --- |
+| `fields` | the paths it can filter on, as **it** names them, or `"all"` |
+| `operators` | the operators it can answer, in JQL's names, or `"all"` |
+| `or` | whether it can answer an `$or`. Default `false` — plenty of key-value stores cannot |
+| `not` | whether it can answer a negation. Default `false` |
+| `accepts` | the last word on one field's condition, for a store whose limits depend on the *values* |
+
+## Splitting a query
+
+```js
+import { plan } from "@osqd/jql";
+import { INDEXED, show } from "./store.mjs";
+
+const query = {
+  status: "paid",
+  "customer.country": "GB",
+  note: { $contains: "neighbour" },
+  "lines.quantity": { $gte: 3 },
+};
+
+show(plan(query, INDEXED));
+```
+
+```
+  pushed    {"$and":[{"status":"paid"},{"customer.country":"GB"}]}
+  remaining {"$and":[{"note":{"$contains":"neighbour"}},{"lines.quantity":{"$gte":3}}]}
+  complete  false
+  kept      note: the store cannot filter on "note"
+  kept      lines.quantity: the store cannot filter on "lines.quantity"
+```
+
+Two conjuncts went to the store, two stayed here, and `kept` says why each one stayed.
+
+That sentence — `the store cannot filter on "note"` — is something you can act on. Either
+index `note` and add it to `fields`, or decide you do not care. A pushdown layer that silently
+held things back would leave you guessing why a query is slow.
+
+## The halves add up
+
+```js
+import { filter, plan } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+import { INDEXED } from "./store.mjs";
+
+const query = {
+  status: "paid",
+  "customer.country": "GB",
+  note: { $contains: "neighbour" },
+  "lines.quantity": { $gte: 3 },
+};
+
+const { pushed, remaining } = plan(query, INDEXED);
+
+// `orders` stands in for the database here; in real life this is a round trip.
+const fromStore = filter(orders, pushed ?? {});
+const answer = filter(fromStore, remaining ?? {});
+
+console.log("the store returned:", fromStore.map((o) => o.id));
+console.log("the engine kept   :", answer.map((o) => o.id));
+console.log("whole query, here :", filter(orders, query).map((o) => o.id));
+```
+
+```
+the store returned: [ 'o-1001', 'o-1003' ]
+the engine kept   : [ 'o-1001' ]
+whole query, here : [ 'o-1001' ]
+```
+
+The store narrowed eight orders to two, using only indexed columns; the engine took one of
+those away. The answer is the one the whole query gives.
+
+## What cannot be split at all
+
+```js
+import { plan } from "@osqd/jql";
+import { INDEXED, show } from "./store.mjs";
+
+show(plan({ $or: [{ status: "open" }, { status: "paid" }] }, INDEXED));
+```
+
+```
+  pushed    undefined
+  remaining {"$or":[{"status":"open"},{"status":"paid"}]}
+  complete  false
+  kept      $or: the store cannot answer an $or
+```
+
+`pushed` is `undefined` — there is nothing to send. Both branches are about an indexed field,
+but this store cannot answer an `$or` at all, and half an `$or` is a different question. So
+the whole thing stays here, and `kept` says so in one line.
+
+## A store that can answer more
+
+A store target is a capabilities object plus a translator. One ships with the library, for
+document databases that speak the conventional query-document dialect:
+
+```js
+import { plan } from "@osqd/jql";
+import { MONGO_CAPABILITIES, toMongoFilter } from "@osqd/jql/mongo";
+
+const query = {
+  status: "paid",
+  "customer.country": "GB",
+  note: { $contains: "neighbour" },
+  "lines.quantity": { $gte: 3 },
+};
+
+const planned = plan(query, MONGO_CAPABILITIES);
+
+console.log("complete:", planned.complete);
+// A driver is handed real RegExp and Date objects, which JSON.stringify cannot show.
+const readable = (value) => JSON.stringify(value, (_, held) => (held instanceof RegExp ? `/${held.source}/${held.flags}` : held));
+console.log("filter  :", readable(toMongoFilter(planned.pushed)));
+```
+
+```
+complete: true
+filter  : {"$and":[{"status":"paid"},{"customer.country":"GB"},{"note":"/neighbour/"},{"lines.quantity":{"$gte":3}}]}
+```
+
+All four conjuncts went, so `complete` is `true` and there is no second pass to run:
+
+```ts
+const { pushed, remaining, complete } = plan(query, MONGO_CAPABILITIES);
+const rows = await collection.find(toMongoFilter(pushed)).toArray();
+const answer = complete ? rows : filter(rows, remaining);
+```
+
+Look at what happened to `$contains`. The store has no such operator, so the target wrote an
+**escaped pattern** that the store runs exactly as JQL would.
+
+What a target will not do is guess. Any operator the store cannot answer *exactly* is left out
+of its capabilities, so `plan` keeps those clauses here and the translator never sees them. A
+translation that was *nearly* right would be the worst of both worlds: fewer rows than the
+query asked for, from a store that looked as though it had answered.
+
+## The limit of `complete`
+
+Capabilities describe what a store can be *asked*. They cannot describe how it resolves a path
+through your data, and those can differ.
+
+The case to know about is an array held directly inside another array. JQL sees an array
+through at every level (lesson 3); a store may apply a path segment to an array's elements but
+not to the elements of *those* arrays. For such a document the two give different answers, and
+`plan` cannot know, because nothing in the query says what shape the rows are.
+
+If your collection stores arrays of arrays of documents, do not read `complete` as permission
+to skip the second pass over those fields.
+
+## Exercise
+
+Harbour's store gains an index on `tags`. Add it to `INDEXED` and see what changes for
+`{ status: "paid", tags: "repeat", note: { $contains: "same" } }`.
+
+<details>
+<summary>Answer</summary>
+
+```js
+import { plan } from "@osqd/jql";
+import { INDEXED, show } from "./store.mjs";
+
+const WITH_TAGS = { ...INDEXED, fields: [...INDEXED.fields, "tags"] };
+
+show(plan({ status: "paid", tags: "repeat", note: { $contains: "same" } }, WITH_TAGS));
+```
+
+```
+  pushed    {"$and":[{"status":"paid"},{"tags":"repeat"}]}
+  remaining {"note":{"$contains":"same"}}
+  complete  false
+  kept      note: the store cannot filter on "note"
+```
+
+`tags: "repeat"` pushed as an equality even though `tags` is a list, because *a value matches
+any element* is a rule both sides share — and shared rules are exactly what makes a clause
+safe to push.
+
+`note` stayed, and the reason is worth reading closely: `the store cannot filter on "note"`.
+Not "cannot answer `$contains`" — `note` is not in `fields` at all, so the field is refused
+before the operator is ever considered. Two different fixes hide behind those two sentences
+(index the column, or teach the store an operator), which is why `kept` says which one it is.
+</details>
+
+## Related
+
+- [Pushing a query into a store](../guides/pushdown.md) — the guide, including writing your own target
+- [Specification §14](../reference/specification.md#14-splitting-a-query) — the split, as a rule other implementations can follow

package/docs/course/16-extending.md

@@ -0,0 +1,199 @@
+# Lesson 16 — Extending it, and proving it
+
+**Goal:** add an operator this project needs, check a filter before it meets anybody, and
+finish Harbour.
+
+← [Course](index.md) · Previous: [Pushing into a store](15-pushdown.md)
+
+---
+
+## Operators of your own
+
+Some questions are not JSON. *"Is this address inside that network"*, *"does this score beat
+the model's threshold"* — no amount of `$gt` expresses them, and the honest answer is to let a
+project add an operator.
+
+The cost of doing that is portability, so the language makes the cost **visible**: an added
+operator's name must begin with `$x` and a capital letter. Somebody reading a stored filter
+can see at a glance that it needs more than a standard engine, and a future version of JQL
+cannot collide with a name you chose.
+
+Save this as `harbour/within-days.mjs`:
+
+```js
+import { JqlError } from "@osqd/jql";
+
+/** How recently an order was placed — the sort of question a project adds for itself. */
+export const withinDays = {
+  name: "$xWithinDays",
+  cost: 2,
+  compile: (operand, at) => {
+    if (typeof operand !== "number" || !Number.isFinite(operand)) {
+      throw new JqlError(`takes a number of days, not ${JSON.stringify(operand)}`, at);
+    }
+    const since = Date.parse("2026-09-25T12:00:00Z") - operand * 86_400_000;
+    return (value) => typeof value === "string" && Date.parse(value) >= since;
+  },
+};
+```
+
+## Using it
+
+```js
+import { filter } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+import { withinDays } from "./within-days.mjs";
+
+const operators = [withinDays];
+const ids = (query) => filter(orders, query, { operators }).map((o) => o.id);
+
+console.log("within 7 days :", ids({ placed: { $xWithinDays: 7 } }));
+console.log("within 20 days:", ids({ placed: { $xWithinDays: 20 } }));
+```
+
+```
+within 7 days : [ 'o-1006', 'o-1007', 'o-1008' ]
+within 20 days: [ 'o-1003', 'o-1004', 'o-1005', 'o-1006', 'o-1007', 'o-1008' ]
+```
+
+From the query's side it is an ordinary operator: it composes with everything else, it can sit
+inside `$or`, and `explain` describes it like any other clause.
+
+## Three refusals that make it safe to have
+
+```js
+import { filter, validate } from "@osqd/jql";
+import { orders } from "./orders.mjs";
+import { withinDays } from "./within-days.mjs";
+
+const say = (verdict) => console.log("  ", verdict.valid ? "accepted" : verdict.error.message);
+
+console.log("an operand that is not a number:");
+say(validate({ placed: { $xWithinDays: "seven" } }, { operators: [withinDays] }));
+
+console.log("an engine that was not given it:");
+say(validate({ placed: { $xWithinDays: 7 } }));
+
+console.log("a name without the $x:");
+try {
+  filter(orders, { placed: { $withinDays: 7 } }, { operators: [{ ...withinDays, name: "$withinDays" }] });
+  console.log("   accepted");
+} catch (error) {
+  console.log("  ", error.message);
+}
+```
+
+```
+an operand that is not a number:
+   at placed.$xWithinDays: takes a number of days, not "seven"
+an engine that was not given it:
+   at placed.$xWithinDays: "$xWithinDays" is an added operator, and this query was compiled without it; pass it in `operators`
+a name without the $x:
+   at operators: "$withinDays" cannot name an added operator: the name is $x and a capital, such as "$xCidr", so a query that needs more than standard JQL says so
+```
+
+Each of those is a property worth having:
+
+- **`compile` runs once**, when the query is compiled, and returns the test. Validate the
+  operand there and throw `JqlError` — the sentence reaches whoever wrote the query, with the
+  place in it.
+- **A query that needs an added operator says so.** The second refusal is an engine *without*
+  the operator, naming it and saying what to do, rather than treating it as a typo and
+  matching nothing.
+- **The naming rule is enforced**, so the visibility it buys is real.
+
+There is a fourth property with no error message: **`cost`** is a hint for ordering an `$and`,
+so a cheap equality runs before your expensive test. It changes the speed and never the
+answer.
+
+Before reaching for any of this, look at the field operators once more. `$word`, `$glob`,
+`$length` and `{ "$field": … }` exist precisely because they are the four things people most
+often added an escape hatch to do — and a query using them is still portable JQL.
+
+## Proving a filter before it meets anybody
+
+The language ships its own test suite as **data**: `conformance/cases.json`, 156 matching
+cases and 27 request cases. Each is a document set, a query, and the answer any implementation
+must give.
+
+```json
+{"group": "equality", "name": "an empty query matches everything", "documents": "people", "query": {}, "matches": [0, 1, 2, 3]}
+```
+
+You need it mostly if you implement JQL in another language. But it is also the clearest
+statement of what an operator means, in twelve groups — equality, arrays and paths, existence
+and type, ordering, strings, logic, text, references, length, glob, relative dates, refusals.
+When you are unsure what something does, the case is faster to read than the prose.
+
+For your *own* filters, the tools are ones you already have:
+
+| | |
+| --- | --- |
+| `validate` | a query from outside, refused with a sentence (lesson 12) |
+| `explain` | why one row did or did not match (lesson 9) |
+| `jql --explain` | the same from a shell, over the first line of a real file (lesson 14) |
+| `fingerprint` | whether the filter in the test is the filter in production (lesson 13) |
+| `toText(…).complete` | whether the box is showing the whole filter (lesson 11) |
+
+## Harbour, finished
+
+Everything the course built, in one place:
+
+```ts
+// vocabulary.mjs — the names, once, for both front ends            (lesson 10)
+export const ORDERS = defineVocabulary()({ fields: { … }, text: [ … ] });
+
+// the console's search box                                        (lesson 11)
+const query = parseText(typed, { vocabulary: ORDERS });
+
+// the table                                                       (lessons 7, 15)
+const { pushed, remaining, complete } = plan(query, STORE_CAPABILITIES);
+const rows = await collection.find(toStoreFilter(pushed)).toArray();
+const page = search(complete ? rows : filter(rows, remaining), {
+  sort: { placed: -1 }, skip, limit, omit: ["customer.email"],
+}, { vocabulary: ORDERS });
+
+// the number above it                                             (lesson 8)
+const byStatus = group(rows, "status", { vocabulary: ORDERS, where: query });
+
+// "why isn't this here?"                                          (lesson 9)
+const why = explain(query, row, { vocabulary: ORDERS });
+
+// saving it                                                       (lesson 13)
+await filters.insert({ key: fingerprint(query), name, query: canonical(query) });
+
+// and the public API, which trusts none of the above              (lesson 12)
+const checked = validate(JSON.parse(body), { vocabulary: PUBLIC, limits });
+if (!checked.valid) return respond(400, { error: checked.error.message });
+```
+
+One query document runs in the console, in the API, in the store and in the nightly export,
+and means the same thing in all four. That is the whole argument for a query being data.
+
+## Where to go next
+
+| | |
+| --- | --- |
+| [The specification](../reference/specification.md) | what every operator means, precisely — the thing to read when you disagree with an answer |
+| [Adopting JQL in a project](../guides/adopting.md) | moving an existing project's filtering onto it |
+| [Pushing a query into a store](../guides/pushdown.md) | writing a target for a store of your own |
+| [Design decisions](../design/decisions.md) | what this library refuses to do, and what that costs |
+| [Performance](../design/performance.md) | how fast it is, how that is measured, and what makes it so |
+
+## A last exercise
+
+Take the filter your own project uses most — the one behind a dashboard or an endpoint — and
+write it as a JQL document. Two things usually come out of that:
+
+1. a clause you cannot express, which is worth knowing about; and
+2. a clause you *can* express that you had been doing in application code, which is worth
+   moving.
+
+If it is the first, the [specification](../reference/specification.md) will tell you whether
+it is a gap in the language or a gap in this course. If it is the second, you have just made a
+filter storable, sendable and explainable — which is what the whole thing is for.
+
+## Related
+
+- [Course index](index.md) — all sixteen lessons
+- [Library API](../reference/api.md) — every export, grouped by what it is for

package/docs/course/index.md

@@ -0,0 +1,185 @@
+# The JQL course
+
+Sixteen lessons that build one real integration, from a first query to a filter you can put
+behind a public endpoint.
+
+← [Documentation](../index.md)
+
+---
+
+## What this is
+
+The [reference documentation](../index.md) answers *"how does X work?"*. This answers *"what
+do I do, and in what order?"* — every capability of the library, taught in the order that
+makes each one make sense, with something to run at every step.
+
+It is written to be worked through rather than read. Every lesson is a handful of short,
+self-contained programs, each followed by what it prints — and **every one of those outputs
+was produced by running the code**, not by imagining what it would print. A script in this
+repository runs all of them on the packed package before a release, so a page that drifts
+from the library fails the build.
+
+**Time:** about three hours to do properly. Lessons 1–5 are the language itself and are worth
+slowing down for; everything after them assumes you have those.
+
+## Who it is for
+
+A TypeScript or JavaScript developer with a collection of things and a filter to write — rows
+in a dashboard, records behind an API, lines in a log. You need no background in query
+languages: the operator names are the conventional ones, so if you have written a filter in
+almost any document store you will recognise most of them, and
+[the specification](../reference/specification.md) says precisely what each one means here.
+
+## The running example
+
+You are building **Harbour**, the order desk of a small shop. It has an order book worth
+searching, a support console worth giving a search box, and an API worth not letting strangers
+run arbitrary queries against. Every lesson adds one thing to Harbour, and by lesson 16 you
+have a complete, tested, production-shaped setup.
+
+## Set up once
+
+```bash
+mkdir harbour && cd harbour
+npm init -y && npm pkg set type=module
+npm install @osqd/jql
+```
+
+Then save the order book as `harbour/orders.mjs`. Every lesson imports it, and it is small
+enough that you can check any answer by hand:
+
+```js
+/** The Harbour order book: eight orders, small enough to check an answer by hand. */
+export const orders = [
+  {
+    id: "o-1001", placed: "2026-09-01T09:15:00Z", status: "paid", channel: "web",
+    customer: { name: "Ada Lovelace", country: "GB", email: "ada@example.com" },
+    lines: [{ sku: "pen-fine", title: "Fine liner", quantity: 3, price: 4.5 }, { sku: "ink-blue", title: "Blue ink", quantity: 1, price: 9 }],
+    total: 22.5, paid: 22.5, tags: ["gift"], note: "leave with the neighbour",
+  },
+  {
+    id: "o-1002", placed: "2026-09-03T14:02:00Z", status: "open", channel: "web",
+    customer: { name: "Grace Hopper", country: "US", email: "grace@example.com" },
+    lines: [{ sku: "pad-a5", title: "A5 pad", quantity: 10, price: 3 }],
+    total: 30, paid: 0, tags: [],
+  },
+  {
+    id: "o-1003", placed: "2026-09-07T08:40:00Z", status: "paid", channel: "phone",
+    customer: { name: "Alan Turing", country: "GB", email: "alan@example.com" },
+    lines: [{ sku: "pen-fine", title: "Fine liner", quantity: 1, price: 4.5 }],
+    total: 4.5, paid: 4.5, tags: ["repeat"], note: "same as last time",
+  },
+  {
+    id: "o-1004", placed: "2026-09-11T19:30:00Z", status: "refunded", channel: "web",
+    customer: { name: "Katherine Johnson", country: "US", email: "kj@example.com" },
+    lines: [{ sku: "ink-blue", title: "Blue ink", quantity: 2, price: 9 }, { sku: "ink-red", title: "Red ink", quantity: 2, price: 9 }],
+    total: 36, paid: 0, tags: ["damaged", "repeat"], note: "arrived leaking",
+  },
+  {
+    id: "o-1005", placed: "2026-09-14T11:05:00Z", status: "open", channel: "app",
+    customer: { name: "Tim Berners-Lee", country: "GB", email: "tim@example.com" },
+    lines: [{ sku: "desk-lamp", title: "Desk lamp", quantity: 1, price: 140 }, { sku: "pad-a5", title: "A5 pad", quantity: 10, price: 3 }],
+    total: 170, paid: 0, tags: ["fragile"],
+  },
+  {
+    id: "o-1006", placed: "2026-09-18T16:45:00Z", status: "paid", channel: "app",
+    customer: { name: "Barbara Liskov", country: "US", email: "barbara@example.com" },
+    lines: [{ sku: "pad-a5", title: "A5 pad", quantity: 2, price: 3 }, { sku: "pen-fine", title: "Fine liner", quantity: 6, price: 4.5 }],
+    total: 33, paid: 33, tags: [], note: "gift wrap, no receipt",
+  },
+  {
+    id: "o-1007", placed: "2026-09-21T07:20:00Z", status: "cancelled", channel: "web",
+    customer: { name: "Margaret Hamilton", country: "DE", email: "margaret@example.com" },
+    lines: [{ sku: "desk-lamp", title: "Desk lamp", quantity: 2, price: 140 }],
+    total: 280, paid: 0, tags: ["fragile"], note: null,
+  },
+  {
+    id: "o-1008", placed: "2026-09-24T13:10:00Z", status: "paid", channel: "phone",
+    customer: { name: "Ada Byron", country: "FR", email: "ada.b@example.com" },
+    lines: [{ sku: "ink-red", title: "Red ink", quantity: 1, price: 9 }, { sku: "pad-a5", title: "A5 pad", quantity: 1, price: 3 }],
+    total: 12, paid: 12, tags: ["repeat"],
+  },
+];
+```
+
+Look at it for a moment before you start. Three orders have no `note` at all, one has a `note`
+of `null`, two have no tags, and one has two lines that are nothing like each other. Every one
+of those is there to catch a lesson out.
+
+Each example is a whole program: put it in a file next to `orders.mjs` and run it with
+`node`. A few lessons introduce a second module — a vocabulary, a store description — and say
+so where they do. Lesson 6 is the one that wants TypeScript; nothing here needs a server or a
+database at all.
+
+---
+
+## Part 1 — The language
+
+| | | |
+|-|-|-|
+| 1 | [Your first query](01-first-query.md) | A query is data. Four helpers, and a refusal. |
+| 2 | [Asking precisely](02-operators.md) | Comparison, membership, existence, strings, patterns. |
+| 3 | [Arrays and paths](03-arrays-and-paths.md) | How a path meets an array. **The most important lesson here.** |
+| 4 | [Combining and negating](04-combining.md) | `$or`, `$nor`, `$not` — and what "not" means over a list. |
+| 5 | [Dates and windows](05-dates.md) | An instant in JSON, and a window that stays true tomorrow. |
+
+## Part 2 — Letting the compiler help
+
+| | | |
+|-|-|-|
+| 6 | [Typed queries](06-typed-queries.md) | A typo in a field name as a compile error rather than an empty result. |
+
+## Part 3 — Whole questions about a collection
+
+| | | |
+|-|-|-|
+| 7 | [Requests](07-requests.md) | Order, pages, and which fields you hand back. |
+| 8 | [Counting by a field](08-grouping.md) | The number above the table. |
+| 9 | [Why did this not match?](09-explaining.md) | The clause that decided it, with the values it read. |
+
+## Part 4 — People typing
+
+| | | |
+|-|-|-|
+| 10 | [A vocabulary](10-vocabulary.md) | The names your data has, in one place, for both front ends. |
+| 11 | [The search box](11-the-search-box.md) | Text into JQL, JQL back into text, and completions. |
+
+## Part 5 — Production
+
+| | | |
+|-|-|-|
+| 12 | [Queries from outside](12-untrusted.md) | Accepting one from a URL without accepting everything. |
+| 13 | [Saved filters](13-saved-filters.md) | One shape and one short name per question. |
+| 14 | [Logs and streams](14-streams-and-cli.md) | The async helpers, and the `jql` command. |
+| 15 | [Pushing into a store](15-pushdown.md) | Letting a backend answer the part it can. |
+| 16 | [Extending it, and proving it](16-extending.md) | Operators of your own, the conformance suite, and a finished Harbour. |
+
+---
+
+## How to get the most out of it
+
+**Type the code, do not paste it.** The examples are short on purpose.
+
+**Predict the answer before you run it.** Eight orders is few enough to work out in your head,
+and the times you are wrong are the times you learn where this language differs from the one
+in your head.
+
+**When something surprises you, chase it.** Every lesson ends with links into the reference
+documentation and the specification for the thing you just used.
+
+## One sentence to keep
+
+> **A query that is not understood is refused, never run as something that looks like it
+> worked.**
+
+You will meet it in lesson 1, thirty seconds in, when a misspelt operator throws instead of
+quietly matching nothing. Every other refusal in this course is that same rule: the failure
+this language exists to prevent is a filter that looks applied and is not.
+
+Start with [lesson 1](01-first-query.md).
+
+## Related
+
+- [Quick start](../start/quick-start.md) — if you want five minutes rather than three hours
+- [The specification](../reference/specification.md) — what every operator means, precisely
+- [Library API](../reference/api.md) — every export, grouped by what it is for