@malloydata/malloyyo 0.2.78 → 0.2.80

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/index.js +828 -799
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ import { dirname, join } from "node:path";
11
11
  import { fileURLToPath } from "node:url";
12
12
 
13
13
  // package.json
14
- var version = "0.2.78";
14
+ var version = "0.2.80";
15
15
 
16
16
  // src/update-check.ts
17
17
  var UPDATE_CHECK_ARGV = "__update-check";
@@ -307,46 +307,14 @@ import { execFileSync } from "node:child_process";
307
307
  import fs4 from "node:fs";
308
308
  import path5 from "node:path";
309
309
 
310
- // ../mcp-engine/dist/index.js
311
- import {
312
- MalloyError,
313
- expressionIsAggregate,
314
- expressionIsAnalytic
315
- } from "@malloydata/malloy";
316
- import { prettify as internalPrettify } from "@malloydata/malloy/internal";
317
- import { API, MalloyError as MalloyError2 } from "@malloydata/malloy";
318
- import { tagFromAnnotations } from "@malloydata/malloy";
319
- import { MalloyError as MalloyError3 } from "@malloydata/malloy";
320
- import path from "node:path";
321
- import url from "node:url";
322
- var HOST_ONLY = "host_only";
310
+ // ../mcp-engine/dist/chunk-2MGIQR2M.js
323
311
  var contentFiles = {
324
- "authoring/start.md": "---\ndescription: Start here when authoring in a clone of a model repo (Claude Code on the web) \u2014 the setup checks, then the edit \u2192 preview_changes \u2192 propose loop\n---\n\n# Authoring a model repo from a clone\n\nYou're in a session with a clone of a model repo, such as Claude Code on the\nweb, and this instance's connector. Edit files in the clone. This instance\ncompiles your edits with its own warehouse connections and shows them, with\nreal data and dashboards, before anything is pushed. Git is only for proposing\nthe finished change.\n\n## First: check the setup\n\nDo these in order. If one fails, tell the person exactly what's wrong and stop.\n\n1. **The tools.** You need `preview_changes`, `list_repos` and `check_repo`. If\n they're missing, either the person isn't an admin on this instance or the\n connector isn't turned on for this session. Say both possibilities.\n2. **The repo.** Run `git remote get-url origin`. `list_repos` must list a repo\n whose `github` is that `owner/name`. If none does, the instance doesn't\n publish this repo, and an admin has to add it.\n3. **The round trip.** Call `preview_changes` with no files:\n - `repo`: the remote, as printed\n - `label`: `git branch --show-current`\n - `base`: `git merge-base HEAD origin/<published branch>`. `list_repos` names\n the published branch, usually `main`.\n\n Every dataset should come back `ok`. If one doesn't, it's broken on the\n published branch too. Say so before you change anything.\n\nThen tell the person it works and ask what they want, unless they already said.\n\n## The loop\n\n1. **Branch.** Work on a branch named for the task, e.g. `claude/returns`.\n Never commit to the published branch.\n2. **Look before writing.**\n - For a new dataset, read the data first with `list_tables` and\n `describe_table`, and ask the person what it should answer.\n - For a change, read the model and the dashboards in the clone.\n `dashboards/*.malloy` and their components exist only here, not in this\n instance's tools.\n3. **Edit, then `preview_changes`.** Send only what differs from `base`:\n - `files`: the full text of each file in `git diff --name-only --diff-filter=d <base>`\n (changed or added; `d` leaves out deletions), plus\n untracked files (`git ls-files --others --exclude-standard`).\n - `deleted`: files removed since `base` (`git diff --name-only --diff-filter=D <base>`).\n - Committed or not doesn't matter. The preview is your working copy.\n4. **Read the answer.** Each dataset is either `ok`, with sources and\n dashboards, or `FAILED` with the compile error. Fix it and preview again.\n5. **Check the numbers.** Use `query` and `describe_source` with the preview\n address as `model_ref`, e.g. `malloyyo_test@claude/returns:returns`. Do the\n work in Malloy, not by post-processing rows.\n6. **Show the person.** Give them the dashboard links from the answer. The pages\n are previews: only admins see them, and nothing is published.\n7. Repeat. Each `preview_changes` replaces what that label's addresses show.\n\n## Adding a dataset\n\n- **Check the repo's layout first.** `list_repos` says it in `addingDatasets`.\n A repo with `datasets/<name>/` directories takes a new one directly. A\n single-dataset repo (`index.malloy` at its root) needs restructuring first;\n `yo_help(\"repo/datasets\")` covers that, and it's a separate change to agree\n with the person.\n- **Look at the data.** Use `list_tables(repo, connection)` with a connection\n from `list_repos`; narrow it with `schema` or `like`, and on BigQuery\n `schema` (the dataset) is required. Then `describe_table` for each table\n that matters: columns, row count and five rows. On DuckDB, a \"table\" can be\n a file path or URL (Parquet, CSV, JSON).\n- **Ask before modeling.** Find out what the person wants to answer: the main\n entities, what one row of each table is, how the tables join, and the few\n measures that matter. A model built from their questions beats one copied\n from the schema.\n- **Write `datasets/<name>/index.malloy`.** The directory names the dataset,\n so make it a short lowercase slug. Use the connection names from\n `list_repos`, e.g. `source: orders is warehouse.table('sales.orders') extend { \u2026 }`.\n Give each source a `#\"` description, and each measure one too; they're what\n people read in `describe_source`.\n- **Stay in your lane.** Don't touch other datasets or `malloy-config.json`\n unless the person asked. A connection or credential that doesn't exist yet is\n an admin's job, outside this change.\n- **It's created at publish.** Until then, the new dataset exists only in\n previews (`status: \"new\"`).\n\n## Proposing it\n\nWhen the person is happy with it:\n\n1. Commit with messages that say why, then push the branch.\n2. Open a pull request, saying what changed and including a sample result.\n3. `check_repo(repo, pull_request: <number>)`. This checks what merging would\n produce. A green preview doesn't cover changes others made to the published\n branch since you started.\n4. **Merging is the person's decision.** Ask first, even if you can merge.\n5. After the merge, `publish_repo(repo)`, unless the repo publishes on push. New\n datasets are created then.\n\n## Good to know\n\n- **Limits.** One preview carries up to 200 changed files and 512KB. Beyond\n that, push the branch and use `fetch_branch(repo, branch)`, which reads it\n from GitHub.\n- **`base` must be on GitHub.** The merge-base with the published branch always\n is. If you rebased onto newer work, recompute it.\n- **Malloy syntax.** `#\"` is a description, a line starting with `#` is an\n annotation (not a comment), and `//` is a comment.\n- **Drafts.** Dashboards someone made in chat are drafts. Promoting one into\n the repo is in `yo_help(\"dashboards/drafts\")`.\n- **Branch previews** in more depth are in `yo_help(\"repo/branches\")`.\n- **A repo that isn't on GitHub** was published with the CLI. There's no clone\n to author in, so it can't be changed this way.\n",
325
- "dashboards/authoring.md": '---\ndescription: How to author a dashboard \u2014 a self-contained file in the dashboards/ directory that defines its own query; the entry point for dashboard how-to\n---\n\n# Authoring dashboards\n\nA dashboard is a **self-contained `.malloy` file in the `dashboards/`\ndirectory**. The file IS the dashboard: it imports the model parts it needs,\ndefines its query (with the filtering it applies), and tags it. No manifest, and\nfor the basic case no JavaScript. Preview with `malloyyo dashboard dev`; check\nwith `malloyyo lint`. Requires `@malloydata/malloy` 0.0.423+.\n\nRelated: `yo_help dashboards/givens-and-controls` (filter controls),\n`dashboards/grid-layout` (columns/colspan/break), `dashboards/charts` (the\n`# bar_chart`/`# line_chart` tags and their channel rules),\n`dashboards/custom-components` (a flat `<name>.jsx`), `dashboards/vega-charts`\n(`<VegaChart>`).\n\n> **Need a chart the `# bar_chart`/`# line_chart`/`# shape_map` tags can\'t do?**\n> Use the `<VegaChart>` COMPONENT (a Vega-Lite spec over query rows) \u2014 NOT a `#`\n> tag; there is no `# vega_lite`. See `yo_help dashboards/vega-charts`.\n\n## The layout\n\n```\nmodel/\n ecommerce.malloy # sources, reusable views/measures, # drill tags\n givens.malloy # given: declarations (the filter controls)\n index.malloy # imports/exports sources \u2014 the MCP/data surface ONLY\n dashboards/\n overview.malloy # one dashboard; the FILENAME is its name/slug\n overview.jsx # optional custom component for overview\n```\n\n**The filename is the dashboard\'s name** \u2014 its URL slug, its `# drill` target,\nand the basename of its optional component. Discovery globs\n`dashboards/*.malloy` and compiles EACH as its own entry \u2014 so dashboards are NOT\ndeclared in, or exported through, `index.malloy` (`index.malloy` is just the\n`query`/`describe_source` data surface).\n\n## Preferred: put the query IN the dashboard file\n\nDefine the query right in `dashboards/<name>.malloy` and tag it `# artifact`, so\nthe given mapping (the `where: \u2026 ~ $GIVEN`) is visible next to the dashboard:\n\n```malloy\n// dashboards/overview.malloy\n##! experimental.givens\nimport "../ecommerce.malloy" // BARE import: source + givens in scope\n\n#" Business health at a glance \u2014 sales, margin, orders.\n# artifact { title="Business Overview" } dashboard {columns=6}\nquery: overview is order_items -> {\n where: // the given mapping, HERE\n inventory_items.product_brand ~ $BRAND, // multi-filter where: is\n inventory_items.product_category ~ $CATEGORY, // COMMA separated\n created_at ~ $PERIOD\n # colspan=2\n aggregate: total_sales, total_gross_margin, order_count\n # colspan=3\n nest:\n # line_chart\n sales_trend is by_month\n top_brands\n # shape_map\n sales_by_state\n}\n```\n\nThat\'s a complete dashboard: the runtime auto-renders a title (the tag\'s\n`title`, else the `#"` doc), a control for every given the query references, and\nthe result panel. `# artifact` DECLARES the dashboard; `# dashboard {columns=6}`\nis the renderer tag that draws it as KPI tiles + a card grid \u2014 partners, on the\nsame line. Grid rules: `yo_help dashboards/grid-layout`.\n\n**You know you\'re doing it right when the `where: foo ~ $FOO` is in the DASHBOARD\nfile, not the model.** Keep the model\'s sources/views reusable and given-free;\neach dashboard decides its own filtering.\n\n**The bare import is required for controls.** A control renders only when the\ngiven\'s DECLARATION is in the dashboard file\'s scope \u2014 a bare\n`import "../ecommerce.malloy"` (or `import "../givens.malloy"`) brings them all;\nthe runtime shows a control for exactly the givens the query references. A\nselective `import { order_items } from \u2026` brings the filter but NOT the control.\n\nKeep the FILENAME as the name \u2014 don\'t set `name=`, so the URL, the\n`# drill { to=\u2026 }`, and the component basename all agree (one source of truth).\n\n## Other forms\n\n- **A view of a source you extend in the file** \u2014 tag the dashboard `view:` with\n `# artifact` (runs as `<source> -> <view>`). Good when the dashboard needs\n helper views defined alongside it.\n- **Compose existing views**: a model-level `## artifact { tiles=["a -> b", "c -> d"]\n dashboard_columns=6 }` (`##`, ONE line) names several views. Each tile runs as\n its own query (in parallel), and the results are combined into ONE\n `# dashboard` that Malloy\'s dashboard renderer lays out \u2014 so it looks exactly\n like the equivalent single-query dashboard: `dashboard_columns=N` sets the grid\n and `# colspan=N` / `# break` on the tile VIEWS place them. A tile that returns\n a SINGLE ROW with no group-by (an aggregate view) is merged in as top-level KPI\n tiles rather than a card (its `# colspan` is spread across those KPIs). The\n dashboard paints once the tiles are ready, with a single early paint if one tile\n straggles so a slow tile can\'t hold up the rest. Use for multi-tile /\n cross-source; prefer the inline query whenever a dashboard has its own filtering.\n- A `dashboards/*.malloy` with NO `# artifact`/`## artifact` is a shared INCLUDE\n (skipped by discovery) \u2014 put helper sources/views there for several dashboards\n to import.\n\n## Givens (filter controls)\n\nDeclare givens as `filter<T>` in the MODEL (`givens.malloy` or the source file) \u2014\nthey\'re shared and used by the MCP surface too; each dashboard APPLIES them in\nits `where:`. Full control reference: `yo_help dashboards/givens-and-controls`.\nPer-dashboard starting values go in the tag:\n\n```malloy\n# artifact { title="Ford recalls" givens { MANUFACTURER=f\'Ford Motor Company\' } }\n```\n\n## Drill from a dimension\n\n`# drill` on a source `dimension:` (in the model) makes its cells clickable \u2014\nopening another dashboard (seeding the value) or filtering in place:\n\n```malloy\ndimension:\n # drill { to=[category_explorer, self] }\n category is inventory_items.product_category\n```\n\n`to` is a list; each is a **dashboard slug** (a `dashboards/<slug>.malloy`\nfilename) \u2192 opens it, seeding the value into the given named like the dimension\nUPPER-cased (`category` \u2192 `CATEGORY`), or **`self`** \u2192 filter the current\ndashboard in place. Add `given=` when the target given differs. `lint` VERIFIES\nevery `to=` slug resolves to a real dashboard file (a typo/renamed dashboard\nfails loudly, not at click time).\n\n> **malloy#2979 (fixed in 0.0.423):** a `# drill` on a bare `group_by: name` was\n> dropped when nested through `+ {\u2026}`. Put it on the source `dimension:`, or use\n> `group_by: name is concat(name,\'\')`.\n\n## Custom component (optional)\n\nFor bespoke layout/charts, add a flat sibling `dashboards/<name>.jsx` (or\n`.tsx`). Only React + `@malloyyo/dashboard` importable (sandboxed). A bare\n`<Panel/>` renders the whole dashboard; a `<Panel query="\u2026"/>` /\n`<VegaChart query="\u2026"/>` runs a query DEFINED in this dashboard file (by name) or\na `source -> view`. `lint` checks each `query="\u2026"` still resolves. See `yo_help\ndashboards/custom-components`.\n\n## Rules\n- Each dashboard is one `dashboards/<name>.malloy`; the filename is the slug.\n Prefer the inline `query: \u2026 # artifact` form \u2014 the `where: ~ $GIVEN` lives in\n the dashboard file.\n- Bare-import the model (and/or `givens.malloy`) so the controls render.\n- Givens are `filter<T>` declared in the model; options come from `# suggest {\u2026}`;\n interactivity = setting given values, not rewriting query text.\n- `index.malloy` is the data surface, NOT where dashboards live.\n- If a query/given you need is missing, add it (check with `describe_source`).\n\n## Preview & validate\n`malloyyo dashboard dev` \u2192 open the URL; `.malloy`/`.jsx` edits hot-reload.\n`malloyyo lint` checks each dashboard file on its own: it compiles as its entry;\neach tile/query and `# suggest` compiles; `dashboard_columns` is a positive int;\nthe component compiles and its `query="\u2026"` resolve; no duplicate names, no\norphaned component; every `# drill { to=\u2026 }` resolves. Tight loop: the local\n`malloyyo mcp --develop` server hot-reloads edits \u2014 `query(execute:false)` to\ncompile-check, `execute:true` to run. Don\'t validate against a hosted/claude.ai\nconnector \u2014 it serves the PUBLISHED model (stale until `malloyyo publish`).\n',
326
- "dashboards/charts.md": "# Charts (`# bar_chart`, `# line_chart`, \u2026)\n\nThe renderer's built-in chart tags cover most dashboard tiles. Tag a nested view\nand it draws:\n\n```malloy\nnest:\n # bar_chart\n sales_by_brand\n # line_chart\n sales_by_month\n```\n\nRelated: `yo_help dashboards/grid-layout` (where tiles sit),\n`dashboards/vega-charts` (`<VegaChart>`, for shapes these tags can't express),\n`dashboards/authoring` (the dashboard file itself).\n\n## Channels: name them, don't leave them to be guessed\n\nA chart has three channels \u2014 **x** (the category axis), **y** (the value), and\n**series** (the colour split). Set them on the tag:\n\n```malloy\n# bar_chart { x=weekday y=drunk }\n# bar_chart { x=nickname y=flight_count series=destination }\n# line_chart { x=sale_date y=['sales', 'cost'] }\n```\n\nLeft unset, the renderer infers them: x prefers a time dimension and otherwise\ntakes the first dimension, y takes the first aggregate, and **series takes any\ndimension left over**. That last rule is the one that surprises people \u2014 see\nbelow. Naming `x` and `y` explicitly costs one line and removes the guesswork.\n\nOther properties: `.stack`, `.size` (`spark`/`xs`/`sm`/`md`/`lg`/`xl`/`2xl`, or\n`size.width` / `size.height`), `.x.limit`, `.series.limit`, and `.independent`\non any channel for nested charts.\n\n## THE RULE: charts count DIMENSIONS, not columns\n\nA chart can carry **one x dimension and one series dimension**. The renderer\ncounts the *dimensions* in the result (`group_by` fields \u2014 not aggregates) and:\n\n- **two dimensions, only `x` named** \u2192 the spare one is promoted to a colour\n series, whether or not you wanted a legend\n- **three or more dimensions, none tagged `series`** \u2192 it refuses:\n *\"Too many dimensions. A bar chart can have at most 2 dimensions: 1 for the x\n axis, and 1 for the series. To use 3+ dimensions, explicitly tag multiple\n fields as series.\"*\n\nThat last sentence is the escape hatch: 3+ dimensions is legal if you say which\nones are the series. What is NOT legal is leaving it to be inferred. If you\ngenuinely want a third dimension in the picture, name it; if you don't, the\nproblem is that a field you didn't think of as a dimension is one.\n\nAggregates are exempt. A result can carry as many measures as you like \u2014 only\nthe ones named in `y` (or the first, if `y` is unset) get plotted, and the rest\nare ignored rather than turned into channels.\n\n**`# hidden` does not exempt a dimension from this count.** It hides a field in\ntables, `big_value` comparisons and `# link` targets; it has no effect on chart\nchannel assignment. A `# hidden` group_by is still a dimension and will still\nbecome a series.\n\n## Sorting a named axis (the common case this rule makes hard)\n\nYou want an axis labelled `Sunday \u2026 Saturday`, or `Jan \u2026 Dec`, in *that* order \u2014\nnot alphabetical. The label has to be a string, but the sort key is a number, and\nthe naive fixes both fail:\n\n```malloy\n// WRONG \u2014 two dimensions: weekday_num becomes a colour series.\ngroup_by:\n # hidden\n weekday_num is day_of_week(exit_date)\n weekday is pick 'Sunday' when day_of_week(exit_date) = 1 \u2026\n```\n\n```malloy\n// ALSO WRONG \u2014 a `select:` stage is a projection, so it has no measures:\n// every column becomes a dimension and a 3-column result is rejected.\n} -> {\n select: weekday is pick 'Sunday' when weekday_num = 1 \u2026 , drunk, avg_price\n}\n```\n\n**Make the sort key a MEASURE.** Measures aren't dimensions, so a sort key\nexpressed as one can never be promoted to a channel:\n\n```malloy\n# bar_chart { x=weekday y=drunk }\nview: by_weekday is {\n group_by: weekday is\n pick 'Sunday' when day_of_week(exit_date) = 1\n pick 'Monday' when day_of_week(exit_date) = 2\n \u2026\n else 'Saturday'\n aggregate:\n drunk\n weekday_sort is min(day_of_week(exit_date)) // orders rows; never a channel\n order_by: weekday_sort asc\n}\n```\n\nOne dimension reaches the chart, the rows arrive in the order you asked for, and\na bar chart preserves query row order for a categorical axis. The same shape\nworks for months (`min(month(date))`), fiscal periods, size buckets, and any\nother \"display a name, sort by a number\" axis.\n\n> `min()` because a sort key needs *some* aggregate function and every row in the\n> group shares the value; `max()` is equally fine.\n\n## Deciding which tile is a chart at all\n\n- **Ranked categories** (top brands, regions by volume) \u2014 `# bar_chart`, ordered\n by the measure. Query order is the bar order.\n- **A value over time** \u2014 `# line_chart` with the time dimension as `x`.\n- **A wide detail table** \u2014 no chart tag. Charting eight columns is worse than\n showing them; give the tile `# colspan=6` instead and label the columns.\n- **Flat data** \u2014 if every bar is within a few percent of the others, the chart\n is saying \"no pattern here\" at the cost of a card. Consider whether the tile\n earns its place.\n\n## Trends by period: drop the incomplete one\n\nA by-year or by-month trend whose final period is partial draws a cliff that\nreads as collapse. Filter to complete periods, using a cutoff that comes from\nthe DATA (e.g. a snapshot/max-date column carried on a joined dimension), not\nfrom the result set \u2014 deriving it from the visible rows will wrongly declare a\nperiod partial as soon as a filter narrows the data.\n\n## Validate\n\n`malloyyo lint` compiles each dashboard and its tiles, but it does not render\nthem \u2014 a chart that compiles can still throw \"Too many dimensions\" in the\nbrowser. See it with `malloyyo dashboard dev`, which runs the queries\nserver-side and renders the real result.\n",
327
- "dashboards/custom-components.md": '---\ndescription: Custom dashboard UI \u2014 a flat dashboards/<name>.jsx|tsx sibling composing @malloyyo/dashboard widgets/hooks/helpers with your own React\n---\n\n# Custom dashboard components (`dashboards/<name>.jsx`)\n\nThe default UI (auto-rendered controls + panel) covers most dashboards. When it\nisn\'t enough, add ONE file \u2014 a **flat sibling** `dashboards/<name>.jsx` (or\n`.tsx`) next to the dashboard\'s `dashboards/<name>.malloy` (same basename) \u2014 that\ncomposes the runtime\'s widgets/hooks with your own React. You own layout, copy,\nand theming; the `.malloy` file still owns every query and filter. See also\n`yo_help dashboards/authoring` and `dashboards/vega-charts`.\n\n```tsx\nimport React from "react";\nimport { Controls, Given, Search, Select, TimeRange, Panel, filters, useGiven } from "@malloyyo/dashboard";\n\nexport default function Dashboard({ dashboard, givens }) {\n return (\n <div style={{ maxWidth: 860, margin: "0 auto", padding: 24 }}>\n <h1>{dashboard.title}</h1>\n <Controls>\n <Given name="STATE" /> {/* picks the control from the declaration */}\n <Search given="NAME" /> {/* committing input + typeahead + validation */}\n <TimeRange given="PERIOD" presets={[\n { value: "", text: "All time" },\n { value: filters.lastN(1, "day"), text: "Last day" },\n { value: filters.lastN(1, "week"), text: "Last week" },\n { value: filters.lastN(1, "month"), text: "Last month" },\n ]} /> {/* "Custom range\u2026" is always appended */}\n <Select given="MIN_SAMPLE"\n options={[10, 200, 1000].map(n => ({ value: filters.greaterThan(n), text: `> ${n}` }))} />\n </Controls>\n <Panel givens={givens} /> {/* the dashboard itself (its tiles/query) */}\n <Panel query="baby_names -> births_by_decade" givens={givens} /> {/* a specific query */}\n </div>\n );\n}\n```\n\nFrom `@malloyyo/dashboard` (also handed to the component as props):\n- **Widgets** (headless-ish; restyle via className/style or the `--dash-*` CSS\n vars \u2014 see Theming below): `<Controls/>` (all givens, or compose children;\n grows Apply/Reset under `autorun=false`), `<Given name/>`,\n `<Select given [options]/>`, `<Search given/>` (committing input + typeahead +\n inline \u2715 clear), `<MultiSelect given [options]/>` (chip multi-select for a\n `filter<string>` \u2014 commits an exact-match list via `filters.oneOf`),\n `<Range given [min max]/>`, `<TimeRange given [presets]/>` (temporal presets +\n custom range), `<Checkbox given/>` (bound to a boolean given),\n `<VegaChart spec query|malloy|data givens/>` (a Vega-Lite chart over query\n rows \u2014 see `yo_help dashboards/vega-charts`)\n- **Hooks**: `useGiven(name)` \u2192 {value, set, spec};\n `useOptions(name, typed?)` \u2192 {options, loading} (typeahead);\n `useQuery({query|malloy, givens})` \u2192 {rows, loading, error, truncated} \u2014\n plain rows for your own visuals; `truncated` is null, or {reason, hint}\n when the 5,000-row limit cut the result (aggregate in Malloy, or say so on\n the chart \u2014 `<VegaChart>` and tag-only dashboards already do);\n `useUrlState(key, initial)` \u2192 [value, setValue] \u2014 shareable view-state (below)\n- **Helpers**: `filters.oneOf/contains/between/atLeast/\u2026` build\n filter-expression strings with correct escaping; temporal:\n `filters.lastN(7, "day")` \u2192 `\'7 days\'`, `filters.dateRange("2026-01-01",\n "2026-07-01")`, `filters.afterDate/beforeDate`; read back with\n `filters.values/numberRange/threshold/inLast/temporalRange`;\n `filters.isValid(type, src)` checks typed input.\n Never hand-concatenate a filter string.\n **Escaping rule for custom controls:** a filter given\'s value is an\n EXPRESSION, so committing a raw column value is wrong the moment it contains\n a comma/percent/dash (\'Tesla, Inc.\' parses as two alternatives and matches\n nothing). Commit `filters.oneOf(value)` (exact) or\n `filters.contains(term)` (substring), and unwrap for display with\n `filters.values(src)`. The stock `<Select/>` does this automatically;\n `<Search/>` deliberately commits raw text (its input IS a filter\n expression).\n- `<Panel/>` runs against the DASHBOARD\'s own file: a bare `<Panel/>` renders\n the whole dashboard (its tiles); `<Panel query="\u2026"/>` runs a query defined in\n the dashboard file (by name) or a `source -> view`; `<Panel malloy="\u2026"/>` and\n `runData(text, givens)` run arbitrary Malloy as a RESTRICTED query (no import /\n given: / connection.* / raw SQL / ##! flags \u2014 the model\'s governed surface\n only). `lint` checks each hard-coded `query="\u2026"` still resolves.\n\n## Shareable view-state: `useUrlState`\n\n`useState` is invisible to the page that owns the URL, so a component built on\nit has an address bar that never changes \u2014 the result can\'t be shared or\nbookmarked. **`useUrlState(key, initial)` is a `useState` twin whose value lives\nin the URL**, under a `~key` param:\n\n```jsx\nimport { useUrlState } from "@malloyyo/dashboard";\n\nconst [rack, setRack] = useUrlState("rack", ""); // string\nconst [reuse, setReuse] = useUrlState("reuse", false); // boolean\nconst [board, setBoard] = useUrlState("board", "........"); // string\nconst [topN, setTopN] = useUrlState("n", 20); // number\n```\n\n- Same shape as `useState`: `[value, setValue]`, and `setValue` takes a value\n **or** an updater fn (`setBoard(b => \u2026)`).\n- The value comes from the URL on load, else `initial`. Every change is written\n back (debounced, `replaceState` \u2014 no history spam), so the address bar is\n always a shareable link.\n- Typed by `initial`: string / number / boolean / any JSON-serializable value.\n Strings stay readable in the URL (`~rack=retinas`); objects and arrays are\n JSON. A value equal to `initial` is dropped from the URL, so defaults never\n clutter it, and a malformed value falls back to `initial` instead of throwing.\n- Works identically in `malloyyo dashboard dev`, on a bundled static site, and\n on a hosted instance \u2014 including inside the sandboxed iframe, which cannot\n reach the top-level URL on its own. That\'s why this is a hook and not\n something a component can do with `history.replaceState`.\n\n**Use it for view-state, not query parameters.** A `given:` is the governed,\nfilter-typed query contract: it\'s declared in the model, drives the default\ncontrols, and is visible over MCP \u2014 bind those with `useGiven` and they already\nround-trip through the URL as `$NAME`. `useUrlState` is for everything else a\ncustom component needs to make shareable: a letter rack whose real query inputs\n(allowed letters, min/max length) are computed from it in JS, a board layout, a\nmode toggle. The two namespaces (`$NAME` vs `~key`) never collide.\n\n## Theming\n\nEvery widget is styled by the runtime\'s **default Malloyyo theme** (system\nfont, neutral grays, blue accent, auto light/dark following the viewer\'s OS) \u2014\na bare component looks styled with zero effort, so DON\'T hand-hardcode\n`fontFamily`/colors. The theme is CSS custom properties; override any subset by\nsetting them on a wrapper element (more specific than the runtime\'s `:root`):\n\n```tsx\n<div style={{ "--dash-accent": "#e11d48", "--dash-controls-bg": "#faf5ff" }}>\n <Controls /> \u2026\n</div>\n```\n\nVars: `--dash-font`, `--dash-bg`, `--dash-fg`, `--dash-muted`, `--dash-border`,\n`--dash-accent`, `--dash-accent-fg`, `--dash-control-bg`, `--dash-controls-bg`,\n`--dash-chip-bg`, `--dash-chip-fg`, `--dash-panel-bg`, `--dash-radius`,\n`--dash-danger`. `DefaultDashboard` also takes a `theme={{ accent, controlsBg }}`\nprop (camelCase keys \u2192 `--dash-*`). The results `<Panel>` keeps a light surface\nin both light/dark (the Malloy renderer has no dark theme) \u2014 override\n`--dash-panel-bg` if your renderer output is dark-safe.\n\n**Use `--dash-*` and nothing else.** A custom component renders in its own\n**iframe**, so CSS variables defined by the surrounding page \u2014 including the\nbundled site\'s `--line` / `--card` / `--muted` \u2014 are NOT in scope inside it. A\ncomponent styled against those still renders, but every rule referencing them\nresolves to nothing: borders, dividers and panel backgrounds vanish silently\nwhile text and layout survive, so the page looks *almost* right and the cause\nisn\'t obvious. If you\'re porting CSS that has to work both inside the frame and\non a bundled page, resolve each colour once through the chain and use the alias:\n\n```css\n.my-card {\n --edge: var(--dash-border, var(--line, #e4e6eb));\n --surface: var(--dash-panel-bg, var(--card, #fff));\n border: 1px solid var(--edge);\n background: var(--surface);\n}\n```\n\nThis is a class of bug `lint` cannot see and a screenshot can \u2014 look at custom\ncomponents in `malloyyo dashboard dev` before shipping them.\n\nFor charts beyond the Malloy renderer\'s `#` tags, use `<VegaChart>` \u2014\n`yo_help dashboards/vega-charts`.\n',
328
- "dashboards/drafts.md": "---\ndescription: Writing a draft dashboard from a chat client \u2014 one component file, queries inline, saved with save_draft_dashboard; and how one is promoted into the model repo\n---\n\n# Draft dashboards (`save_draft_dashboard`)\n\nA draft is a dashboard stored on this instance rather than in the model repo.\nIt gets a URL, renders like any other dashboard, and can be re-saved as often\nas you like. Read this before writing one.\n\n## The shape\n\nONE React component, default-exported, whose queries are Malloy written inline:\n\n```tsx\nimport { useQuery } from \"@malloyyo/dashboard\";\n\nexport default function Dashboard() {\n const top = useQuery({\n malloy: `run: flights -> { group_by: carrier; aggregate: flight_count; limit: 10 }`,\n });\n const rows = top.rows ?? [];\n return (\n <div style={{ padding: 24 }}>\n <h1 style={{ fontSize: 22, fontWeight: 600 }}>Top carriers</h1>\n {top.loading ? <p>Loading\u2026</p> : <ol>{rows.map((r) => (\n <li key={String(r.carrier)}>{String(r.carrier)}: {Number(r.flight_count).toLocaleString()}</li>\n ))}</ol>}\n </div>\n );\n}\n```\n\nSave it with `save_draft_dashboard({ dataset, name, title, source })`. The\nresult carries a `url` to open and a `dashboard` name that `show_dashboard`\nrenders. Pass the returned `slug` back on the next save to update the same\ndraft instead of making another.\n\n## The queries\n\nInline Malloy runs against what the model PUBLISHES \u2014 the same rules as the\n`query` tool. You may define your own sources, measures and joins derived from\nthe model's sources. You may not `import`, open a connection, write raw SQL, or\ndeclare `given:`. Check a query with `query(execute:false)` before you put it\nin a component; the save also compiles every literal query it finds and reports\nwhat failed.\n\nWrite the whole query as one template literal. A query built by string\nconcatenation can't be checked at save time and only fails when a reader opens\nthe dashboard.\n\n## What you can import\n\nOnly these resolve:\n\n| Import | What you get |\n|---|---|\n| `react` | React itself, hooks included |\n| `@malloyyo/dashboard` | `useQuery`, `useGiven`, `useOptions`, `useUrlState`, `runData`, `filters`, `VegaChart`, `Field`, and the controls: `Controls`, `Given`, `Select`, `Search`, `MultiSelect`, `Range`, `Checkbox`, `TimeRange` |\n\nNothing else \u2014 no chart library, no icon set, no CSS framework, no `fetch`.\nUse inline `style` objects, plain HTML, and `VegaChart` (see\n`yo_help dashboards/vega-charts`) for charts.\n\n`useQuery` returns `{ rows, result, loading, error, truncated }`. `rows` is\nan array of plain objects, at most 5,000 of them; `truncated` is null, or\n`{ reason, hint }` when that limit cut the result. Aggregate in Malloy rather\nthan plotting a prefix as if it were the whole answer \u2014 `<VegaChart>` notes a\ncut result on the page; anything you draw from `rows` yourself must say so\nitself. Numbers can arrive as BigInt or decimal objects, so wrap them\nwith `Number()` before `.toLocaleString()` or arithmetic, and format dates in\nMalloy rather than in JavaScript.\n\n## Presentation\n\n- One clear page title, then the content. No wrapper card around everything.\n- Put a few headline numbers in a row, value large (~40px) with a small label\n beneath; don't stack them vertically.\n- Give each query-backed section its own loading and error state, so a slow one\n doesn't blank the page.\n- Prefer a table under ~8 categories, where exact values and ranking matter;\n use a chart when shape or trend is the point.\n- Keep charts responsive in width and roughly 200\u2013280px tall.\n- Say what the data shows. Don't call a change strong, concerning or surprising.\n\n## When to add a `.malloy` file instead\n\nPass `malloy` as well when the dashboard needs:\n\n- **filters/controls** \u2014 declare givens in the model and the controls render\n themselves (`yo_help dashboards/givens-and-controls`);\n- **named queries** shared across several tiles, or a composite grid\n (`yo_help dashboards/authoring`);\n- **no code at all** \u2014 a tagged Malloy query renders through Malloy's own\n renderer, which is often the better dashboard.\n\nThat file is `dashboards/<name>.malloy`: it imports `\"../index.malloy\"` and\ntags a query `# artifact`.\n\n## Promotion\n\nA draft lives on the instance; the model repo is where dashboards belong. To\nmove one in, from a checkout of the repo:\n\n```bash\nmalloyyo draft list # find the slug\nmalloyyo draft promote <slug> # writes dashboards/<name>.malloy + component\n```\n\nPromotion writes the files and records what the draft became; it never deletes\nthe draft, whose URL people may already hold. A draft whose queries are inline\nneeds them LIFTED into its `.malloy` as named queries \u2014 the component then uses\n`useQuery({ query: \"<name>\" })` \u2014 because a repo dashboard's queries live in\nthe model, not the component. The written `.malloy` carries them as comments to\nwork from. Then `malloyyo lint`, and the usual PR.\n\n**From a clone, without the CLI** (Claude Code on the web):\n\n1. `get_draft_dashboard(dataset, dashboard)` returns the draft's files.\n2. Write them into the clone as `dashboards/<name>.malloy` plus its component,\n lifting the inline queries as described above.\n3. `preview_changes` to see it compiled and rendered (`yo_help(\"authoring/start\")`).\n4. Commit, then call\n `mark_draft_promoted(dataset, dashboard: \"draft-<slug>\", promoted_as: \"<name>\")`.\n\n`malloyyo draft promote` records the promotion itself.\n\n**What happens to the draft.** Once the dataset publishes the promoted\ndashboard, the draft's URL **redirects** to it, keeping any query string, and\nthe draft drops out of listings. Saved links keep working, and nobody picks the\nstale copy from a menu. Until then the draft serves as before.\n\n## Deleting a draft\n\n`delete_draft_dashboard(dataset, dashboard)`, **Delete draft** on the draft's\npage, or `malloyyo draft delete <slug>`. Its author or an admin can. Its link\nstops working, so ask the person first. A promoted draft that's already\npublished doesn't need deleting, and deleting it ends the redirect.\n\n## Iterating\n\n1. `list_sources`, then `describe_source` for the source you'll query.\n2. Validate each query with `query(execute:false)`.\n3. Save the draft; fix anything the report names.\n4. Show the user the URL (or `show_dashboard`), and ask what to change.\n5. Re-save with the same `slug`.\n",
329
- "dashboards/givens-and-controls.md": "---\ndescription: Dashboard filter controls \u2014 declare filter<T> givens with # label / suggest / control tags; faceted (related) suggestions\n---\n\n# Dashboard givens & controls\n\nOne given is NOT a control: `$MALLOYYO_EMAIL` is filled from the signed-in\nuser, cannot be set by a caller, and renders no filter \u2014 see\n`yo_help language/who-is-asking` for per-user data.\n\nA dashboard's filters are `filter<T>` **givens** declared in the model; the\n`#` tags on each declaration drive its control. This is part of authoring a\ndashboard \u2014 see also `yo_help dashboards/authoring`.\n\n**Declare the filters as `filter<T>` givens** \u2014 never raw strings/numbers.\nA `filter<string>` value accepts one value ('NY'), alternatives ('NY, CA'),\nwildcards ('Ann%'), negation ('-NY'); a `filter<number>` accepts ranges\n('[1910 to 1930]') and comparisons ('> 200'); a `filter<timestamp>` /\n`filter<date>` accepts relative windows ('7 days' = the last 7 days, 'today',\n'last month') and literal ranges ('2026-01-01 to 2026-07-01' \u2014 NO `@` in\nfilter literals). Apply with `~`; `f''` = empty = no filter (the natural\n\"All\"/\"all time\" \u2014 just `col ~ $X`, no `$X = '' or \u2026` dance):\n\n```malloy\n##! experimental { givens }\ngiven:\n # label=\"State\" control=select suggest { source=baby_names dimension=state }\n STATE :: filter<string> is f'NY'\n # label=\"Brand\" suggest { query=brand_suggest dimension=product_brand }\n BRAND :: filter<string> is f''\n # label=\"Names\" control=multiselect suggest { query=name_suggest dimension=name }\n NAMES :: filter<string> is f''\n # label=\"Years\" range_min=1910 range_max=2025\n YEAR_RANGE :: filter<number> is f'[1910 to 1930]'\n # label=\"Time period\"\n PERIOD :: filter<timestamp> is f''\n # label=\"Include rare names\"\n INCLUDE_RARE :: boolean is false\n```\n\nTags on the declaration drive the control (tag syntax is `key=\"value\"` \u2014\nequals, not colon):\n- `label` \u2014 control caption (defaults to the given's name)\n- `suggest { \u2026 }` \u2014 where the control's options come from. NO Malloy code in\n strings \u2014 just names:\n - `suggest { query=brand_suggest dimension=product_brand }` \u2014 the FIRST\n COLUMN of a named query (declare the query in the model \u2014 governed and\n reviewable). PREFER THIS FORM. The query must be in scope where the dashboard\n runs (bring it in with the dashboard file's bare `import`).\n - `suggest { source=baby_names dimension=state }` \u2014 the DISTINCT VALUES of\n a dimension on a source (the source must be in the dashboard's scope)\n A `dimension` (in either form) is what enables SERVER-SIDE TYPEAHEAD: the\n runtime refines the base query with what the user has typed\n (`\u2026 + { where: lower(field) ~ f'll%'; limit: 50 }`, case-insensitive,\n escaped). Without a dimension the fetched list is filtered client-side.\n Runs as a restricted query; lint checks the declaration compiles.\n\n **RELATED (faceted) filters** \u2014 query-form only: a suggest query may\n reference the OTHER givens, and the runtime runs it with the dashboard's\n current values (the suggested given itself is excluded, so the list never\n collapses to the current pick). Brand suggestions narrow when Category is\n set:\n\n ```malloy\n query: brand_suggest is inventory_items -> product_brand + {\n where:\n product_category ~ $CATEGORY, // NOT product_brand ~ $BRAND\n product_department ~ $DEPARTMENT\n limit: 500\n }\n ```\n\n Declare one `*_suggest` per filter, each referencing the others; `f''`\n defaults mean unset filters don't constrain. `source=` suggests can't do\n this (no place for a `where:`) \u2014 another reason to prefer `query=`.\n- `control=select` \u2014 a fixed dropdown instead of a typeahead search box\n- `control=multiselect` \u2014 a tokenized multi-select for a `filter<string>`:\n each pick is a removable chip, the committed value is an exact-match list\n (`Emma, Olivia, Sophia`). Ideal for \"pick several\" filters (names, brands).\n Suggestions come from the given's `suggest {\u2026}` (server-side typeahead when\n it names a dimension). Empty (start from `f''`) = no filter (all).\n- `range_min` / `range_max` \u2014 bounds; makes a filter<number> given a\n dual-thumb range slider\n- anything else passes through in `spec.tags` for custom components\n\nControl picked from the declaration automatically: numeric range tags \u2192\ndual-thumb slider; `filter<timestamp|timestamptz|date>` \u2192 the TimeRange\nwidget (relative presets: Today / Last 7 days / Last 30 days / \u2026 plus a\n\"Custom range\u2026\" from/to date picker); `control=multiselect` \u2192 chip\nmulti-select; suggest + control=select \u2192 dropdown; boolean \u2192 checkbox;\nanything else \u2192 committing search box with typeahead (an inline \u2715 clears it;\na \"Press \u21B5 to apply\" hint shows while the typed draft differs from what's\nrunning \u2014 free text can't safely re-run per keystroke).\nThe suggest-driven options are DATA VALUES only \u2014 options that aren't column\nvalues (custom time presets, threshold buckets) need a custom component\n(`yo_help dashboards/custom-components`) with explicit `{value, text}` options\nwhere value is a filter expression built with `filters.*`.\n\n## When the query re-runs: live (default) vs. Apply\n\nBy default a dashboard is **live** \u2014 every control change re-runs the query\nimmediately (the committing search box is the exception: free text commits on\nEnter/blur, since a half-typed filter is invalid). To batch changes behind an\n**Apply** button instead, set `autorun=false` on the `# artifact` tag:\n\n```malloy\n# artifact { name=\"births-by-name\" title=\"Births by name\" autorun=false }\n```\n\n`autorun=false` makes `<Controls>` grow an Apply/Reset pair \u2014 controls edit a\ndraft and nothing re-runs until Apply. Reach for it when the query is expensive\nor several filters are usually changed together; leave it off (live) otherwise.\n",
330
- "dashboards/grid-layout.md": "---\ndescription: Dashboard grid layout \u2014 # dashboard {columns=N} with # colspan and # break to place KPI tiles and charts\n---\n\n# Dashboard grid layout (`# dashboard {columns=N}`)\n\nBy default a `# dashboard` result flows its KPI tiles and cards and wraps.\nAdd `{columns=N}` to place them on a fixed **N-column grid** instead \u2014 use\n`columns=6`, which divides evenly into 2- and 3-wide cards.\n\n**Key mechanic:** a tag placed ABOVE `aggregate:` or `nest:` applies to EVERY\nitem declared in that block. So you set card widths once per block, not per\nfield.\n\n```malloy\n# artifact { title=\"Customer Insights\" } dashboard {columns=6}\nview: customer_insights is {\n where: created_at ~ $PERIOD\n # colspan=2\n aggregate: total_sales, user_count, order_count, average_order_value\n # colspan=3\n nest:\n # break\n # bar_chart\n users_by_spend_tier\n sales_by_traffic_source\n # shape_map\n sales_by_state\n # colspan=6\n recent_orders // wide detail table \u2192 full width\n}\n```\n\n## The conventions\n\n- **`# colspan=2` above `aggregate:`** \u2014 each KPI / measure tile spans 2 of 6\n columns \u2192 3 tiles per row.\n- **`# colspan=3` above `nest:`** \u2014 each graph or small table spans 3 \u2192 2 per\n row. Per-item render tags (`# line_chart`, `# bar_chart`, `# shape_map`) still\n go on the individual nested items.\n- **`# colspan=6`** \u2014 a single wide / many-column table gets its own full-width\n line. Tag that one item; a per-item `# colspan` overrides the block default.\n- **`# break` on the FIRST nest item** \u2014 starts the graphs on a fresh row, so\n KPI tiles and charts never share one. The renderer splits fields into a new\n grid at each `# break`. Just always add it: it's a no-op when the tiles\n already fill complete rows, and the fix when they don't (e.g. 4 measures\n leave a lone tile a colspan-3 chart would otherwise pack in beside).\n\n`# colspan` only does anything in columns mode \u2014 without `{columns=N}` the\nlayout is free-flow wrap and colspan is ignored. Clamp colspans to `1..N`.\n\nSee also `yo_help dashboards/vega-charts` for custom charts, and the fuller\nauthoring guide surfaced by the local `malloyyo mcp` server.\n",
331
- "dashboards/vega-charts.md": '---\ndescription: Custom dashboard charts with Vega-Lite \u2014 the <VegaChart> component, for charts the # renderer tags can\'t do\n---\n\n# Custom charts with Vega-Lite (`<VegaChart>`)\n\nWhen Malloy\'s renderer tags (`# bar_chart`, `# line_chart`, `# shape_map`, \u2026)\ndon\'t cover the chart you want, a dashboard can draw a **Vega-Lite** spec with\nthe `<VegaChart>` component. The chart engine ships in the dashboard runtime, so\nyou author only a JSON spec + a Malloy query \u2014 no library to load.\n\n**It is a COMPONENT, not a `#` tag.** There is no `# vega_lite` or\n`# scatter_chart` tag. `<VegaChart>` lives in a custom component \u2014 a flat sibling\n`dashboards/<name>.jsx` (or `.tsx`) next to the dashboard\'s\n`dashboards/<name>.malloy` \u2014 a different layer from the `#` renderer tags. (The\ndashboard\'s query is declared in the `.malloy` file; the component only\ncustomizes presentation. Preview with `malloyyo dashboard dev`, validate with\n`malloyyo lint`.)\n\n## The recipe\n\n```tsx\nimport { VegaChart } from "@malloyyo/dashboard";\n\n// Encodings point at the query\'s OUTPUT COLUMN NAMES (here: name, births).\nconst spec = {\n mark: { type: "bar", tooltip: true },\n encoding: {\n y: { field: "name", type: "nominal", sort: "-x" },\n x: { field: "births", type: "quantitative" },\n },\n};\n\nexport default function Dashboard({ givens }) {\n return <VegaChart spec={spec} query="births_by_name" givens={givens} />;\n}\n```\n\nThree ways to feed it data:\n- `<VegaChart spec={spec} query="births_by_name" givens={givens}/>` \u2014 a query\n defined in the dashboard\'s `.malloy` file (by name), or a `source -> view`\n- `<VegaChart spec={spec} malloy="source -> view" givens={givens}/>` \u2014 restricted\n Malloy text (same governance as the explore surface: no import / given: /\n connection.* / raw SQL / ##! flags)\n- `<VegaChart spec={spec} data={rows}/>` \u2014 rows you already have from `useQuery`\n\n## Gotchas (the ones that actually bite)\n\n- **Shape the data in Malloy; return FLAT rows.** Do ranking, share/percent\n (`all(x, dim)`), and label lookups (a `pick` for month names) in the QUERY.\n The spec just encodes columns \u2014 it is not the place to reshape data.\n- **Match column names character-for-character.** Run the query once with\n `query(execute:true)` and read the exact output column names; the spec\'s\n `field` values must match them exactly.\n- **The spec\'s `data` is ignored / any `url` is stripped.** The frame has no\n network \u2014 remote data URLs, transform lookups, and remote `image` marks are\n removed. Adapting a Vega-Lite gallery example = delete its\n `"data": {"url": \u2026}` and repoint the encodings; the query rows are inlined for\n you as the dataset.\n- **Nests come back as arrays.** Flatten to plottable rows in the query, or bind\n a nest to its own chart: `<VegaChart data={row.my_nest}/>`.\n- **Huge integers arrive as strings, on purpose.** Integers serialize as JSON\n numbers, but a value beyond \xB12^53 (a snowflake ID, a 64-bit hash) keeps its\n full precision by staying a string \u2014 JSON has no int64. Bound to a\n `quantitative` or `temporal` channel, Vega-Lite would sort such a column\n lexicographically (`"1","10","11","2"`). If a column can get that big and you\n need to plot it, narrow it in the QUERY \u2014 bucket it, rank it, or emit the\n value you actually want on the axis.\n- **Interactivity = setting given values**, never rewriting query text per\n interaction. Client-side chart interactions (tooltip, zoom, brush) work;\n anything that calls a server does not.\n- **Reads well:** for normalized/share data use a diverging color scale with\n `domainMid` (e.g. `1/12` for month-share), and sort a discrete axis by a\n companion numeric field (`month_name` sorted by `month_num`) rather than\n alphabetically.\n\n## Validate\n\n`malloyyo lint` checks the query, the givens, AND the component (it compiles,\nand each `query="\u2026"` it references resolves) \u2014 your only pre-browser check. Then\n`malloyyo dashboard dev` to see it render.\n',
332
- "develop/connection-setup.md": '---\ndescription: Setting up a data connection (malloy-config.json)\n---\n\n# Setting up a data connection\n\nA model reaches its data through a **connection** declared in\n`malloy-config.json` at the **root of the model** (next to `index.malloy`). This\nis Malloy\'s standard connection config \u2014 the full reference, with every\nconnector\'s properties, is at\n<https://docs.malloydata.dev/documentation/setup/config>. The essentials:\n\n## The file\n\n```json\n{\n "connections": {\n "mydb": { "is": "duckdb" }\n }\n}\n```\n\n- A connection has a **name** (the key) and a type (`is`). Sources refer to it by\n that name \u2014 `source: x is mydb.table("orders")` or `mydb.sql("SELECT \u2026")` \u2014 so\n the name in the config must match the name in the model.\n- Supported types (`is`): `duckdb` (incl. MotherDuck), `bigquery`, `postgres`,\n `mysql`, `snowflake`, `databricks`, `trino`, `presto`. Each has its own\n properties \u2014 see the full docs.\n\n## Default connections (and when they apply)\n\nSetting `"includeDefaultConnections": true` makes one connection available for\n**each registered database type, named by the type** \u2014 a `duckdb` connection\nnamed `duckdb`, a `postgres` named `postgres`, and so on. Each uses that\nconnector\'s default settings, which for several backends means picking up\ncredentials from the environment (e.g. BigQuery\'s application-default\ncredentials \u2014 see the per-connector setup docs). Connections you name explicitly\nin `connections` always win; the defaults only fill in types you didn\'t list.\n\n```json\n{\n "includeDefaultConnections": true,\n "connections": { "warehouse": { "is": "postgres", "host": "\u2026" } }\n}\n```\n\nmalloyyo has one rule worth knowing:\n\n- **No `malloy-config.json` at all \u2192 defaults are ON.** `duckdb` just works with\n zero setup.\n- **Write a `malloy-config.json` and they turn OFF** unless you add\n `"includeDefaultConnections": true`. A config that only defines, say, a\n `postgres` connection will report *No connection named "duckdb"* if a source\n still references `duckdb`.\n\nThis is deliberate \u2014 your local connections then resolve exactly the way the\npublished server\'s will, rather than silently leaning on a default that would not\nexist in production. (It differs from `malloy-cli`, which forces the defaults on\nunconditionally.)\n\n*No connection named* has one cause that is **not** about your config: if more\nthan one copy of `@malloydata/malloy` is installed, the connectors register with\none copy and malloyyo reads another, and every connection looks missing. malloyyo\ndetects that and says so instead \u2014 if it doesn\'t mention duplicate copies, the\nproblem really is the config. To check by hand: `npm ls @malloydata/malloy`.\n\nGive a connection a **custom name** \u2014 not the bare type default \u2014 whenever you\nhave more than one connection of the same type, or need non-default parameters.\n\n## DuckDB and local files (the common case)\n\nDuckDB can either open a **DuckDB database file** or read **local data files**\n(CSV, Parquet, \u2026) directly.\n\n**A pre-loaded database file** \u2014 point `databasePath` at a `.duckdb` file and\nreference its tables by name (an absolute path is safest):\n\n```json\n{ "connections": { "warehouse": { "is": "duckdb", "databasePath": "/data/warehouse.duckdb" } } }\n```\n\n**Local files, by path** \u2014 read a CSV or Parquet file straight into a source.\nThese paths are **project-relative** \u2014 resolved against the model root, so they\nsurvive publishing:\n\n source: my_csv is duckdb.table(\'data/my_file.csv\')\n source: my_parquet is duckdb.table(\'data/my_file.parquet\')\n\n`.table()` names a single file. When you need something it can\'t express \u2014 a\nglob, a union, any SQL \u2014 wrap it in `.sql()` (its paths are project-relative too):\n\n source: payments is duckdb.sql(\n "SELECT * FROM read_parquet(\'data/payments-*.parquet\')"\n )\n\nThe default `duckdb` connection is **in-memory** \u2014 nothing persists between runs;\nyour data lives in the files (or the `databasePath` database) you read.\n\n**MotherDuck:** a DuckDB connection against an `md:` database, with its own\ntoken: `"motherDuckToken": { "env": "MY_MOTHERDUCK_TOKEN" }`. Name the token in\nthe config. On a published instance, a connection with no `motherDuckToken`\ndoesn\'t pick one up from the server\'s environment.\n\n## Secrets \u2014 keep them out of the file\n\nAny property value may be written as `{ "env": "VAR_NAME" }`. It resolves from\n`process.env.VAR_NAME` when the connection opens, so passwords and tokens never\nget committed:\n\n```json\n{\n "connections": {\n "analytics": {\n "is": "postgres",\n "host": "db.internal",\n "databaseName": "analytics",\n "username": "reader",\n "password": { "env": "PG_PASSWORD" }\n }\n }\n}\n```\n\n(The non-secret property names here are illustrative \u2014 each connector\'s exact\nproperties are in the full docs. The `{ "env": \u2026 }` form is the part that\nmatters: it works for any value.)\n\n## malloyyo specifics\n\n- **One file, one place.** Only the `malloy-config.json` at the model root is\n read \u2014 there is no walk-up to parent directories.\n- **Local override:** a `malloy-config-local.json` (do **not** commit it)\n **replaces** `malloy-config.json` entirely when present \u2014 your private variant\n for local credentials or a different database.\n- **The same file ships to production.** Publishing uploads this exact\n `malloy-config.json`, so it must resolve the same way locally and on the\n server \u2014 put anything environment-specific behind `{ "env": \u2026 }` rather than\n hard-coding it. That is what makes the local test window faithful to\n production.\n- Edits are picked up **without a restart** \u2014 the server re-reads the file when\n it changes.\n\n## When a connection will not resolve\n\nFix the connection **first**: a broken connection yields an empty schema and then\na cascade of misleading `field-not-found` errors \u2014 ignore those and fix the\nconnection. A fast check is to compile a probe and see if it alone compiles:\n\n source: _probe is mydb.sql("SELECT 1 AS one")\n',
333
- "develop/documenting-models.md": '---\ndescription: Documenting a model \u2014 what each description is for, where it shows, and how long it should be\n---\n\n# Documenting a model\n\nAn AI reading your published model sees it in two steps. `list_sources` comes\nfirst: every source in every model it can see, so it can pick one. Then\n`describe_source`, for the source it picked: fields, views, joins, and your\nguidance for using it. Each kind of documentation is shown at one of those\nsteps. Put each thing where it is read, at the size it is read at.\n\n| You write | It becomes | Shown in | Keep it to |\n|---|---|---|---|\n| `##"` at the top of `index.malloy` | the model\'s description | `list_sources` | a sentence or two (lint warns past 500 characters) |\n| `#"` above a source | the source\'s description | `list_sources` | one sentence on what the source answers (lint warns past 300) |\n| `#(agent)` above a source | the source\'s instructions | `describe_source` | what someone writing a query must know, in a few short paragraphs |\n| `#"` above a dimension, measure or view | its description | `describe_source` | one line |\n| `#(agent)` above a field | its instructions | `describe_source` | a line or two, only where the name and type don\'t say it |\n\n## Why the sizes matter\n\n`list_sources` is read on every question, before anyone knows which source they\nneed, so every description in it is paid for every time. Ten sources with a\nparagraph each make a listing too large to read in one go. The AI ends up\nsearching it instead of reading it, and can miss the source it needed.\n\n`describe_source` is read once a source has been picked, so it can afford more.\nThat is where the detail goes.\n\n## The model: `##"`\n\nTwo hashes. A single `#"` attaches to the next declaration, so `#"` above the\nfirst source documents that source and leaves the model with nothing.\n\n ##" Orders, customers and products from the online store, as finance reports them.\n\nSay what the dataset is, and for whom. Leave out how to query it; that belongs\nto each source.\n\n## A source: `#"`, then `#(agent)`\n\nThe `#"` is how a reader picks this source over the others. Write it as the\nquestions it answers:\n\n #" One row per order line: revenue, margin and discounts by product, customer and day.\n #(agent) Revenue is net of returns; use `gross_revenue` for the pre-return figure.\n #(agent) Join `customers` for region; `order_date` is in UTC.\n source: order_items is ...\n\nEach `#(agent)` line is joined with the others into the source\'s\n`instructions`. That is the place for grain, the measure to prefer, a filter\nthat is almost always wanted, how two similar fields differ, and what the\nvalues of a coded field mean.\n\nA test: if a sentence in the `#"` only helps someone who has already chosen this\nsource, move it to `#(agent)`.\n\n## Fields and views: one line each\n\n #" Sales after returns, in USD.\n measure: revenue is sale_price.sum() - returned_amount.sum()\n\n #" Top products by revenue this year.\n view: top_products is { ... }\n\n`describe_source` shows these next to each name. A view\'s description is often\nall a reader needs to run it, so give every view one.\n\n## Check it\n\n`malloyyo lint` warns when the model has no `##"`, when an exported source has\nno `#"`, and when either runs past the sizes above. These are warnings, so\nthey never block a publish.\n',
334
- "develop/getting-started.md": '---\ndescription: Getting started \u2014 build a Malloy model step by step\n---\n\n# Building a Malloy model, step by step\n\nA model is a `malloy-config.json` (the connection to the data) and an\n`index.malloy` (the published query surface), optionally with other `.malloy`\nfiles that `index.malloy` imports. You edit these with your own file tools; the\nMCP tools compile, inspect, and test what you wrote. Never read `.malloy` as\ntext \u2014 compiling a bare source is how you read a table\'s schema.\n\n## 1. Verify the connection first\n\nConfirm the connection named in `malloy-config.json` resolves \u2014 compile a\nthrowaway probe inline with `compile` (no file needed):\n\n source: _probe is CONN.sql("SELECT 1 AS one")\n\nIf it compiles, the connection is good. If not, fix the connection / config\nbefore going further \u2014 a broken connection produces an empty schema and then a\ncascade of misleading `field-not-found` errors; ignore the cascade and fix the\nconnection. Call `yo_help("develop/connection-setup")` for how to set up or repair a connection.\n\n## 2. Identify the tables the model needs\n\nIf you are unsure which tables matter, ask the fox \u2014 they own the data and know\nwhere it lives.\n\n## 3. Get a base source per table\n\nA base is "what\'s in the table and what\'s computable from it" \u2014 no joins.\nDiscover the schema by compiling a bare stub inline with `compile`:\n\n source: users_base is CONN.table("users")\n\n`compile` returns the full column list + types \u2014 that is your schema browser.\nThen write the base into its own file and iterate with `compile_file`, adding\nonly the dimensions and measures intrinsic to that one table:\n\n // users_base.malloy\n source: users_base is CONN.table("users") extend {\n measure: user_count is count()\n }\n\nIf the data lives in files rather than database tables \u2014 common when the\nconnection is DuckDB \u2014 DuckDB lets you name a file path as the table (a\nproject-relative path):\n\n source: users_base is CONN.table(\'data/users.parquet\')\n\nOnly drop to a `.sql()` block when a single file-as-table can\'t express what you\nneed \u2014 e.g. globbing or unioning several files:\n\n source: users_base is CONN.sql("SELECT * FROM read_parquet(\'data/users-*.parquet\')")\n\n(`read_parquet` there is DuckDB SQL, not Malloy \u2014 see `yo_help("develop/connection-setup")`.)\n\n## 4. Assemble index.malloy \u2014 the published surface\n\nImport the bases, join them into the consumer-facing sources, and explicitly\nexport what consumers may query:\n\n import "users_base.malloy"\n import "orders_base.malloy"\n\n source: users is users_base extend {\n join_many: orders is orders_base on id = orders.user_id\n }\n source: orders is orders_base extend { }\n\n export { users, orders }\n\n**Export discipline** \u2014 the model is a published artifact, so be deliberate about\nits public surface:\n\n- Imported names are private. Base sources stay internal scaffolding unless you\n export them.\n- Without an `export` statement, everything you define is public. Add one and the\n surface becomes explicit: only the names you list \u2014 defined or imported \u2014 are\n public.\n- Hide intermediates. A staging source you define only so other sources can build\n on it should not be exported.\n- The export list is the consumer\'s menu \u2014 exactly what the test window and real\n consumers can query, nothing more.\n\n**Document what you export.** A `##"` for the model, a one-sentence `#"` on each\nexported source (what it answers), and `#(agent)` lines for how to query it.\n`list_sources` shows the short ones on every question, so size matters \u2014 see\n`yo_help("develop/documenting-models")`. `malloyyo lint` warns on missing or\noversized descriptions.\n\n## The loop\n\nEdit a file \u2192 `compile_file` \u2192 fix `problems[]` \u2192 `query` (pass the model file\'s\npath as `ref`; `execute: false` validates first and reports the givens the query\nneeds, supplied via `givens`). Query text is restricted \u2014 `import`, `given:`\ndeclarations, `connection.table`/`connection.sql`, raw SQL, and `##!` flags\nbelong in the model file, not the query. When `compile`/`compile_file` returns\n`formatted: false`, call `prettify` and save its output. Use project-relative\ndata paths, not absolute \u2014 they resolve against the project root and survive\npublishing the model.\n',
335
- "develop/working-with-models.md": "---\ndescription: Working with an existing Malloy model\n---\n\n# Working with an existing model\n\nAn existing model is an `index.malloy` (plus any `.malloy` files it imports) and\na `malloy-config.json`.\n\n## Understand the model\n\n- **Read `malloy-config.json` directly** \u2014 it is JSON, so read it as text. It\n lists the connection(s) the model queries against; `yo_help(\"develop/connection-setup\")` explains\n the format (and how to set one up or repair it).\n- **Do NOT read `.malloy` as text \u2014 compile it.** `compile_file` returns the\n structured model: each source with its fields, joins, views, and named queries,\n plus `problems[]`. That is how you describe what is in the model. (Compiling a\n bare source \u2014 no `extend` block \u2014 likewise reads a raw table's schema.)\n\n## The loop\n\nEdit a file \u2192 `compile_file` \u2192 fix `problems[]` \u2192 `query`. Pass the model file's\npath as `ref`; `execute: false` validates first and reports the givens the query\nneeds (supplied via `givens`). Query text is restricted \u2014 `import`, `given:`\ndeclarations, `connection.table`/`connection.sql`, raw SQL, and `##!` flags\nbelong in the model file, not the query. When `compile`/`compile_file` returns\n`formatted: false`, run `prettify` and save its output. Use project-relative data\npaths, not absolute.\n",
336
- "explore/charting-results.md": "---\ndescription: Answer with a chart \u2014 the render tags, how channels are chosen, and when a chart beats a table\n---\n\n# Charting a result\n\nA query result renders as a table unless you tag it. One line above the query\nturns it into a chart, and the tag travels with the result \u2014 so a shared link or\na saved query draws the same picture later.\n\n```malloy\n# bar_chart\nrun: order_items -> {\n group_by: brand is inventory_items.product_brand\n aggregate: total_sales\n order_by: total_sales desc\n limit: 10\n}\n```\n\n**A tag on its own line attaches to the thing on the NEXT line.** That is the\nwhole placement rule, and it is also the trap:\n\n```malloy\n// WRONG \u2014 the tag attaches to `birth_year`, not to the query.\n// Malloy compiles this, runs it, returns rows, and silently draws a TABLE.\nrun: baby_names -> {\n where: name = 'James' | 'Michael'\n # line_chart { x=birth_year y=total_babies series=name }\n group_by: birth_year\n group_by: name\n aggregate: total_babies\n}\n```\n\n```malloy\n// RIGHT \u2014 above `run:`, so it attaches to the query.\n# line_chart { x=birth_year y=total_babies series=name }\nrun: baby_names -> {\n where: name = 'James' | 'Michael'\n group_by: birth_year\n group_by: name\n aggregate: total_babies\n}\n```\n\nNothing warns you. The tag simply does not appear in the result's annotations,\nand the renderer has no chart to draw. If you tagged a query and got a table,\nthis is why, before anything else.\n\nRelated: `yo_help dashboards/charts` goes deeper on the dimension-counting rule\nand on sorting a named axis; this topic is about answering a question with a\npicture.\n\n## Choose the shape from the question\n\n| The question is about\u2026 | Use | The x axis is |\n|---|---|---|\n| ranking or comparing categories | `# bar_chart` | the category |\n| change over time | `# line_chart` | the time field |\n| whether two measures relate | `# scatter_chart` | the first measure |\n| variation across US states | `# shape_map` | the state name |\n\nIf none of those is what was asked, **leave it a table**. A chart of eight\ncolumns is worse than the eight columns, and a bar chart whose bars are all the\nsame height says \"no pattern\" at the cost of the reader's attention.\n\n## Name the channels\n\n```malloy\n# bar_chart { x=brand y=total_sales }\n# bar_chart { x=nickname y=flight_count series=destination }\n# line_chart { x=order_month y=['sales', 'cost'] }\n```\n\nLeft unset they are inferred: **x** takes a time dimension if there is one and\notherwise the first dimension, **y** takes the first aggregate, and \u2014 the rule\nthat catches people \u2014 **any leftover dimension becomes a colour series**.\n\nSo a result with two `group_by` fields and only `x` named will grow a legend you\ndid not ask for, and one with three or more untagged dimensions is refused\noutright:\n\n> Too many dimensions. A bar chart can have at most 2 dimensions: 1 for the x\n> axis, and 1 for the series.\n\nAggregates are exempt \u2014 a result may carry as many measures as you like; only\nthose named in `y` are drawn.\n\n**`# hidden` does not exempt a dimension from that count.** It hides a column in\na table; a hidden `group_by` is still a dimension and will still be promoted to a\nseries.\n\n*If you need a sort key that is not a channel, make it a MEASURE* \u2014\n`aggregate: sort_key is min(month_number)` \u2014 because measures can never be\npromoted. That is the standard fix for \"label it January, order it first\".\n\n## Properties worth knowing\n\n| | |\n|---|---|\n| `size` | `spark`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, or `size.width` / `size.height` in pixels |\n| `stack` | `# bar_chart.stack` \u2014 stack instead of group |\n| `zero_baseline` | line charts: force the y axis to include zero |\n| `series.limit` | how many series before the rest are dropped (bar 20, line 12) |\n| `title`, `subtitle` | a heading on the chart itself |\n| `x.limit` | cap the categories drawn |\n\nChannels can also be tagged on the fields instead of in the block, which reads\nbetter when the query is long:\n\n```malloy\n# bar_chart\nrun: flights -> {\n group_by:\n # series\n destination\n # x\n carriers.nickname\n aggregate:\n # y\n flight_count\n}\n```\n\n## Scatter and maps take fields in ORDER\n\n`# scatter_chart` reads them positionally: **x, y, colour, size, shape**. There\nare no channel names to set, so the order of your `group_by`/`aggregate` clauses\nis the encoding.\n\n`# shape_map` is **US states only**, and wants **state name first, value\nsecond**. `# segment_map` takes `lat1, lon1, lat2, lon2, colour`.\n\n## Format the numbers\n\nA chart with raw floats on the axis is harder to read than the table it\nreplaced. These attach to a field, not to the chart:\n\n```malloy\naggregate:\n # currency=usd2m\n total_sales\n # percent\n share_of_sales\n # number=\"#,##0\"\n order_count\n```\n\n`# duration`, `# data_volume`, `# link` and `# image` follow the same shape.\n\n## Check it drew\n\nA chart that compiles can still refuse to render \u2014 \"too many dimensions\" happens\nat draw time, not compile time. If you ran the query and the caller sees a table\nwhere you expected a chart, the tag did not take: check that it is on its own\nline directly above the query, and that you have not left a spare dimension to be\npromoted.\n",
312
+ "explore/charting-results.md": "---\ndescription: Answer with a chart \u2014 the render tags, how channels are chosen, and when a chart beats a table\n---\n\n# Charting a result\n\nA query result renders as a table unless you tag it. One line above the query\nturns it into a chart, and the tag travels with the result \u2014 so a shared link or\na saved query draws the same picture later.\n\n```malloy\n# bar_chart\nrun: order_items -> {\n group_by: brand is inventory_items.product_brand\n aggregate: total_sales\n order_by: total_sales desc\n limit: 10\n}\n```\n\n**A tag on its own line attaches to the thing on the NEXT line.** That is the\nwhole placement rule, and it is also the trap:\n\n```malloy\n// WRONG \u2014 the tag attaches to `birth_year`, not to the query.\n// Malloy compiles this, runs it, returns rows, and silently draws a TABLE.\nrun: baby_names -> {\n where: name = 'James' | 'Michael'\n # line_chart { x=birth_year y=total_babies series=name }\n group_by: birth_year\n group_by: name\n aggregate: total_babies\n}\n```\n\n```malloy\n// RIGHT \u2014 above `run:`, so it attaches to the query.\n# line_chart { x=birth_year y=total_babies series=name }\nrun: baby_names -> {\n where: name = 'James' | 'Michael'\n group_by: birth_year\n group_by: name\n aggregate: total_babies\n}\n```\n\nNothing warns you. The tag simply does not appear in the result's annotations,\nand the renderer has no chart to draw. If you tagged a query and got a table,\nthis is why, before anything else.\n\n## Choose the shape from the question\n\n| The question is about\u2026 | Use | The x axis is |\n|---|---|---|\n| ranking or comparing categories | `# bar_chart` | the category |\n| change over time | `# line_chart` | the time field |\n| whether two measures relate | `# scatter_chart` | the first measure |\n| variation across US states | `# shape_map` | the state name |\n\nIf none of those is what was asked, **leave it a table**. A chart of eight\ncolumns is worse than the eight columns, and a bar chart whose bars are all the\nsame height says \"no pattern\" at the cost of the reader's attention.\n\n## Name the channels\n\n```malloy\n# bar_chart { x=brand y=total_sales }\n# bar_chart { x=nickname y=flight_count series=destination }\n# line_chart { x=order_month y=['sales', 'cost'] }\n```\n\nLeft unset they are inferred: **x** takes a time dimension if there is one and\notherwise the first dimension, **y** takes the first aggregate, and \u2014 the rule\nthat catches people \u2014 **any leftover dimension becomes a colour series**.\n\nSo a result with two `group_by` fields and only `x` named will grow a legend you\ndid not ask for, and one with three or more untagged dimensions is refused\noutright:\n\n> Too many dimensions. A bar chart can have at most 2 dimensions: 1 for the x\n> axis, and 1 for the series.\n\nAggregates are exempt \u2014 a result may carry as many measures as you like; only\nthose named in `y` are drawn.\n\n**`# hidden` does not exempt a dimension from that count.** It hides a column in\na table; a hidden `group_by` is still a dimension and will still be promoted to a\nseries.\n\n*If you need a sort key that is not a channel, make it a MEASURE* \u2014\n`aggregate: sort_key is min(month_number)` \u2014 because measures can never be\npromoted. That is the standard fix for \"label it January, order it first\".\n\n## Properties worth knowing\n\n| | |\n|---|---|\n| `size` | `spark`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, or `size.width` / `size.height` in pixels |\n| `stack` | `# bar_chart.stack` \u2014 stack instead of group |\n| `zero_baseline` | line charts: force the y axis to include zero |\n| `series.limit` | how many series before the rest are dropped (bar 20, line 12) |\n| `title`, `subtitle` | a heading on the chart itself |\n| `x.limit` | cap the categories drawn |\n\nChannels can also be tagged on the fields instead of in the block, which reads\nbetter when the query is long:\n\n```malloy\n# bar_chart\nrun: flights -> {\n group_by:\n # series\n destination\n # x\n carriers.nickname\n aggregate:\n # y\n flight_count\n}\n```\n\n## Scatter and maps take fields in ORDER\n\n`# scatter_chart` reads them positionally: **x, y, colour, size, shape**. There\nare no channel names to set, so the order of your `group_by`/`aggregate` clauses\nis the encoding.\n\n`# shape_map` is **US states only**, and wants **state name first, value\nsecond**. `# segment_map` takes `lat1, lon1, lat2, lon2, colour`.\n\n## Format the numbers\n\nA chart with raw floats on the axis is harder to read than the table it\nreplaced. These attach to a field, not to the chart:\n\n```malloy\naggregate:\n # currency=usd2m\n total_sales\n # percent\n share_of_sales\n # number=\"#,##0\"\n order_count\n```\n\n`# duration`, `# data_volume`, `# link` and `# image` follow the same shape.\n\n## Check it drew\n\nA chart that compiles can still refuse to render \u2014 \"too many dimensions\" happens\nat draw time, not compile time. If you ran the query and the caller sees a table\nwhere you expected a chart, the tag did not take: check that it is on its own\nline directly above the query, and that you have not left a spare dimension to be\npromoted.\n",
337
313
  "explore/how-to.md": "---\ndescription: Extended instructions working with this MCP server\n---\n# General Notes\nMalloy is a combined semantic layer/query language. It describes data and analysis, and it can generate and execute SQL.\n\nYou answer questions from published Malloy semantic models. A model publishes sources and queries.\n\n* Some tools return problems[] to indicate invalid Malloy. problems may have a `help_topic` field \u2014 call `yo_help(help_topic)` for detailed guidance.\n* `yo_help()` with no topic will show an index which include error explanations, examples of Malloy syntax for common patterns, and a language reference manual (Malloy syntax is still evolving).\n* Tools that inspect Malloy code return objects with schemas, among other things. An entry with a name which requires `back-tick-quoting` (reserved word, special characters), will have `must_quote: true`\n* When limiting queries, do ranking, top-N, and member selection in Malloy, not in client code. Results are byte-budgeted: oversized results are truncated (the response says so and may link the full result). Reading aggregated rows is better analysis and the only way to see everything.\n* Compose your answer from what the model publishes. When composing a query, you can make new sources, extending existing sources with measures dimensions and joins. If the model's surface genuinely cannot answer a question, that is useful signal about the model.\n\n# Answering A Question\nTo answer a question you need to see what sources are available which pertain to the question.\n\n`list_sources` (when available) \u2014 see the sources you can query, grouped by model, with each model's named queries. If you already know the source, go straight to describe_source.\n\n# Build the Query\n* New to a pattern? `yo_help(\"explore/query-examples\")` \u2014 the handful of Malloy query shapes (views, the workhorse group_by/aggregate, filtered aggregates, `all()`, `extend:`, `select:`, `nest:`) that cover almost every question, with the SQL habits that are wrong in Malloy.\n* `describe_source(source, model_ref)` \u2014 always describe a source before querying it (`model_ref` optional when the name is unique). Returns:\n * `described_source` \u2014 the source's `dimensions` (columns), `measures`, and `views` (the author's saved queries). A dimension's `type` is a scalar or a nested record (`origin.city`); an array column has no `type` \u2014 it shows up as a `joins` entry at its `path`.\n * `joins` \u2014 keyed by path, the arrays and source-joins this source reaches. `fans_out` marks a path that fans out. Each entry is one of: `{ source }` (fields in `join_source_map`), `{ source_def }` (an anonymous source's fields, inline), or an array `{ is_array, source_def }` \u2014 a record array's fields are used directly (`parcels.sku`), a scalar array's element is `each` (`tags.each`). To write a reference, use the entry's `quoted_path` if it has one, else the key.\n * `join_source_map` \u2014 the named sources those `{ source }` joins resolve to, deduped.\n * In its own content block, the source's raw Malloy, for anything the structured output above doesn't cover.\n* `query(source: \"...\", malloy: \"run: source -> { ... }\", execute: false)` \u2014 validate without running; it returns the SQL. Iterate until clean. (`model_ref` optional, needed only when the source name is ambiguous.)\n* Some queries accept parameters (givens). More info if needed: yo_help(\"language/givens-model-level-parameters\")\n\n# Run the query\n* Pass a plain-English question with EVERY query, describing what that specific query answers. Queries are recorded/shared independently. Don't try to group related queries.\n* query(source: \"...\", malloy: \"run: source -> { ... }\", question: \"...\") \u2014 run it; get the rows.\n* Next to `rows`, the result carries `columns`: each column's `type` (with a number's `subtype`, a truncated date's `timeframe`, a nest's `fields`) and, when the model or query declares one, its display `format` exactly as tagged (`currency = usd0k`, `percent`, `number = \"mmm yyyy\"`). Write values the way `format` says: `currency = usd0k` is $521k, not 521034.77. A timestamp column may also carry `timezone` (the query's `timezone:`): `rows` hold the instant as UTC ISO text, so read its date and time in that zone. No `timezone` means UTC.\n\n# Displaying Results\n* Lead with a natural-language restatement of the query \u2014 a short heading works well.\n* A successful query comes back with an ltool_link \u2014 {text, url}, already assembled. It opens this exact query so the user can keep exploring, or share the insight. Follow the data with a markdown link, [\u2197 text](url).\n* When it helps the reader add a short note on how you got the answer: the Malloy logic (filters, grouping, aggregation, ordering, pipeline stages), and any post-processing done outside Malloy.",
338
- "explore/query-examples.md": "---\ndescription: Worked query examples \u2014 the handful of Malloy shapes that cover almost every question. Read this before writing a query from scratch.\n---\n# Query Examples\n\nAlmost every query is one of the shapes below. Examples use a `flights` source\n(dimensions like `carrier`, `distance`, `origin`, `destination`, `state`,\n`dep_delay`, `is_small_plane`; measures `flight_count`, `total_distance`).\nSubstitute the real fields from `describe_source`.\n\nTwo rules first: do ordering, limiting, and ranking **in Malloy**, not in client\ncode \u2014 and reuse what the source already publishes before writing your own.\n\n## Run a saved view\n\nThe source may already answer the question. A view is invoked by name:\n\n```malloy\nrun: flights -> by_carrier\n```\n\nRefine a saved view in place with `+ { \u2026 }` \u2014 no need to rewrite it:\n\n```malloy\nrun: flights -> by_carrier + { where: state = 'CA' }\n```\n\n## The workhorse query\n\nWhen no view fits, write a stage. The vast majority of queries are this shape \u2014\n`group_by` the dimensions, `aggregate` the **measures the source already\ndeclares**, `where` to filter, `order_by` to rank. Reuse the measures\n`describe_source` lists (here `flight_count`); don't re-derive an aggregate the\nsource already defines (`count()`):\n\n```malloy\nrun: flights -> {\n group_by: destination\n aggregate: flight_count\n where: state = 'CA'\n order_by: flight_count desc\n limit: 10\n}\n```\n\nEvery clause is `keyword:` (note the colon, including `order_by:`).\n\n### Aggregate moves\n\n**Filtered aggregate** \u2014 `measure { where: \u2026 }` filters *that one number* only,\nindependent of the stage `where:`. Two kinds of `where`: stage-level (which rows\nenter the query) vs aggregate-level (which rows a single aggregate counts).\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate:\n flight_count\n percent_late is flight_count { where: dep_delay > 15 } / flight_count * 100\n}\n```\n\n**Aggregates from scratch** \u2014 *only when the source has no measure for what you\nneed*, define your own with `is`:\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate:\n flight_count is count() -- row count\n destination_count is count(destination) -- DISTINCT destinations\n total_distance is distance.sum() -- field-first aggregation\n}\n```\n\n**Percent of total with `all()`** \u2014 `all(expr)` ignores the `group_by:` to give\nthe grand total, so a share is `part / all(part)`:\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate:\n flight_count\n pct_of_total is flight_count / all(flight_count)\n}\n```\n\n(`all(expr, dim)` totals within a subgroup \u2014 it takes the **alias from\n`group_by:`**, not a dotted path.)\n\n### Declare once, reuse \u2014 `extend:`\n\nWhen an expression repeats in a query, define it locally in an `extend:` block:\n\n```malloy\nrun: flights -> {\n extend: {\n measure: total_distance is distance.sum()\n dimension: state_first_letter is substr(state, 1, 1)\n }\n group_by: state_first_letter\n aggregate:\n total_distance\n small_plane_distance is total_distance { where: is_small_plane }\n}\n```\n\n**Composing aggregates.** You can't reference one aggregate from another in the\nsame stage (`aggregate: a is \u2026, b is a/2` fails \u2014 *\"'a' is not defined\"*). To\nbuild a value *from* other aggregates \u2014 a ratio, a share \u2014 define the parts as\nmeasures in `extend:` (measures **can** reference each other), then use them:\n\n```malloy\nrun: flights -> {\n extend: {\n measure:\n late_flights is flight_count { where: dep_delay > 15 }\n pct_late is late_flights / flight_count\n }\n group_by: carrier\n aggregate: late_flights, pct_late\n order_by: pct_late desc\n}\n```\n\nTo rank by a computed value, name it (in `aggregate:` or `extend:`) and\n`order_by:` that name \u2014 `order_by:` takes an output field name, never a raw\nexpression, and there is no `derive:` step.\n\n## Flat detail rows \u2014 `select:`\n\nTo fetch raw rows instead of aggregating, use `select:` (the columns to return):\n\n```malloy\nrun: flights -> {\n select: id, carrier, origin, destination, distance\n where: distance > 1000\n order_by: distance desc\n limit: 100\n}\n```\n\nA stage is **either** a reduction (`group_by:` / `aggregate:`) **or** a projection\n(`select:`) \u2014 never both in the same stage. And `select:` **cannot** be combined\nwith `nest:` in any way; nesting belongs to reductions.\n\n## Nesting \u2014 a sub-table per row\n\n`nest:` attaches a whole query to each row of the outer one. This is where\nanswers get their depth (a per-row ranked breakdown):\n\n```malloy\nrun: flights -> {\n group_by: origin\n aggregate: flight_count\n nest: by_carrier is {\n group_by: carrier\n aggregate: flight_count\n order_by: flight_count desc\n limit: 5\n }\n}\n```\n\n**Listing top-N detail rows in a nest \u2014 `group_by:`, not `select:`.** A nest is a\nreduction, so to nest raw rows (not an aggregate) list the columns with\n`group_by:` (`select:` is not allowed inside a nest):\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate: flight_count\n nest: longest_flights is {\n group_by: origin, destination, distance\n order_by: distance desc\n limit: 5\n }\n}\n```\n\n## Multi-stage \u2014 aggregate, then aggregate again (`->`)\n\nA second `->` runs another stage over the **output** of the first. Reach for it\nwhen you need to aggregate an aggregate \u2014 e.g. the **peak** of a per-period\ntotal. You can't write `flight_count.max()` (that's an aggregate of an aggregate\n\u2014 it errors); compute the per-period total in one stage, then take the max in the\nnext:\n\n```malloy\nrun: flights -> {\n group_by: carrier, dep_year\n aggregate: flights_that_year is flight_count\n} -> {\n group_by: carrier\n aggregate: peak_year is flights_that_year.max()\n}\n```\n\nIn the second stage `flights_that_year` is an ordinary column (the first stage's\noutput), so `.max()` is valid. The same shape filters or re-ranks already-\naggregated rows.\n\n## Make a cell a clickable deep link \u2014 `# link`\n\nWhen the answer is \"here's the row, go look at it in the source system\", tag a\n`group_by:`/`select:` field with `# link` so its cell renders as a hyperlink\n(in the shareable ltool view and in dashboards). Three forms:\n\n```malloy\nrun: flights -> {\n # link -- the value IS a full URL\n group_by: page is concat('https://wikipedia.org/wiki/', origin)\n}\n```\n\n```malloy\nrun: flights -> {\n # link { url_template='https://www.flightsfrom.com/$$' } -- $$ = this cell's value\n group_by: origin\n}\n```\n\nLink to a value *other* than the one displayed with `field=`, and hide the raw\nid with `# hidden` so only the label shows:\n\n```malloy\nrun: flights -> {\n # link { url_template='https://crm.example.com/person/$$' field=person_id }\n group_by: person_name\n # hidden\n group_by: person_id\n}\n```\n\n`$$` is substituted anywhere in the template (`.../$$-SJC` works). Sibling\n`# image { url_template=\u2026 width= height= alt= }` renders the cell as an inline\nimage instead. Deep links open in a new browser tab.\n\n## SQL habits that are WRONG in Malloy\n\n| You'd write in SQL | Malloy |\n| --- | --- |\n| `COUNT(DISTINCT x)` | `count(x)` \u2014 `count(distinct x)` is a deprecated error |\n| `SUM(x)` | `x.sum()` |\n| `SUM(x) OVER ()` | `all(x)` |\n| `COUNT(*) FILTER (WHERE c)` / `CASE WHEN` | `count() { where: c }` |\n| `SELECT \u2026 GROUP BY \u2026` | `group_by:` + `aggregate:` (one stage is reduction OR `select:`, never both) |\n",
314
+ "explore/query-examples.md": "---\ndescription: Worked query examples \u2014 the handful of Malloy shapes that cover almost every question. Read this before writing a query from scratch.\n---\n# Query Examples\n\nAlmost every query is one of the shapes below. Examples use a `flights` source\n(dimensions like `carrier`, `distance`, `origin`, `destination`, `state`,\n`dep_delay`, `is_small_plane`; measures `flight_count`, `total_distance`).\nSubstitute the real fields from `describe_source`.\n\nTwo rules first: do ordering, limiting, and ranking **in Malloy**, not in client\ncode \u2014 and reuse what the source already publishes before writing your own.\n\n## Run a saved view\n\nThe source may already answer the question. A view is invoked by name:\n\n```malloy\nrun: flights -> by_carrier\n```\n\nRefine a saved view in place with `+ { \u2026 }` \u2014 no need to rewrite it:\n\n```malloy\nrun: flights -> by_carrier + { where: state = 'CA' }\n```\n\n## The workhorse query\n\nWhen no view fits, write a stage. The vast majority of queries are this shape \u2014\n`group_by` the dimensions, `aggregate` the **measures the source already\ndeclares**, `where` to filter, `order_by` to rank. Reuse the measures\n`describe_source` lists (here `flight_count`); don't re-derive an aggregate the\nsource already defines (`count()`):\n\n```malloy\nrun: flights -> {\n group_by: destination\n aggregate: flight_count\n where: state = 'CA'\n order_by: flight_count desc\n limit: 10\n}\n```\n\nEvery clause is `keyword:` (note the colon, including `order_by:`).\n\n### Aggregate moves\n\n**Filtered aggregate** \u2014 `measure { where: \u2026 }` filters *that one number* only,\nindependent of the stage `where:`. Two kinds of `where`: stage-level (which rows\nenter the query) vs aggregate-level (which rows a single aggregate counts).\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate:\n flight_count\n percent_late is flight_count { where: dep_delay > 15 } / flight_count * 100\n}\n```\n\n**Aggregates from scratch** \u2014 *only when the source has no measure for what you\nneed*, define your own with `is`:\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate:\n flight_count is count() -- row count\n destination_count is count(destination) -- DISTINCT destinations\n total_distance is distance.sum() -- field-first aggregation\n}\n```\n\n**Percent of total with `all()`** \u2014 `all(expr)` ignores the `group_by:` to give\nthe grand total, so a share is `part / all(part)`:\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate:\n flight_count\n pct_of_total is flight_count / all(flight_count)\n}\n```\n\n(`all(expr, dim)` totals within a subgroup \u2014 it takes the **alias from\n`group_by:`**, not a dotted path.)\n\n### Declare once, reuse \u2014 `extend:`\n\nWhen an expression repeats in a query, define it locally in an `extend:` block:\n\n```malloy\nrun: flights -> {\n extend: {\n measure: total_distance is distance.sum()\n dimension: state_first_letter is substr(state, 1, 1)\n }\n group_by: state_first_letter\n aggregate:\n total_distance\n small_plane_distance is total_distance { where: is_small_plane }\n}\n```\n\n**Composing aggregates.** You can't reference one aggregate from another in the\nsame stage (`aggregate: a is \u2026, b is a/2` fails \u2014 *\"'a' is not defined\"*). To\nbuild a value *from* other aggregates \u2014 a ratio, a share \u2014 define the parts as\nmeasures in `extend:` (measures **can** reference each other), then use them:\n\n```malloy\nrun: flights -> {\n extend: {\n measure:\n late_flights is flight_count { where: dep_delay > 15 }\n pct_late is late_flights / flight_count\n }\n group_by: carrier\n aggregate: late_flights, pct_late\n order_by: pct_late desc\n}\n```\n\nTo rank by a computed value, name it (in `aggregate:` or `extend:`) and\n`order_by:` that name \u2014 `order_by:` takes an output field name, never a raw\nexpression, and there is no `derive:` step.\n\n## Flat detail rows \u2014 `select:`\n\nTo fetch raw rows instead of aggregating, use `select:` (the columns to return):\n\n```malloy\nrun: flights -> {\n select: id, carrier, origin, destination, distance\n where: distance > 1000\n order_by: distance desc\n limit: 100\n}\n```\n\nA stage is **either** a reduction (`group_by:` / `aggregate:`) **or** a projection\n(`select:`) \u2014 never both in the same stage. And `select:` **cannot** be combined\nwith `nest:` in any way; nesting belongs to reductions.\n\n## Nesting \u2014 a sub-table per row\n\n`nest:` attaches a whole query to each row of the outer one. This is where\nanswers get their depth (a per-row ranked breakdown):\n\n```malloy\nrun: flights -> {\n group_by: origin\n aggregate: flight_count\n nest: by_carrier is {\n group_by: carrier\n aggregate: flight_count\n order_by: flight_count desc\n limit: 5\n }\n}\n```\n\n**Listing top-N detail rows in a nest \u2014 `group_by:`, not `select:`.** A nest is a\nreduction, so to nest raw rows (not an aggregate) list the columns with\n`group_by:` (`select:` is not allowed inside a nest):\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate: flight_count\n nest: longest_flights is {\n group_by: origin, destination, distance\n order_by: distance desc\n limit: 5\n }\n}\n```\n\n## Multi-stage \u2014 aggregate, then aggregate again (`->`)\n\nA second `->` runs another stage over the **output** of the first. Reach for it\nwhen you need to aggregate an aggregate \u2014 e.g. the **peak** of a per-period\ntotal. You can't write `flight_count.max()` (that's an aggregate of an aggregate\n\u2014 it errors); compute the per-period total in one stage, then take the max in the\nnext:\n\n```malloy\nrun: flights -> {\n group_by: carrier, dep_year\n aggregate: flights_that_year is flight_count\n} -> {\n group_by: carrier\n aggregate: peak_year is flights_that_year.max()\n}\n```\n\nIn the second stage `flights_that_year` is an ordinary column (the first stage's\noutput), so `.max()` is valid. The same shape filters or re-ranks already-\naggregated rows.\n\n## Make a cell a clickable deep link \u2014 `# link`\n\nWhen the answer is \"here's the row, go look at it in the source system\", tag a\n`group_by:`/`select:` field with `# link` so its cell renders as a hyperlink\n(wherever the host renders results). Three forms:\n\n```malloy\nrun: flights -> {\n # link -- the value IS a full URL\n group_by: page is concat('https://wikipedia.org/wiki/', origin)\n}\n```\n\n```malloy\nrun: flights -> {\n # link { url_template='https://www.flightsfrom.com/$$' } -- $$ = this cell's value\n group_by: origin\n}\n```\n\nLink to a value *other* than the one displayed with `field=`, and hide the raw\nid with `# hidden` so only the label shows:\n\n```malloy\nrun: flights -> {\n # link { url_template='https://crm.example.com/person/$$' field=person_id }\n group_by: person_name\n # hidden\n group_by: person_id\n}\n```\n\n`$$` is substituted anywhere in the template (`.../$$-SJC` works). Sibling\n`# image { url_template=\u2026 width= height= alt= }` renders the cell as an inline\nimage instead. Deep links open in a new browser tab.\n\n## SQL habits that are WRONG in Malloy\n\n| You'd write in SQL | Malloy |\n| --- | --- |\n| `COUNT(DISTINCT x)` | `count(x)` \u2014 `count(distinct x)` is a deprecated error |\n| `SUM(x)` | `x.sum()` |\n| `SUM(x) OVER ()` | `all(x)` |\n| `COUNT(*) FILTER (WHERE c)` / `CASE WHEN` | `count() { where: c }` |\n| `SELECT \u2026 GROUP BY \u2026` | `group_by:` + `aggregate:` (one stage is reduction OR `select:`, never both) |\n",
339
315
  "explore/restricted-queries.md": "# Restricted Query Explanation\n\nThe `query` tool runs your Malloy against a **published model**. You have that\nmodel's entire published surface to work with \u2014 and you can build on it. The\nmodel is an inentionally curated subset of the data available in the\ndatabase.\n\n## You can\n\n- Use everything the model defines: its **sources, dimensions, measures, views,\n joins, and named queries**. `describe_source` shows exactly what's there.\n- **Run a named query and refine it** \u2014\n `run: top_carriers + { where: dep_year = 2024 }`.\n- **Define your own** dimensions, measures, and **your own sources and joins** \u2014\n as long as they are *derived from the model's sources*. You are not limited to\n the author's fields; compose new ones from them.\n- Reference the model's `$NAME` givens and supply values via the `givens` map on\n the `query` call (use `execute: false` to discover which a query needs).\n- Use a model field that was itself defined with raw SQL \u2014 the author vouched\n for the model's own definitions.\n\n## What is \"Restricted\"\n\nIf you see `restricted-construct-forbidden`, the query used something that\nreaches *outside* the published model: pulling in another file (`import`),\nopening a raw connection (`connection.table(...)` / `connection.sql(...)`),\nwriting raw SQL (`name!type(...)` or the `sql_*` functions), declaring new\n`given:`s, or setting `##!` compiler flags.\n\nThe fix is never to work around it \u2014 express the answer in terms of what the\nmodel publishes (define derived sources, joins, dimensions, and measures from\nthe model's sources). If something fundamental is missing, that's feedback for\nthe model's author.\n",
340
316
  "language/malloy-language-reference.md": '<!-- Copied from malloy-cli (jrtipton/malloy-cli) skills/malloy-language-reference.md on 2026-06-11.\n Deliberate temporary fork \u2014 converge when the engine is extracted to @malloydata. -->\n---\ndescription: Malloy language reference \u2014 concepts, syntax, compilation model. Load this before writing or reviewing Malloy code.\n---\n# Malloy Language Reference\n\nMalloy is a semantic data modeling and query language. It compiles to SQL and runs against existing database engines (DuckDB, BigQuery, Snowflake, PostgreSQL, MySQL, Trino, Presto). It is not a SQL wrapper or abstraction layer \u2014 it has its own type system, scoping rules, expression semantics, and compilation pipeline.\n\nMalloy is designed around how humans think about data, not how data computations are mechanically accomplished. SQL is oriented around the machine \u2014 you specify joins, group-by columns, subqueries, and window functions in terms of what the database needs to do. Malloy is oriented around the analyst \u2014 you describe relationships, name computations, and compose questions in terms of what the data means. Malloy bridges the gap between these two by compiling the human-oriented description into correct, efficient SQL.\n\nA core design principle is that **most queries are themselves designing a new semantic model.** Formulating a question about data \u2014 choosing what to group by, what to aggregate, what to nest \u2014 is inherently an act of defining a new way to look at that data. Malloy is built around this idea: the output of every query is not just a result set but a new source with its own schema, and data comprehension is an ongoing iterative process where later stages want not only the data from a previous stage but how that data came into being. This is why query output carries metadata, why queries can be used as sources, and why views and pipelines compose naturally.\n\n## Documents and Statements\n\nA Malloy file (`.malloy`) is a sequence of statements, optionally separated by semicolons. There are five statement types:\n\n- **`import`** \u2014 import sources and queries from another `.malloy` file\n- **`source:`** \u2014 define a named, reusable data source with its schema and extensions\n- **`query:`** \u2014 define a named query (source + view) for reuse\n- **`run:`** \u2014 execute a query (the "do it now" statement)\n- **`given:`** \u2014 declare model-level parameters supplied at run time (experimental, see Givens)\n\n```malloy\nimport "shared_model.malloy"\n\nsource: flights is duckdb.table(\'flights.parquet\') extend {\n measure: flight_count is count()\n}\n\nquery: carrier_summary is flights -> {\n group_by: carrier\n aggregate: flight_count\n}\n\nrun: carrier_summary\n```\n\nComments use `//` or `--` (both are line comments).\n\n## Sources\n\nA **source** is anything you can hand a SQL database and get a schema back \u2014 a table name, a SQL SELECT, or the output of another Malloy query. The columns in that schema become the source\'s initial fields (all dimensions).\n\n```malloy\nsource: flights is duckdb.table(\'flights.parquet\')\nsource: limited is duckdb.sql("""SELECT * FROM flights LIMIT 100""")\nsource: carrier_facts is carrier_summary -- a query used as a source\n```\n\nWhat makes sources central to Malloy is **extension**. The `extend` block lets you layer on dimensions, measures, views, joins, filters, primary keys, field restrictions, and renames. These extensions travel with the source \u2014 any query against it gets them for free.\n\n```malloy\nsource: flights is duckdb.table(\'flights.parquet\') extend {\n primary_key: id\n\n dimension: distance_km is distance * 1.609344\n\n measure:\n flight_count is count()\n total_distance is sum(distance)\n\n join_one: carriers with carrier\n join_one: origin_airport is airports on origin_airport.code = origin\n\n where: dep_time > @2001\n\n view: by_carrier is {\n group_by: carrier\n aggregate: flight_count, total_distance\n }\n}\n```\n\nSources can extend other sources, creating a refinement chain:\n\n```malloy\nsource: ca_flights is flights extend {\n where: origin.state = \'CA\'\n}\n```\n\nField access control uses `accept:` (allowlist) or `except:` (denylist) to restrict which inherited columns are visible. Fields can be renamed with `rename: new_name is old_name`.\n\n## Joins\n\nJoins are declared in the source, not reconstructed in every query. This is a fundamental design difference from SQL: the graph structure of your data is a property of the model.\n\n```malloy\njoin_one: carriers with carrier -- FK \u2192 PK shorthand\njoin_one: origin_airport is airports on origin_airport.code = origin -- explicit ON\njoin_many: line_items on line_items.order_id = id -- one-to-many\njoin_cross: other_table on other_table.key = key -- cross join\n```\n\n- `join_one` \u2014 the joined source has at most one row per source row (many-to-one or one-to-one)\n- `join_many` \u2014 the joined source has potentially many rows per source row\n- `join_cross` \u2014 a full cross product\n\nThe `with` shorthand requires the joined source to have a declared `primary_key`. All joins are left outer by default. There is no right join \u2014 Malloy\'s graph model doesn\'t need one.\n\n**Choosing `join_one` vs `join_many`:** Ask "for a single row in the base source, can the joined source match more than one row?" If yes \u2192 `join_many`. If no (or at most one) \u2192 `join_one`. The common mistake is reaching for `join_many` when joining a *lookup or summary table* (e.g., joining an inventory snapshot to a purchase history on a wine key). Even though the joined table may have many rows overall, if each base row resolves to *at most one* joined row, use `join_one`. Use `join_many` only when the join genuinely fans out the base rows \u2014 e.g., joining line items to orders, or notes to a wine catalog.\n\nWhen you reference a joined source\'s fields, you use dot notation: `carriers.nickname`, `origin_airport.state`. This is one of Malloy\'s most important abstractions: **the access path to nested data is identical regardless of how the nesting is physically stored.** An array of records embedded in a column, a `join_many` to a separate table, a record-typed column \u2014 all are navigated with the same dot notation. The SQL required to traverse these different physical arrangements varies wildly (unnesting arrays, LEFT JOINs, correlated subqueries, ARRAY_AGG), but Malloy hides all of that. You think about the logical shape of your data \u2014 "flights have carriers, carriers have a nickname" \u2014 and write `carriers.nickname`. The compiler figures out what SQL is needed to get there. This means you can restructure your physical schema (normalize a nested array into a separate table, or denormalize a joined table into a record column) without changing any of the Malloy that references that data.\n\n## Fields\n\nMalloy has four kinds of fields: **dimensions**, **measures**, **views**, and **calculations**.\n\n### Dimensions\n\nScalar expressions \u2014 they compute a value per row. All columns inherited from a table are dimensions. Computed dimensions reference other dimensions or columns:\n\n```malloy\ndimension: full_name is concat(first_name, \' \', last_name)\ndimension: is_long_haul is distance > 1000\n```\n\n### Measures\n\nAggregate expressions \u2014 they compute a value across a set of rows. A field is a measure when its defining expression contains an aggregate function (`count`, `sum`, `avg`, `min`, `max`):\n\n```malloy\nmeasure:\n flight_count is count()\n total_distance is sum(distance)\n avg_distance is avg(distance)\n pct_delayed is count() { where: dep_delay > 30 } / count()\n```\n\n**`count(expr)` counts distinct values.** Unlike SQL\'s `COUNT(DISTINCT expr)`, Malloy uses `count(expr)` for distinct counting. The `count(distinct expr)` form is a deprecated syntax that will produce an error. Use `count()` for total row count, `count(field)` for distinct values of that field:\n\n```malloy\naggregate:\n total_rows is count() -- all rows\n unique_carriers is count(carrier) -- distinct carriers\n```\n\nMeasures can be filtered inline with `{ where: ... }`, which is how you build things like "percent of flights delayed" without subqueries.\n\n### Views\n\nA view is a query saved into the source \u2014 a reusable transformation:\n\n```malloy\nview: by_carrier is {\n group_by: carrier\n aggregate: flight_count, total_distance\n limit: 10\n}\n```\n\nViews can reference other views from the same source as a starting point, and can be extended with `+`.\n\n### Calculations\n\nWindow functions over the grouped result. Calculations can only be defined in a query stage with `calculate:`, never in a source definition, because they depend on the output columns of the query:\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate: flight_count\n calculate: carrier_rank is rank()\n}\n```\n\n## Queries and Views\n\nA query pairs a source with a view (the transformation). Everything after the first `->` is the view.\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate: flight_count\n}\n```\n\n### Reduction vs. Projection\n\nEach stage of a view performs exactly one of:\n\n- **Reduction** \u2014 uses `group_by:` and/or `aggregate:` to reduce grain. Analogous to `SELECT ... GROUP BY` in SQL.\n- **Projection** \u2014 uses `select:` to pick fields without aggregation. Analogous to `SELECT` without `GROUP BY`.\n\nThese cannot be mixed in a single stage. A stage with `group_by:` cannot have `select:`, and vice versa.\n\n### Source-level definitions vs. query-level operations\n\nThe same `name is expression` syntax defines fields in both sources and queries:\n\n```malloy\n-- In a source (reusable):\nsource: flights is ... extend {\n measure: flight_count is count() -- defines a measure in the model\n}\n\n-- In a query (ad hoc):\nrun: flights -> {\n aggregate: flight_count is count() -- defines the same measure inline\n}\n```\n\nWhen used in a source, `measure:` and `dimension:` are **definition statements** \u2014 they add named fields to the source\'s schema. When used in a query, `group_by:`, `aggregate:`, `select:`, `nest:`, and `calculate:` are **query operations** \u2014 they specify what the query does. The field definitions are syntactically identical in both contexts, but the enclosing keyword determines the role:\n\n| Source keyword | Query keyword | What it holds |\n|---|---|---|\n| `dimension:` | `group_by:` or `select:` | scalar expressions |\n| `measure:` | `aggregate:` | aggregate expressions |\n| `view:` | `nest:` | sub-queries |\n| _(n/a)_ | `calculate:` | window functions |\n\nThis is why `measure` and `aggregate` are separate keywords. `measure:` is a *modeling* statement \u2014 "this source has a reusable aggregate computation called X." `aggregate:` is a *query* statement \u2014 "in this query, include these aggregate values in the output." A query\'s `aggregate:` can reference a previously defined measure by name, or define one inline. The distinction parallels the separation between defining a dimension in a source and using it via `group_by:` in a query.\n\n### Multi-stage Pipelines\n\nStages chain with `->`. Each stage\'s output becomes the next stage\'s source:\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate: flight_count is count()\n} -> {\n where: flight_count > 1000\n select: *\n}\n```\n\n### Refinement with `+`\n\nThe refinement operator `+` merges query operations together. It works both within a view and at the top level on a named query:\n\n```malloy\n-- Refining a view within a query:\nrun: flights -> by_carrier + { limit: 5 } + { nest: by_destination }\n\n-- Refining a named query at the top level:\nrun: carrier_summary + { group_by: origin } -- add origin grouping to existing query\n```\n\nWhen a dimension name appears as a bare reference, it expands to `{ group_by: name }`. A measure name expands to `{ aggregate: name }`:\n\n```malloy\nrun: flights -> carrier + flight_count + { limit: 10 }\n-- equivalent to: flights -> { group_by: carrier; aggregate: flight_count; limit: 10 }\n```\n\nFor multi-stage queries, refinement semantics get more complex \u2014 but for single-stage queries, `+` straightforwardly merges operations into the stage.\n\n### Nesting\n\n`nest:` embeds an aggregating subquery inside a reduction. Each row of the outer query gets a subtable from the nested query. Nests can nest arbitrarily deep:\n\n```malloy\nrun: flights -> {\n group_by: carrier\n aggregate: flight_count\n nest: top_routes is {\n group_by: origin, destination\n aggregate: flight_count\n limit: 3\n }\n}\n```\n\n### Other query operations\n\n- **`where:`** \u2014 filter rows (pre-aggregation). Comma-separated filters are ANDed.\n- **`having:`** \u2014 filter groups (post-aggregation), like SQL\'s HAVING.\n- **`limit:`** / **`order_by:`** \u2014 limit and sort output.\n- **`extend`** \u2014 add fields or joins to a source inline within a query expression.\n\n## Aggregate Locality (Symmetric Aggregates)\n\nThis is one of Malloy\'s most important features. In SQL, when you join tables and aggregate, you risk double-counting (the "fan trap"). Malloy solves this with **aggregate locality** \u2014 you specify *where in the join graph* an aggregation should be computed.\n\n```malloy\nrun: flights -> {\n aggregate:\n -- avg seats weighted by number of flights (locality: source, i.e. flights)\n avg_seats_per_flight is source.avg(aircraft.aircraft_models.seats)\n -- avg seats per aircraft model (locality: aircraft_models)\n avg_seats_per_model is aircraft.aircraft_models.seats.avg()\n}\n```\n\nThree syntactic forms:\n\n- `avg(expr)` \u2014 aggregate at the current source (implicit locality)\n- `joined_source.avg(expr)` \u2014 aggregate at the specified join point (explicit locality)\n- `joined_source.field.avg()` \u2014 shorthand for aggregating the field at its parent source\n\nFor `sum` and `avg` (asymmetric aggregates), when the expression crosses a join boundary, Malloy *requires* explicit locality \u2014 it won\'t silently give you a wrong answer. For `min`, `max`, and `count` (symmetric), locality doesn\'t change the result, so implicit is always fine.\n\nMalloy implements this with a technique called **symmetric aggregates** \u2014 it internally de-duplicates rows based on primary keys at the appropriate join level, so aggregations are always mathematically correct regardless of join fan-out.\n\n## Ungrouped Aggregates\n\n`all()` and `exclude()` allow computing aggregates at different grouping levels within a single query:\n\n```malloy\nrun: airports -> {\n group_by: state, faa_region\n aggregate:\n airport_count is count()\n total_airports is all(count()) -- ungrouped: total across all rows\n region_airports is all(count(), faa_region) -- grouped only by faa_region\n pct_of_total is count() / all(count())\n}\n```\n\n`all(expr)` removes all grouping. `all(expr, dim1, dim2)` keeps only the specified grouping dimensions. `exclude(expr, dim)` removes the specified dimension from grouping.\n\n**Important:** `all(expr, dim)` takes the **local alias name** as defined in the query\'s `group_by:`, not a dotted path. If you want to partition by a joined field, alias it first:\n\n```malloy\n-- WRONG: all(count(), director.primaryName) -- dot paths don\'t work here\n-- RIGHT:\nrun: movies -> {\n group_by: director is director.primaryName -- alias it\n aggregate:\n movies is count()\n director_total is all(count(), director) -- reference the alias\n pct is count() / all(count(), director)\n}\n```\n\n## Expressions\n\nMalloy expressions include arithmetic, comparison, logical operators, function calls, type casts, and several Malloy-specific forms.\n\n### Evaluation Spaces\n\nEvery expression has an evaluation space: **literal**, **constant**, **input**, or **output**. Input expressions reference source columns/dimensions. Output expressions reference the results of the current query stage (used in `calculate:`). Some functions constrain their arguments \u2014 e.g., `lag(expr)` requires an output expression, `avg(expr)` requires an input expression.\n\n### Application and Partial Comparison\n\nThe `?` operator applies a condition to a value. Partial comparisons are conditions without a left-hand side:\n\n```malloy\nwhere: state ? \'CA\' | \'NY\' -- state is \'CA\' or \'NY\'\nwhere: distance ? > 500 & < 2000 -- distance between 500 and 2000\n```\n\n`|` is alternation (OR), `&` is conjunction (AND) within partials.\n\n### Pick Expressions\n\nMalloy\'s equivalent of CASE:\n\n```malloy\ndimension: size_bucket is\n pick \'short\' when distance < 500\n pick \'medium\' when distance < 1500\n else \'long\'\n```\n\n### Filtered Aggregate Expressions\n\nAny aggregate can be filtered inline:\n\n```malloy\nmeasure: ca_flights is count() { where: origin.state = \'CA\' }\n```\n\n### Type Casting\n\n```malloy\ntotal_distance::string -- Malloy type cast\nname::"VARCHAR(32)" -- database-native type cast\n```\n\n### Time Literals and Ranges\n\n```malloy\n@2003 -- the year 2003\n@2003-Q2 -- second quarter of 2003\n@2024-01-15 10:30:00 -- timestamp literal\ndep_time ? @2003 to @2005 -- range comparison\nnow -- current timestamp\n```\n\n## Data Types\n\nMalloy\'s type system: `string`, `number`, `boolean`, `date`, `timestamp`, `timestamptz`, `json`, and `sql native` (for unsupported database types). Compound types: `type[]` for arrays, `{ name :: type, ... }` for records, nesting arbitrarily: `{ x :: number, tags :: string[] }[]`.\n\n## Annotations and Tags\n\nThese are related but distinct concepts.\n\n### Annotations\n\nAnnotations are **text strings** attached to objects during compilation. They are metadata \u2014 they never affect query execution or SQL generation. An annotation starts with `#` and continues to end of line:\n\n```malloy\n# bar_chart\nview: by_carrier is { ... }\n```\n\n- `#` annotations attach to the next object defined below them\n- `##` annotations attach to the model (the file)\n- Block annotations use `#|` ... `|#` for multi-line content (closing delimiter must match the column position of the opener)\n\nAnnotations distribute over definition lists:\n\n```malloy\n# currency\nmeasure: -- all three measures get the # currency annotation\n revenue is sum(amount)\n # percent -- this measure also gets # percent\n margin is revenue / cost\n cost is sum(amount)\n```\n\n### Tags (a use of annotations)\n\nTags are the primary *consumer* of annotation strings. They interpret annotation text using a structured property language (MOTLY). The key distinction: **annotations are the transport mechanism (raw strings attached to objects), tags are the interpretation layer (parsed key-value properties).**\n\nNot all annotations are tags. An annotation is just text. Tags are annotations that happen to be written in the tag property language and parsed by an application.\n\n### Annotation prefixes (routing)\n\nThe character(s) immediately after `#` route the annotation to different consumers:\n\n- `# ` (hash-space) \u2014 renderer tags, parsed by the Malloy VS Code extension for visualization (`# bar_chart`, `# line_chart`, `# shape_map`; `# link { url_template="https://\u2026/$$" }` turns a field\'s cell into a clickable deep link \u2014 `$$` is the cell value, `field=other` links on a different (often `# hidden`) field; `# image { url_template=\u2026 }` renders it as an image)\n- `##!` \u2014 compiler directives (e.g., `##! experimental.parameters`, `##! experimental.givens`)\n- `#"` \u2014 reserved for documentation strings\n- `#(appName)` \u2014 application-specific tags (e.g., `#(docs) hidden`)\n\n```malloy\n# bar_chart size=large -- renderer tag: tells VS Code how to render\n##! experimental.parameters -- compiler tag: enables a feature flag\n#(myApp) priority=high -- custom app tag: ignored by renderer/compiler\n```\n\n### Tag property syntax\n\n```\ntName -- boolean flag (exists = true)\ntName=value -- set property value\ntName=[a, b, c] -- array value\ntName: { p1=v1 p2=v2 } -- nested properties (replaces)\ntName { p1=v1 } -- nested properties (merges)\n-tName -- delete a property\ntName.sub.path=value -- deep path assignment\n```\n\nValues can be unquoted identifiers, quoted strings, numbers, or typed values prefixed with `@` (`@true`, `@false`, `@2024-01-15`).\n\n## Givens (Model-Level Parameters)\n\n**Status: experimental, gated by `##! experimental.givens`.** Naming is provisional.\n\nGivens are values supplied at run time that the model can reference in any expression. The motivating use case is row-level access control \u2014 a model written once with `where: x.tenant_id = $TENANT` and the tenant supplied per API call \u2014 but they also fit configuration values, session context, and any "one compiled model, many invocations with varying context" pattern.\n\nGivens are model-wide: a single namespace, one value per name per compilation. They are *complementary to* source/query parameters (`source: foo(x :: string) is ...`), not a replacement. Use a parameter when you want two differently-bound copies of the same source side-by-side in one model; use a given when you want one value visible everywhere in the compilation.\n\n### Declaration\n\nThe `given:` top-level statement introduces givens, with a name, a type, and an optional default:\n\n```malloy\ngiven:\n TENANT :: string\n MAX_ROWS :: number is 1000\n CUTOFF_DATE :: date is @2024-01-01\n```\n\nType can be any Malloy atomic type or compound type, including `filter<T>`:\n\n```malloy\ngiven:\n ROLE :: string\n ALLOWED_ROLES :: string[]\n SESSION :: { user_id :: string, tenant :: string }\n TENANT_FILTER :: filter<string>\n```\n\nDefaults are expressions over constants and other givens. Annotations attach to given declarations the same way they attach to sources or measures.\n\n### Reference: the `$` sigil\n\nInside any expression, a given is referenced with a leading `$`:\n\n```malloy\nsource: orders_for_user is orders extend {\n where: orders.tenant_id = $TENANT\n}\n\nquery: recent_orders is orders_for_user -> {\n where: order_date >= $CUTOFF_DATE\n limit: $MAX_ROWS\n}\n```\n\n`$` appears *only* at expression references. The other three sites where a given\'s name appears \u2014 declaration, import, and supply (caller side) \u2014 use the bare name, because syntactic position already disambiguates. Givens share the top-level declaration namespace with sources/queries/views, so `source: x is ...` plus `given: x :: string` is a name-conflict error.\n\n### Set membership: `expr in $arrayGiven`\n\nThe RHS of `in` is either a parenthesized list of expressions (`in (1, 2, x, y * 7)`, same as SQL) or a given with an array value (`in $ARR`). A bare array-typed expression \u2014 a dimension, a joined array field, an inline `[a, b, c]` literal \u2014 is *not* legal on the RHS; arrays only reach the RHS via the given form.\n\nWhen a given has array type, `expr in $ARR` tests `expr` against the runtime-bound array; `not in $ARR` is the negation. The left-hand side must match the array\'s element type (`string in $string[]`, `number in $number[]`, etc.); mismatches are translate-time errors. Records and nested arrays are out of scope.\n\n```malloy\ngiven:\n ALLOWED_STATES :: string[]\n URGENT_STATUSES :: string[]\n\nsource: orders extend {\n where: state in $ALLOWED_STATES\n dimension: is_urgent is order_status in $URGENT_STATUSES\n}\n```\n\nAt SQL emit, the array\'s contents land in a generated `IN (...)` clause. Empty or `null` arrays collapse to the obvious result (`IN` \u2192 `FALSE`, `NOT IN` \u2192 `TRUE`). NULL elements inside a non-empty array follow standard SQL `IN` semantics.\n\nTo derive a value from an array \u2014 typically a boolean gate \u2014 *without* the array itself reaching row-position SQL, use an inline given (below).\n\n### Inline givens\n\nAn `inline` given is evaluated at **bind time**, before SQL is emitted: its default expression runs against the resolved given values and reduces to a literal, and that literal is what reaches SQL.\n\n```malloy\ngiven:\n CAPABILITIES :: string[]\n inline CAN_READ_ORDERS :: boolean is \'read_orders\' in $CAPABILITIES\n inline CAN_MUTATE :: boolean\n is \'write_orders\' in $CAPABILITIES or \'admin\' in $CAPABILITIES\n\nsource: orders extend {\n where: $CAN_READ_ORDERS -- SQL sees: WHERE ... AND TRUE (or FALSE)\n}\n```\n\nThis is the **row-level access-control gate** pattern: the host supplies a capability list as a regular given, an inline given derives a boolean from it, and only the boolean \u2014 not the list \u2014 crosses into row-position SQL. The query planner sees a constant predicate.\n\nRules:\n\n- An inline given **must** have a default. `inline FOO :: number` with no `is` clause is a translate-time error.\n- The default may use:\n - Boolean and comparison operators: `and`, `or`, `not`, `=`, `!=`, `<`, `<=`, `>`, `>=`\n - The `in $array` test against another given\n - Literals (string, number, boolean, null, array) and references to other givens\n- The default cannot call SQL functions, reference fields, or use any operator outside that list. Disallowed operators are reported at translate time with the offending operator names.\n- Inline givens are filtered out of `Model.givens` and `PreparedQuery.givens` \u2014 they\'re computed, not supplied \u2014 so introspection-driven UIs don\'t render editors for them. A caller can still shadow one by binding it explicitly (useful in tests).\n- `inline` is a context-sensitive modifier, not a reserved keyword: fields, sources, views, dimensions, and joins can still be named `inline`.\n\n### Imports\n\nGivens behave like every other top-level named thing under import:\n\n- **Bare import** (`import "b.malloy"`) brings B\'s full export surface in, including all of B\'s givens, under their original names.\n- **Selective import** (`import { source1 } from "b.malloy"`) brings in only what\'s listed. To surface a given to your callers, list it: `import { source1, MAX_ROWS } from "b.malloy"`.\n- **Rename** uses the existing `LOCAL is REMOTE` form: `import { CAP is MAX_ROWS } from "b.malloy"`.\n\nSurfacing controls *who can supply a value*, not whether internal references work. An imported source can reference a given the importer didn\'t surface; the reference still resolves internally, and at run time the unsurfaced given relies on its declaration-site default.\n\nA common project convention is a shared `tenant_givens.malloy` (declaring `$TENANT`, `$USER_ROLE`, etc.) that every root file bare-imports on line 1, so the project\'s given contract is visible at the top of any model.\n\n### Satisfiability\n\nA query referencing `$X` is satisfiable if either `$X` is in the model\'s namespace (so a caller can supply a value) or `$X` has a default at its declaration site. Otherwise the query is unsatisfiable and errors. Latent definitions (views, dimensions, measures) that reference `$X` are fine if no query actually invokes them \u2014 satisfiability is a property of running queries.\n\n### Supplying values\n\nValues can be supplied at two layers, which compose (per-query overrides per-runtime):\n\n**Per-runtime** \u2014 bound to a `Runtime`, applied as defaults to every query through it. Two paths:\n\n1. **`givensPath` in `malloy-config.json`** points at a JSON file of `name \u2192 value`:\n ```jsonc\n { "givensPath": "./local-givens.json" }\n // or env-var indirection (resolved at config load):\n { "givensPath": { "env": "GAME_STORE_GIVENS" } }\n ```\n The values file is a flat JSON map, keys are caller-facing surface names:\n ```jsonc\n { "TENANT": "acme", "USER_ROLE": "admin", "CUTOFF_DATE": "2024-01-01" }\n ```\n\n2. **Direct on the Runtime constructor** (for per-request multi-tenant servers, tests, scripts):\n ```typescript\n const runtime = new Runtime({\n config,\n givens: { TENANT: claims.tenant_id, USER_ROLE: claims.role },\n urlReader,\n });\n ```\n Constructor values *merge over* the file at `givensPath` per-key.\n\n**Per-query** \u2014 supplied on a single `.run({ givens: ... })` call:\n```typescript\nawait query.run({ givens: { STATE_FILTER: "CA", LIMIT_OVERRIDE: 50 } })\n```\nAvailable on every compile-or-run entry point (`runtime.loadQuery(...).run(options)`, `preparedQuery.getPreparedResult(options)`, `preparedQuery.getSQL(options)`).\n\nThe resolved per-runtime values are exposed on `runtime.givens` (read-only) for diagnostics.\n\n### Finalized givens (security primitive)\n\nA multi-tenant deployment usually wants `TENANT`/`USER_ROLE`/`REGION` to be runtime-bound and **un-overridable per-query** \u2014 otherwise a downstream endpoint that accidentally accepts user-controlled query params and plumbs them into `.run({ givens: ... })` becomes a tenant-leak vulnerability.\n\n`finalizeGivens` in the config locks names at the API surface:\n\n```jsonc\n{\n "givensPath": { "env": "GAME_STORE_GIVENS" },\n "finalizeGivens": ["TENANT", "USER_ROLE", "REGION"]\n}\n```\n\nFinalize doesn\'t change *what* a given resolves to \u2014 only *who* can supply it. A `.run({ givens: { TENANT: ... } })` for a finalized name throws at API entry (named, not silently dropped). Finalized givens are filtered out of `Model.givens` and `PreparedQuery.givens` so introspection-driven UIs don\'t render editors for locked names.\n\n### JS shapes for supplied values\n\nBoth the JSON values file and per-query `givens` maps accept the same per-type shapes:\n\n| Malloy type | JS |\n|---|---|\n| `string` | string |\n| `number` | `number`, `bigint`, or string (precision escape hatch) |\n| `boolean` | boolean |\n| `date` | ISO date string `"2024-01-15"` |\n| `timestamp` (naive) | ISO string without offset \u2014 *not* a JS `Date` |\n| `timestamptz` | JS `Date` or ISO string with offset (string preferred \u2014 makes TZ choice visible) |\n| `T[]` | JS array |\n| `{ name :: T, ... }` | JS object |\n| `filter<T>` | JS string (Malloy filter expression source) |\n\nNaive timestamp givens reject `Date` because `Date` represents a UTC instant, not a wall-clock value, and `new Date("2001-01-01T00:00:00")` silently picks up the system\'s local TZ. Type mismatches throw at the boundary with a path that points at the offending location (e.g., `givens.SESSION.user_id: expected string, got number`). `null` is legal for any given type.\n\n### Introspection\n\n`Model.givens` and `PreparedQuery.givens` expose, to the host, the supplyable givens \u2014 for whole-model parameter editors and per-query "run this" forms respectively. Each entry carries name, type, default expression (or undefined if the caller must supply), location, and access to declaration-site annotations via `tagParse`/`getTaglines`.\n\n## How a Malloy Query Becomes SQL\n\nThe compilation pipeline has two phases:\n\n### Phase 1: Translation (source code \u2192 IR)\n\n```\nMalloy source \u2192 ANTLR lexer/parser \u2192 parse tree \u2192 AST builder \u2192 AST \u2192 IR generator \u2192 IR\n```\n\nThe **Intermediate Representation (IR)** is a plain, serializable data structure (JSON-compatible) that fully describes the semantic model and query. Note that IR is *not* dialect-agnostic \u2014 the same Malloy source compiled against different databases can produce different IR, because schema information, type mappings, and available functions vary by backend. It can be cached, transmitted, and reused. Key IR types:\n\n- **`SourceDef`** \u2014 a source\'s complete definition: schema, fields, joins, filters\n- **`Query`** \u2014 a source paired with a pipeline of operations\n- **`FieldDef`** \u2014 definition of any field (dimension, measure, join, calculation)\n- **`Expr`** \u2014 expression tree (arithmetic, comparisons, aggregates, function calls, field references)\n\nThe translator handles all language-level semantics: scoping, name resolution, type checking, evaluation space validation.\n\n### Phase 2: Compilation (IR \u2192 SQL)\n\n```\nIR \u2192 query compiler \u2192 expression compiler \u2192 dialect-specific SQL generator \u2192 SQL + metadata\n```\n\nThe compiler walks the IR query pipeline, translating each stage into SQL constructs (CTEs, subqueries, GROUP BY, window functions). A **Dialect** layer handles database-specific SQL generation.\n\nThe compiler also produces **metadata** alongside the SQL \u2014 structural information needed to interpret the result set (column types, nesting structure, annotation data). This metadata is what allows Malloy renderers to reconstruct nested/hierarchical results from the flat SQL result set and apply visualization tags.\n\n### Key architectural consequences\n\n- Because the IR is serializable, it can be cached and reused across compilations (though IR is database-specific \u2014 the same source compiled against different backends may produce different IR).\n- Because joins are declared in the source (not the query), the compiler knows the full join graph and can compute symmetric aggregates correctly.\n- Because nested queries are first-class, the compiler generates the appropriate SQL (correlated subqueries or ARRAY_AGG patterns depending on dialect) automatically.\n- Because measures are typed as aggregates in the IR, the compiler can validate that they only appear in aggregate context and enforce locality rules.\n\n## Where to Go Deeper\n\nThis document is a conceptual reference \u2014 enough to reason about the language and its design, but not exhaustive. Here\'s where to find more detail.\n\n### Language Documentation\n\nThe full docs live at [https://docs.malloydata.dev](https://docs.malloydata.dev). Key pages by topic:\n\n| Topic | URL |\n|---|---|\n| Sources, extensions, joins, primary keys | [documentation/language/source](https://docs.malloydata.dev/documentation/language/source) |\n| Queries, views, reduction vs projection | [documentation/language/query](https://docs.malloydata.dev/documentation/language/query), [views](https://docs.malloydata.dev/documentation/language/views) |\n| Fields: dimensions, measures, views, calculations | [documentation/language/fields](https://docs.malloydata.dev/documentation/language/fields) |\n| Aggregate functions and aggregate locality | [documentation/language/aggregates](https://docs.malloydata.dev/documentation/language/aggregates) |\n| Ungrouped aggregates (`all`, `exclude`) | [documentation/language/ungrouped-aggregates](https://docs.malloydata.dev/documentation/language/ungrouped-aggregates) |\n| Nested views / aggregating subqueries | [documentation/language/nesting](https://docs.malloydata.dev/documentation/language/nesting) |\n| Joins | [documentation/language/join](https://docs.malloydata.dev/documentation/language/join) |\n| Expressions, operators, pick, apply | [documentation/language/expressions](https://docs.malloydata.dev/documentation/language/expressions) |\n| Evaluation spaces (literal, constant, input, output) | [documentation/language/eval_space](https://docs.malloydata.dev/documentation/language/eval_space) |\n| Filters and filter placement | [documentation/language/filters](https://docs.malloydata.dev/documentation/language/filters) |\n| Annotations and tags | [documentation/language/tags](https://docs.malloydata.dev/documentation/language/tags) |\n| Calculations and window functions | [documentation/language/calculations_windows](https://docs.malloydata.dev/documentation/language/calculations_windows) |\n| Data types | [documentation/language/datatypes](https://docs.malloydata.dev/documentation/language/datatypes) |\n| Time operations, ranges, timezones | [documentation/language/timestamp-operations](https://docs.malloydata.dev/documentation/language/timestamp-operations), [time-ranges](https://docs.malloydata.dev/documentation/language/time-ranges), [timezones](https://docs.malloydata.dev/documentation/language/timezones) |\n| Imports | [documentation/language/imports](https://docs.malloydata.dev/documentation/language/imports) |\n| Top-level statements and model structure | [documentation/language/statement](https://docs.malloydata.dev/documentation/language/statement) |\n| Functions reference | [documentation/language/functions](https://docs.malloydata.dev/documentation/language/functions) |\n\n### Examples and Patterns\n\nThe docs site includes worked examples of common analytical patterns at [documentation/patterns](https://docs.malloydata.dev/documentation/patterns/): percent-of-total, year-over-year, cohort analysis, sessionization, moving averages, nested subtotals, and more.\n\nEnd-to-end guides are at [documentation/user_guides](https://docs.malloydata.dev/documentation/user_guides/), including [Malloy by Example](https://docs.malloydata.dev/documentation/user_guides/malloy_by_example) (a comprehensive walkthrough) and a three-part series for SQL users ([part 1](https://docs.malloydata.dev/documentation/user_guides/sql_experts1), [part 2](https://docs.malloydata.dev/documentation/user_guides/sql_experts2), [part 3](https://docs.malloydata.dev/documentation/user_guides/sql_experts3)).\n\n### Source Code\n\nThe Malloy implementation lives at [github.com/malloydata/malloy](https://github.com/malloydata/malloy). Key entry points:\n\n| What | Where |\n|---|---|\n| ANTLR grammar (lexer + parser) | `packages/malloy/src/lang/grammar/` |\n| AST node hierarchy | `packages/malloy/src/lang/ast/` |\n| Parse tree \u2192 AST builder | `packages/malloy/src/lang/malloy-to-ast.ts` |\n| IR type definitions | `packages/malloy/src/model/malloy_types.ts` |\n| IR \u2192 SQL compiler | `packages/malloy/src/model/` |\n| Dialect-specific SQL generation | `packages/malloy/src/dialect/` |\n| Tag/annotation parsing (MOTLY) | `packages/malloy-tag/` |\n| Renderer | `packages/malloy-render/` |\n| Architecture overview | `CONTEXT.md` (root and in each package) |\n',
341
317
  "language/pick.md": "---\ndescription: pick expressions \u2014 Malloy's CASE/if-then-else\n---\n\n`pick` is Malloy's equivalent of SQL `CASE WHEN`. Each branch is its own\n`pick` keyword; the `else` clause catches the remainder.\n\nThere are two forms of pick. In the first the `when` expression is any\nboolean expression.\n\n```malloy\n pick 'Female' when upper(first_name) in ('JENNIFER', 'ELIZABETH', 'AMY', 'JESSICA')\n pick 'Male' when upper(first_name) in ('JAMES', 'JOHN', 'ROBERT', 'MICHAEL')\n else 'Unknown'\n```\n\n## Example usage in a query\n\n```malloy\nrun: payments -> {\n group_by: tier is\n pick 'high' when total_amount > 10000\n pick 'medium' when total_amount > 1000\n else 'low'\n aggregate: payment_count is count()\n}\n```\n\n## Common mistakes\n\n- **Every branch needs its own `pick` keyword** \u2014 there is no `when \u2026 then`:\n ```malloy\n -- WRONG:\n pick 'a' when x = 1 'b' when x = 2 else 'c'\n\n -- RIGHT:\n pick 'a' when x = 1\n pick 'b' when x = 2\n else 'c'\n ```\n\n- **`else` is required** when the branches don't cover all cases \u2014 omitting it\n returns `null` for unmatched rows.\n",
342
- "language/who-is-asking.md": "---\ndescription: Per-user data with $MALLOYYO_EMAIL \u2014 the reserved given this server fills from the signed-in user, how to declare it, and how to run the model locally\n---\n\n# Who is asking \u2014 `$MALLOYYO_EMAIL`\n\nA model can scope what a query returns to the person running it. Declare the\nreserved given, then use it like any other:\n\n```malloy\n##! experimental.givens\ngiven:\n MALLOYYO_EMAIL :: string is ''\n\nsource: orders is duckdb.table('orders.parquet') extend {\n where: owner_email = $MALLOYYO_EMAIL\n}\n```\n\nEvery query against that model \u2014 the `query` tool, a dashboard tile, a saved\nquery, an ltool link \u2014 binds it to the signed-in user's address. Nothing else\nchanges: no per-user models, no filtered copies, no query rewriting.\n\n**The declaration is the opt-in.** A model that does not declare it is\nuntouched, because supplying a given a model never declared is an error in\nMalloy rather than a no-op.\n\n## What a caller cannot do\n\nA caller may not set it. A `givens: { \"MALLOYYO_EMAIL\": \"someone@else.com\" }`\non a `query` call, a dashboard's `?MALLOYYO_EMAIL=` URL, a value baked into a\ncomponent \u2014 all dropped before the query compiles, and the signed-in address\nbound instead. That is the whole point of the feature; do not design around it.\n\nFor the same reason it is not offered as a filter: `query(execute:false)` does\nnot list it among the givens to supply, and a dashboard renders no control for\nit.\n\n## The `MALLOYYO_` prefix is reserved\n\nTwo exist: `MALLOYYO_EMAIL` (the signed-in address) and `MALLOYYO_ROLES` (every\nrole that person holds, as a list \u2014 `where: department in $MALLOYYO_ROLES`).\nDeclaring any other `MALLOYYO_*` given is refused at publish: the prefix means\n\"a value this server vouches for\", and a `$MALLOYYO_ROLE` nothing fills would\nread as though it did. Name your own givens anything else.\n\n## The dataset decides whether it is supplied\n\nDeclaring the given is not enough. An admin ticks what a dataset is scoped by,\nand only then is the value supplied and locked. The two halves check each\nother:\n\n- tick it, and a model that does not declare it **cannot be published** \u2014 the\n data would be served unscoped;\n- declare it without the tick, and nothing supplies it, so your filter runs on\n the declaration default. `publish` says so in that case; do not ignore the\n line.\n\nThat is why the default matters so much (see Notes below): an unsupplied\n`:: string is ''` matches nothing, which is the safe way to be misconfigured.\n\n## Running it locally\n\nLocally there is no one asking, so a tenant-scoped query would come back\nempty \u2014 which looks exactly like a broken dashboard. Set the address in the\nenvironment instead:\n\n```bash\nMALLOYYO_EMAIL=you@example.com malloyyo dashboard dev\n```\n\n`malloyyo lint` needs nothing: it compiles, it does not run. Anything that\nactually runs a query refuses without a value and names the variable, rather\nthan showing you an empty page to debug. Change the address to see another\ntenant's view.\n\nNothing about the identity is committed. On a server the value comes from\nwhoever is signed in; the environment is only the local stand-in, because a\nserver's environment is ONE value for every request and would hand every user\nthe same tenant.\n\n## Not `malloyyo dashboard bundle`\n\nA bundled site has no one asking, and cannot have: there is no server, the\nmodel source is inlined into the page, and DuckDB-WASM fetches the data in the\nreader's own browser. Nothing supplies the identity there \u2014 the bundler only\nintrospects, and no environment travels into a static page. So a tenant-scoped\ndashboard bundles to a page that shows nothing.\n\nDo not answer that by loosening the default. `MALLOYYO_EMAIL :: filter<string>\nis f'\u2026'` with anything permissive publishes every row to every visitor, and the\nraw data is one fetch away regardless. **A model that filters by who is asking\nbelongs on an instance, not in a static bundle.**\n\n## Notes\n\n- Give it a default and make sure the default is the SAFE answer. Watch the\n type: `:: string is ''` matches no rows, which is right, but\n `:: filter<string> is f''` is an EMPTY FILTER, which matches EVERY row. The\n server refuses to run a query when it cannot supply the value (an account\n with no address, say) rather than let a default like that through \u2014 but the\n default is still what a local `dashboard dev` run and any non-server path\n will use, so write one that shows nothing.\n- Filtering belongs in the source (`extend { where: \u2026 }`), not in each query \u2014\n that way it holds for every query anyone writes against it, including ones\n an agent composes later.\n- It is a string, not a verified claim about identity beyond sign-in: it is the\n address the signed-in account carries.\n",
343
- "repo/branches.md": "---\ndescription: Branch previews \u2014 a repo's unpublished changes, compiled and usable here as repo@label:dataset; the three ways to make one, and what they're good for\n---\n\n# Branch previews\n\nA **preview** is a model repo with unpublished changes in it, compiled by this\ninstance with its own connections and usable as if it were published:\nqueries, `describe_source`, dashboards. Nothing about it is published. Only\nadmins can make or see one. The workflow for authoring with previews is in\n`yo_help(\"authoring/start\")`; this page covers previews themselves.\n\n## The address\n\nEach dataset in a preview gets an address:\n\n <repo>@<label>:<dataset> e.g. malloyyo_test@claude/returns:returns\n\nThe label is usually the branch name. Pass the address anywhere a dataset goes:\n\n- as `model_ref` to `describe_source` and `query`\n- as `dataset` to `show_dashboard`\n- in a browser, as `/datasets/<address, URL-encoded>/dashboard/<name>`. Every\n tool that makes a preview returns these links, so give them to the person.\n\nThe page shows a banner naming the preview and its commit. Queries against a\npreview make no share links.\n\n## Making one\n\n| From | Use | When |\n| --- | --- | --- |\n| Your clone (Claude Code on the web) | `preview_changes(repo, label, base, files, deleted)` | While authoring. Sends only your edits, committed or not; no push needed. |\n| A branch on GitHub | `fetch_branch(repo, branch)`, or **Fetch from GitHub** on the repo's page | To look at a branch someone else pushed. |\n| A local checkout with the CLI | `malloyyo publish --repo <owner/name> --branch` | Developing on your own machine. |\n\nEach answers with every dataset's compile result, `ok` or the error, plus its\naddress and dashboard links. A dataset that doesn't exist on this instance yet\ngets a preview like any other, which is how a new dataset is tried before it's\ncreated.\n\n## A snapshot, not a live view\n\nA preview shows what was sent or fetched. Making another preview with the same\nlabel replaces what that label's addresses show; older ones stay reachable by\ncommit SHA (`repo@<sha>:dataset`). So preview again after each round of edits,\nor fetch again after each push you want to see. `list_repos` lists each repo's\nlatest previews.\n\n## Then\n\nA preview never becomes the published version. The published version always\ncomes from the repo's published branch. To ship:\n\n1. Push the branch and open a pull request.\n2. `check_repo(repo, pull_request: <n>)` checks what merging would produce.\n3. The person merges.\n4. `publish_repo(repo)`, or the repo's GitHub hook, publishes.\n",
344
- "repo/convert-single-dataset.md": "---\ndescription: Move an old single-dataset repo (index.malloy at the root) to the datasets/ layout\n---\n\n# Convert a single-dataset repo\n\nThe old layout put `index.malloy` at the repo root. To move it under `datasets/`:\n\n1. **Pick the dataset's name.** It becomes the directory name and the published\n name, so use what the dataset is already called on the instance \u2014 renaming it\n here would publish a second dataset rather than update the first.\n\n2. **Move everything the model owns**, keeping `malloy-config.json` at the root:\n\n mkdir -p datasets/<name>\n git mv index.malloy *.malloy dashboards datasets/<name>/\n\n Leave at the root: `malloy-config.json`, `.mcp.json`, `.devcontainer/`,\n `.claude/`, `README.md`, and anything that is not the model.\n\n3. **Fix imports that reached outside the model.** Imports between files that\n moved together still resolve \u2014 they kept their relative positions. Only a path\n that pointed at something left behind needs editing, and it needs `../../`\n in front of it.\n\n4. **Verify before publishing:**\n\n malloyyo lint\n\n Lint reads the repo the same way the server does, so a clean lint here means\n the server will accept it. It names the file and line for anything that moved\n wrong.\n\n5. **Publish the repo**, not the dataset:\n\n malloyyo publish --repo <owner/name>\n\n The dataset already exists on the instance, so no `--create-datasets`. The\n name matching is what connects the moved directory to the dataset that was\n already there \u2014 which is why step 1 matters.\n\n### If the dataset is backed by GitHub rather than pushed\n\nAn instance that pulls from the repo needs to learn the dataset moved. The repo's\nlayout is re-read on every refresh, so pushing the converted repo and refreshing\nis enough \u2014 but the dataset's recorded directory is set when it is created. If\nthe refresh reports the dataset as **unpublished** (the repo no longer has its\nold directory) and the new directory as **unclaimed**, an admin updates the\ndataset's directory on the instance, or re-adds the repo.\n\nNothing is deleted either way: a dataset whose directory disappears keeps\nserving its last model until someone decides otherwise.\n\n---\n\n*This topic is transitional. It exists while repos built on the old\nsingle-dataset layout are still in the wild, and goes away with them \u2014 along with\nthe notice `lint` and `publish` print when they meet one.*\n",
345
- "repo/datasets.md": '---\ndescription: A model repo holds datasets under datasets/ \u2014 add one, or convert a single-dataset repo to the new layout\n---\n\n# Datasets in a model repo\n\nA model repo publishes **datasets**. Each one is a directory under `datasets/`,\nnamed after the directory:\n\n```\nmalloy-config.json connections \u2014 shared by every dataset\ndatasets/\n finance/\n index.malloy what THIS dataset publishes\n orders.malloy the model behind it\n dashboards/\n spend.malloy\n sales/\n malloy-config.json \u2026unless a dataset brings its own\n index.malloy\n dashboards/\nlib/ shared code, imported by relative path\n```\n\n`malloyyo init` scaffolds the repo and nothing else \u2014 no datasets. You add them.\n\n## The rules worth knowing before you start\n\n- **The directory names the dataset.** `datasets/finance/` publishes `finance`.\n The name is a slug \u2014 it is the URL, what a publish matches on, and what a role\n is granted against \u2014 so a directory that is not already one is converted:\n `datasets/the-look/` publishes `the_look`. `malloyyo lint` prints the name it\n will publish as, next to the directory.\n- **A dataset can say what to CALL it and what it IS**, at model scope in its\n `index.malloy`:\n\n ##" Deals, contacts and companies, as the sales team sees them.\n ## dataset { title="HubSpot CRM" }\n\n Note `##"` \u2014 two hashes. A `#"` attaches to whatever declaration follows it,\n so `#"` above the first source documents that SOURCE and leaves the dataset\n with no description. The description shows where someone is deciding whether\n they want this dataset, or who should see it \u2014 and in `list_sources`, so keep\n it to a sentence or two (`yo_help("develop/documenting-models")`).\n\n With no tag the title is derived from the name \u2014 `hub_spot` \u2192 "Hub Spot" \u2014\n so a dataset that says nothing still reads properly. Use the tag when the\n mechanical version is wrong: an acronym, a product\'s own capitalisation.\n The title is presentation ONLY. It is not unique, nothing is looked up by it,\n and changing it renames nothing.\n- **A dataset publishes exactly what its own `index.malloy` exports.** A source\n next door is not hidden from it, it is absent.\n- **`malloy-config.json` can be at the repo root or in a dataset.** At the root\n it is shared by every dataset. In a dataset it is that dataset\'s own \u2014 and it\n REPLACES the root\'s rather than adding to it, so a dataset that brings its own\n cannot reach a connection only the root declares. Nearest one wins.\n- **The repo publishes as a unit.** Every dataset is linted, and the server\n writes all of them or none.\n- **Never have both layouts.** A root `index.malloy` AND a `datasets/` directory\n is refused. A repo with a root `index.malloy` is the old single-dataset shape:\n `yo_help("repo/convert-single-dataset")`.\n\n## Add a dataset\n\n1. Make the directory and its dashboards folder:\n\n mkdir -p datasets/<name>/dashboards\n\n2. Write the model. Build it the way you build any model \u2014 compile a probe to\n read a schema, then write sources into files. `yo_help("develop/getting-started")`\n is the full procedure. Compile with paths relative to the REPO root:\n\n compile_file("datasets/<name>/orders.malloy")\n\n3. Write `datasets/<name>/index.malloy`, exporting what the dataset publishes:\n\n import { orders, PERIOD } from \'orders.malloy\'\n export { orders, PERIOD }\n\n Imports inside a dataset are relative to that dataset\'s directory, so\n `\'orders.malloy\'` is its sibling. Shared code one level up is\n `\'../../lib/orders.malloy\'`.\n\n4. Check the repo still publishes cleanly:\n\n malloyyo lint\n\n5. Publish:\n\n malloyyo publish --repo <owner/name> --create-datasets\n\n `--create-datasets` is only needed the first time a dataset appears.\n\n## Splitting one dataset into several\n\nOnly worth doing when the datasets really are separate \u2014 different people should\nsee different things, or one of them is scoped by who is asking and the others\nare not. A dataset is the unit of access: everything it publishes, a holder of\nits role gets.\n\nMove the sources for each into its own `datasets/<name>/`, put anything both need\nin `lib/`, and import it with `\'../../lib/<file>.malloy\'`.\n\n**Watch the givens.** A plain `import "../../lib/x.malloy"` brings that file\'s\n`given:` declarations with it, so a shared library that declares `MALLOYYO_EMAIL`\nmakes every dataset importing it scoped by the asker. Import selectively \u2014\n`import { orders } from \'../../lib/x.malloy\'` \u2014 when that is not what you want.\n\n## Trying a change before it\'s published\n\nWork on a branch and preview it here: `yo_help("repo/branches")`.\n',
346
- "site/auto-update.md": '# Auto-update a data site weekly\n\nAdd a scheduled GitHub Actions job that rebuilds the data and commits it, so the\npublished Pages site stays current on its own. Use this **after** the site works\n(built with `yo_help("site/data-site")`). If the data never changes, skip this.\n\nThe worked example is `malloydata/malloyyo-imdb` \u2014 fetch and read its\n`scripts/build_data.sh` and `.github/workflows/refresh-data.yml`; adapt, don\'t\ncopy blindly.\n\n## Precondition: one command that rebuilds the data\n\nThe whole thing rests on a single script that turns the source URL(s) into the\ncommitted parquet \u2014 the same script you\'d run by hand. Keep it linear so it\nreads as a recipe:\n\n```bash\n# scripts/build_data.sh\nset -euo pipefail\ncd "$(dirname "$0")/.."\nbash data/get.sh # 1. download source URLs -> data/\nrm -f data/build.duckdb\nmalloy-cli -c malloy-build.json build transform.malloy # 2. transform\necho "ATTACH \'data/build.duckdb\' AS b (READ_ONLY); -- 3. export -> docs/*.parquet\n COPY b.thing TO \'docs/thing.parquet\' (FORMAT parquet)" | malloyyo sql\n```\n\n(If you used Path A \u2014 direct \u2014 the whole script is just the one\n`echo "COPY (FROM read_..(\'https://\u2026\')) TO \'docs/\u2026\'" | malloyyo sql` command.\nNo `data/get.sh`, `malloy-build.json`, `malloy-cli`, or transform needed \u2014 and\nno standalone `duckdb` either, since `malloyyo sql` uses the embedded one.)\n\nGitignore the working files: `data/*.gz`, `data/*.duckdb`, `MANIFESTS/`.\n\n## The workflow\n\n`.github/workflows/refresh-data.yml`:\n\n```yaml\nname: refresh-data\non:\n schedule:\n - cron: "0 6 * * 0" # weekly, Sunday 06:00 UTC\n workflow_dispatch: # ...and on demand from the Actions tab\njobs:\n refresh:\n runs-on: ubuntu-latest\n permissions:\n contents: write # so the job can commit + push\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-node@v4\n with: { node-version: "20" }\n # malloyyo carries its own DuckDB (`malloyyo sql`), so no duckdb CLI to install.\n # Add `@malloydata/cli` only for a `#@ persist` transform (malloy-cli build).\n - run: npm install -g @malloydata/malloyyo @malloydata/cli\n - uses: actions/setup-python@v5 # only if an enrichment step needs it\n with: { python-version: "3.12" }\n - name: Build data\n run: bash scripts/build_data.sh\n - name: Commit refreshed data\n run: |\n git config user.name github-actions\n git config user.email github-actions@github.com\n git add docs/*.parquet\n git commit -m "refresh data $(date -u +%F)" || exit 0 # unchanged = clean no-op\n git push\n```\n\n## Hard-won details (these came from a real first run)\n\n- **`git commit \u2026 || exit 0`** \u2014 an unchanged week means nothing new upstream.\n That is success, not a failed job.\n- **Secondary/enrichment steps must be best-effort.** If the build has a step\n that can fail independently (an external API lookup, an optional metadata\n enrichment) and it isn\'t essential to the data, mark it\n `continue-on-error: true`. Otherwise one flaky API call throws away an\n otherwise-good data refresh \u2014 the commit step never runs and the fresh parquet\n is lost. (In `malloyyo-imdb` this bit us: a poster-image lookup with a missing\n secret failed the whole job until it was made non-blocking.)\n- **Secrets** go in repo settings (Settings \u2192 Secrets and variables \u2192 Actions,\n or `gh secret set NAME`), referenced as `${{ secrets.NAME }}`. A step reading\n a secret that isn\'t set gets an empty string \u2014 pair that with best-effort.\n- **No re-bundle needed for data changes.** The dashboards fetch parquet at\n runtime, so committing fresh parquet updates the live site. Only install\n `@malloydata/malloyyo` and run `malloyyo dashboard bundle` in CI if the job\n also needs to regenerate the HTML (i.e. dashboard code changed \u2014 rare for a\n data refresh).\n- **Test before trusting the schedule.** Push, then Actions tab \u2192 the workflow \u2192\n **Run workflow** (that\'s `workflow_dispatch`). Or `gh workflow run\n refresh-data.yml`, then `gh run watch <id> --exit-status`.\n\n## Git growth, and the flatten\n\nEach committed refresh adds the full parquet to history (~its file size per\nrun). That is intentional simplicity, not a leak. When history gets too big,\nflatten it to a single commit by hand \u2014 **not** as part of the weekly job:\n\n```bash\ngit checkout --orphan flat && git add -A && git commit -m "flatten history"\ngit branch -M flat main && git push -f origin main\n```\n\nOnly do this on a repo you solely own (it force-pushes; other clones must\n`git reset --hard origin/main`). Run it as often or as rarely as you like.\nDocument this in the repo\'s README so future-you remembers it\'s available.\n\n## Done when\n\n- The workflow file is on the default branch (so `workflow_dispatch` shows up)\n- A manual run goes green end-to-end and commits fresh `docs/*.parquet`\n- The Pages site shows the new data\n',
347
- "site/data-site.md": '# Build a public data site from a web data pointer\n\nGoal: given one or more **public data URLs**, produce a **GitHub Pages site** of\ninteractive Malloy dashboards that anyone can open in a browser. The data ends\nup as parquet in `docs/`; the dashboards are static HTML that query it\nclient-side with DuckDB-WASM \u2014 so there is no server, no database to run.\n\nTwo reference repos \u2014 read them, they are the ground truth for structure:\n\n- **`malloydata/malloyyo-babynames`** \u2014 the clean base pattern (one model file,\n a few dashboards, `docs/`). Data is static.\n- **`malloydata/malloyyo-imdb`** \u2014 the same, plus a `transform.malloy` that\n cleans raw source files into parquet, plus a **weekly auto-refresh** (that\n part is `yo_help("site/auto-update")`).\n\nFetch either with `gh api repos/<repo>/git/trees/HEAD?recursive=1` and read the\nfiles you need. Match their layout rather than inventing your own.\n\n## The shape of a finished repo\n\n```\nmalloy-config.json connection(s): duckdb (local), optionally md/gs mirrors\nindex.malloy the EXPORT SURFACE \u2014 only what this file exports is live\n<model>.malloy sources, measures, joins, givens (parameters)\nstorage.malloy sources point at the parquet \u2014 docs-local OR an https URL\n (or gs.malloy / md.malloy) same source names, swappable hosting (step 3)\ndashboards/*.malloy the query behind each dashboard\ndashboards/*.jsx the dashboard layout (grid of charts/tables)\ndocs/ PUBLISHED SITE \u2014 bundled HTML (+ the *.parquet if docs-local)\n *.parquet the data, when hosted docs-local (committed; served by Pages)\n *.html .nojekyll written by `malloyyo dashboard bundle`\n.mcp.json written by `malloyyo init` (author-mode Claude)\n```\n\n## Prerequisites (install once)\n\n```bash\nnpm install -g @malloydata/malloyyo # the `malloyyo` command\n```\n\nThat\'s the whole toolchain for the common case. `malloyyo` has **DuckDB built\nin** \u2014 `malloyyo sql` runs SQL (read a URL, `COPY` to parquet) through it, so you\ndo **not** need a standalone `duckdb` CLI.\n\nAdd `@malloydata/cli` (`malloy-cli`) **only** if you do a heavier transform with\nMalloy `#@ persist` (see Path B in `yo_help("site/data-to-parquet")`):\n\n```bash\nnpm install -g @malloydata/cli # only for #@ persist transforms\n```\n\n## Recipe\n\nWork top to bottom. After each step, prove it before moving on.\n\n### 1. Scaffold\n\n```bash\nmkdir my-site && cd my-site && git init\nmalloyyo init # writes .mcp.json (author-mode Claude) + index.malloy stub\n```\n\nCreate `malloy-config.json` with a local DuckDB connection (this is what reads\nthe parquet):\n\n```json\n{ "connections": { "duckdb": { "is": "duckdb" } } }\n```\n\n### 2. Get the web data into `docs/*.parquet`\n\nThis is the one dataset-specific step. Two paths \u2014 pick the simpler one that\nworks. Full detail and copy-paste commands: **`yo_help("site/data-to-parquet")`**.\n\n- **Direct** (default): `malloyyo sql` reads the URL and writes parquet in one\n shot, through the embedded DuckDB:\n ```bash\n echo "COPY (FROM read_csv_auto(\'https://\u2026/thing.csv\')) TO \'docs/thing.parquet\'" | malloyyo sql\n ```\n Use when the web data is already close to what you want to show.\n- **Transform** (when you need to clean / join / rank / reshape): write a\n `transform.malloy` with `#@ persist` sources and build it with `malloy-cli`,\n then export the tables to `docs/*.parquet`. This is the `malloyyo-imdb`\n pattern.\n\nVerify: `malloyyo sql -e "DESCRIBE SELECT * FROM \'docs/thing.parquet\'"` and a\n`SELECT count(*)`.\n\n### 3. Write the model\n\nA storage file \u2014 one source per parquet file \u2014 that the rest of the model builds\non. **Where the parquet lives is a choice** (the two examples differ here):\n\n- **docs-local** (the `malloyyo-imdb` way) \u2014 parquet committed in `docs/`,\n served same-origin by Pages. Self-contained; git carries the data. Address it\n by project-relative path so the same spelling works locally and published:\n ```malloy\n // storage.malloy\n source: thing_table is duckdb.table(\'docs/thing.parquet\') extend {}\n ```\n- **External URL** (the `malloyyo-babynames` way \u2014 it uses `import "gs.malloy"`)\n \u2014 parquet hosted on GCS / a CDN / any https URL; `docs/` holds only the HTML,\n so git stays small. DuckDB-WASM fetches the URL at runtime:\n ```malloy\n // gs.malloy\n source: thing_table is duckdb.table(\'https://storage.googleapis.com/\u2026/thing.parquet\') extend {}\n ```\n\nKeep the **source names identical** across storage files (as babynames does with\n`gs.malloy` / `md.malloy`) so switching hosting is a one-line import change in\nthe model. Start docs-local (simplest); move to a URL if git growth bites.\n\n`<model>.malloy` \u2014 build real sources on top: primary keys, measures, joins,\nand **givens** (the parameters that become the dashboard\'s filter controls).\n`index.malloy` \u2014 re-export exactly the sources/queries/givens the dashboards\nuse. **Only what `index.malloy` exports is visible** to dashboards, `dashboard\ndev`, and the hosted app.\n\nGive each exported source a `#"` doc string: one sentence on which questions it\nanswers. It\'s what `list_sources` shows the hosted app and any MCP client, for\nevery source, on every question \u2014 so keep it short, and put how to query the\nsource (grain, the measure to prefer, a subtle meaning) in `#(agent)` lines,\nwhich `describe_source` shows. Sizes and examples:\n`yo_help("develop/documenting-models")`.\n\nFor Malloy modeling and givens specifics, lean on the author MCP rather than\nguessing: the repo\'s `.mcp.json` wires `mcp__malloyyo_author__*`. Call\n`mcp__malloyyo_author__compile` to check files and\n`mcp__malloyyo_author__yo_help` for topics (`develop/working-with-models`).\n\nThree shapes that compile, pass `lint`, and still produce a dashboard that looks\nright and isn\'t:\n\n- **A stage-level `where:` zeroes measures that carry their own filters.**\n `count() { where: status = \'Sold\' }` needs the sold rows to reach it; a\n `where: in_cellar` on the stage removes them first and the measure reads 0\n everywhere. Constrain the output with `having:` instead.\n- **Grouping finer than the fact scatters the counts.** Group by an attribute\n that only applies to some rows and the measures over the others split across\n groups and read near-zero. Pick the grain the question is asked at; if you\n need both, group at the coarser one and `nest:` the finer.\n- **Detail tables default to raw field names and bare numbers.** `exit_date` and\n `829.57`, and a null renders as `\u2205`. Tag them \u2014 `# label="Opened"`,\n `# label="Paid" currency` \u2014 and `coalesce(field, \'\')` where empty is\n meaningful rather than missing.\n\nAggregate locality is NOT one of these: Malloy\'s symmetric aggregates keep\nmeasures honest through a `join_many` fan-out, and it warns (or errors) rather\nthan silently answering when an `avg`/`sum` crosses a join without explicit\nlocality. `notes.rating.avg()` already averages at the notes grain; ask for\n`source.avg(notes.rating)` only when you want the fan-out-weighted number. See\n`yo_help language/aggregate-locality-symmetric-aggregates`.\n\n### 4. Author dashboards and preview live\n\nEach dashboard is **one self-contained `dashboards/<name>.malloy`** \u2014 the query,\nits filtering, and the tags that lay it out. The filename is the dashboard\'s\nname and URL slug.\n\n**A `.jsx` is OPTIONAL and most dashboards don\'t need one.** The default form \u2014\nan inline query tagged `# artifact` + `# dashboard { columns=6 }` \u2014 renders KPI\ntiles and a card grid with no React at all. Reach for a sibling\n`dashboards/<name>.jsx` only when you want bespoke layout or presentation the\ntags can\'t express (a hand-built card, a picker, a Vega chart).\n\nAuthor with the `malloyyo_author` MCP and its `yo_help` topics \u2014 **read these,\ndon\'t guess the API**: `dashboards/authoring` (the dashboard file),\n`dashboards/grid-layout` (colspans), `dashboards/charts` (chart tags and their\nchannel rules), `dashboards/givens-and-controls` (filters),\n`dashboards/custom-components` and `dashboards/vega-charts` (only if you add a\n`.jsx`).\n\nPreview in a browser with live reload:\n\n```bash\nmalloyyo dashboard dev # serves at http://localhost:4173\n```\n\nTwo things about `dashboard dev` worth knowing:\n\n- It runs the queries **server-side**, through the same local DuckDB the CLI\n uses \u2014 the browser only renders results. So it works without DuckDB-WASM or\n its CDN extensions, and it is the only way to see a custom component render\n against real data short of publishing.\n- It holds **one long-lived connection set with a warm schema cache** (a\n deliberate tradeoff \u2014 refetching schemas per compile reads like a hang on a\n warehouse). The file watcher hot-reloads your `.malloy` edits and re-discovers\n `# artifact` tags, but nothing invalidates that cache, so a change to the\n DATA\'s shape \u2014 a new column in a parquet \u2014 needs a restart. The tell is\n `\'<column>\' is not defined` in the browser while the CLI and `lint` are green.\n\nIterate here until the dashboards look right. **Look at every dashboard before\nyou call it done**: `malloyyo lint` compiles the dashboards against the model but\ndoes not render them, so it cannot see a chart that throws at render time, a\ncomponent whose CSS resolved to nothing, or a column of raw field names.\n`malloyyo test` previews what the hosted claude.ai app would see.\n\n### 5. Build the static site\n\n```bash\nmalloyyo dashboard bundle --out docs\n# optional: add analytics + a title\nmalloyyo dashboard bundle --out docs --title "My Site" --analytics G-XXXXXXXXXX\n```\n\n`bundle` writes the HTML, `.nojekyll`, and assets into `docs/`, next to the\nparquet from step 2. The pages fetch `./*.parquet` relative to the site root, so\nthe data must already be in `docs/` \u2014 always run the data step before bundling.\n\n### 6. Publish on GitHub Pages\n\nCommit `docs/` and turn on Pages (Settings \u2192 Pages \u2192 Deploy from a branch \u2192\n`main` / `docs`). Full steps + gotchas: **`yo_help("site/github-pages")`**.\n\n### 7. (Optional) Keep it fresh automatically\n\nIf the data comes from a URL that updates over time and you want the site to\ntrack it, add a weekly GitHub Actions refresh \u2014 see\n**`yo_help("site/auto-update")`** (worked example: `malloydata/malloyyo-imdb`).\n\n## Done when\n\n- `malloyyo sql -e "SELECT count(*) FROM \'docs/<file>.parquet\'"` returns real rows\n- `malloyyo lint` passes\n- **you have LOOKED at every dashboard** in `malloyyo dashboard dev` \u2014 each one\n renders with no console errors, every tile has data, and the labels read like\n English rather than column names. `lint` passing is not this; a dashboard can\n compile and still throw at render time.\n- `docs/` has the bundled `*.html` + `.nojekyll` alongside the parquet\n- the Pages URL loads and the dashboards populate (data fetch succeeds)\n',
348
- "site/data-to-parquet.md": '# Getting web data into `docs/*.parquet`\n\nThe site queries parquet files (in `docs/`, or at an https URL \u2014 see the model\nstep). This is how you turn a public data URL into that parquet. Pick the\nsimplest path that produces clean data.\n\n`malloyyo sql` runs SQL through malloyyo\'s **embedded DuckDB** \u2014 no standalone\n`duckdb` binary. It takes SQL from `-e`, `-f <file>`, or stdin, and runs against\na connection from `malloy-config.json` (default `duckdb`).\n\n## Path A \u2014 Direct (default)\n\nOne command reads the URL and writes parquet. Best when the web data is already\nclose to what you want to display.\n\n```bash\n# CSV / TSV\necho "COPY (SELECT * FROM read_csv_auto(\'https://example.com/data.csv\'))\n TO \'docs/data.parquet\' (FORMAT parquet)" | malloyyo sql\n\n# TSV, gzipped, tab-delimited, header row (IMDb-style)\necho "COPY (SELECT * FROM read_csv_auto(\'https://example.com/data.tsv.gz\',\n delim=\'\\t\', header=true, all_varchar=true))\n TO \'docs/data.parquet\' (FORMAT parquet)" | malloyyo sql\n\n# JSON / NDJSON\necho "COPY (SELECT * FROM read_json_auto(\'https://example.com/data.json\'))\n TO \'docs/data.parquet\' (FORMAT parquet)" | malloyyo sql\n\n# Already parquet on the web \u2014 just fetch it\ncurl -fsSL -o docs/data.parquet \'https://example.com/data.parquet\'\n```\n\nFor anything longer than a line or two, put the SQL in a file and run it with\n`-f`, so it\'s re-runnable and diffable:\n\n```bash\nmalloyyo sql -f scripts/build.sql # a file of ;-separated statements\n```\n\nNotes:\n- DuckDB autoloads `httpfs` for `https://` reads.\n- Keep only the columns/rows the dashboards need \u2014 `SELECT` the columns and add a\n `WHERE` to drop noise. Smaller parquet = faster page loads.\n- Cast types here if the source is all-strings: `col::INT`, `col::DOUBLE`, etc.\n\n## Path B \u2014 Transform with Malloy (when you need to reshape)\n\nUse when the data needs cleaning, joining across files, ranking, or nesting \u2014\nthe `malloydata/malloyyo-imdb` case. You write the transform once in Malloy;\n`malloy-cli build` materializes it; you export the tables to parquet. This path\nalso needs `@malloydata/cli` (`npm install -g @malloydata/cli`).\n\n**1. A build connection** \u2014 `malloy-build.json` (a DuckDB db just for building):\n\n```json\n{ "connections": { "build": { "is": "duckdb", "databasePath": "data/build.duckdb" } } }\n```\n\n**2. `transform.malloy`** \u2014 read the raw source(s) through the `build`\nconnection and mark each output source with `#@ persist name="\u2026"`:\n\n```malloy\n##! experimental.persistence experimental.virtual_source\n\nsource: raw is build.sql("""\n SELECT * FROM read_csv_auto(\'data/raw.csv.gz\', delim=\'\\t\', all_varchar=true, header=true)\n""")\n\n#@ persist name="thing"\nsource: thing_base is raw -> {\n where: some_count::number > 100\n select: id, name, value is value::number\n calculate: rank is rank() { order_by: value::number desc }\n}\n```\n\nDownload the raw files first (a `data/get.sh` that `wget`s the URLs into `data/`,\ngitignored). Gitignore `data/`, `data/*.duckdb`, and `MANIFESTS/`.\n\n**3. Build, then export the persisted tables to `docs/`** \u2014 the export still\ngoes through `malloyyo sql` (no standalone duckdb needed):\n\n```bash\nrm -f data/build.duckdb\nmalloy-cli -c malloy-build.json build transform.malloy # -> tables in build.duckdb\necho "ATTACH \'data/build.duckdb\' AS b (READ_ONLY);\n COPY b.thing TO \'docs/thing.parquet\' (FORMAT parquet)" | malloyyo sql\n```\n\nThe persist `name=` is the table name inside `build.duckdb`; the `COPY` names the\nserved file (they can differ \u2014 e.g. `thing` \u2192 `docs/mysite_thing.parquet`).\n\nWrap steps 1\u20133 in a single `scripts/build_data.sh` so it is one command, by hand\nand in CI. That\'s exactly what `yo_help("site/auto-update")` automates weekly.\n\n## Either way, verify\n\n```bash\nmalloyyo sql -e "DESCRIBE SELECT * FROM \'docs/thing.parquet\'"\nmalloyyo sql -e "SELECT count(*) FROM \'docs/thing.parquet\'"\n```\n\nThen point a storage source at it (docs-local shown; an https URL works too \u2014\nsee the model step in SKILL.md):\n\n```malloy\nsource: thing_table is duckdb.table(\'docs/thing.parquet\') extend {}\n```\n',
349
- "site/github-pages.md": '# Publishing the site on GitHub Pages\n\nThe published site is just the `docs/` directory: bundled HTML plus the parquet\nit queries. GitHub Pages serves it directly \u2014 no build step on GitHub\'s side.\n\n## One-time setup\n\n```bash\n# from the repo root, after `malloyyo dashboard bundle --out docs`\ngh repo create <owner>/<name> --public --source=. --remote=origin # or an existing repo\ngit add -A\ngit commit -m "initial data site"\ngit push -u origin main\n```\n\nTurn on Pages, pointing at the `docs/` folder on the default branch:\n\n```bash\ngh api -X POST repos/<owner>/<name>/pages \\\n -f \'source[branch]=main\' -f \'source[path]=/docs\'\n```\n\n(Or in the UI: Settings \u2192 Pages \u2192 Source: **Deploy from a branch** \u2192 Branch\n`main`, folder `/docs`.)\n\nThe site appears at `https://<owner>.github.io/<name>/` within a minute or two.\n\n## Why `docs/` and why `.nojekyll`\n\n- Serving from `/docs` on the main branch keeps the data committed **once**\n (it\'s the same directory you build into), not duplicated on a separate branch.\n- `malloyyo dashboard bundle` writes a `.nojekyll` file so Pages serves the\n bundled assets as-is instead of running them through Jekyll (which would drop\n files beginning with `_`). Keep it committed.\n\n## Updating the site\n\nRe-run the data step and the bundle, then commit `docs/`:\n\n```bash\nbash scripts/build_data.sh # or your Path-A duckdb command \u2192 docs/*.parquet\nmalloyyo dashboard bundle --out docs\ngit add docs && git commit -m "update" && git push\n```\n\nBecause the dashboards fetch the parquet client-side, **committing fresh parquet\nis enough to update the live data** \u2014 you only need to re-`bundle` when you\nchange dashboard code. To automate the data refresh weekly, see the\n`yo_help("site/auto-update")`.\n\n## Gotchas\n\n- **Data must be in `docs/` before you bundle** \u2014 the pages fetch `./*.parquet`\n relative to the site root; `bundle` also reads the parquet to get schemas.\n- **Big parquet grows git history.** Each committed refresh adds the full file.\n Fine for occasional updates; for frequent auto-refresh, see the flatten note\n in `yo_help("site/auto-update")`.\n- **Git LFS does not work with Pages "deploy from a branch"** \u2014 Pages serves the\n LFS pointer text, not the file. Commit parquet as normal git objects.\n- **Private repos**: Pages on private repos needs a paid plan. Use a public repo\n for a public site.\n',
350
318
  "writing-malloy-with-mcp.md": "---\ndescription: How to write Malloy over an MCP surface \u2014 the compiler-in-the-loop discipline, common errors, and givens. Tool-agnostic; read once.\n---\n# Writing Malloy over MCP\n\nMalloy is a semantic language: a source already carries measures, dimensions,\nviews, and joins, and the compiler typechecks every query against them. The\nsingle most useful habit is **let the compiler be ground truth** \u2014 don't guess\nsyntax or field names. Read the source's shape first, validate before you run,\nand read the `problems[]` the surface returns.\n\nThe exact tools differ by surface (an explore surface exposes describe + query;\nan authoring surface adds compile/prettify), but the loop is the same:\n\n1. **Read the shape.** Describe the source you're querying \u2014 its measures,\n dimensions, views, and joins. The model usually already defines the\n aggregation you want; reuse it instead of re-deriving it.\n2. **Validate, then run.** Compile/validate the query first (no execution) to\n confirm it typechecks and to see the generated SQL or the givens it needs;\n fix any `problems[]`, then execute to get rows.\n3. **Recover from problems[].** Every failure \u2014 parse, field-not-found,\n aggregate-locality, runtime \u2014 comes back as a uniform `problems[]` with a\n `code` and (when known) a `help_topic`. Pull that topic with `yo_help`.\n\n## Common errors and how to read them\n\n- **Unknown field** \u2014 describe the source and check its dimensions / measures /\n views / joins for what actually exists. A join rendered by `source_ref` is\n described under that name in the same response.\n- **Aggregate locality** \u2014 `sum(joined.x)` across a join needs explicit\n locality: `source.sum(joined.x)` or `joined.x.sum()`.\n- **Mixed reduction / projection** \u2014 one query stage is either\n `group_by:`/`aggregate:` OR `select:`, never both.\n- **Calculation in a source** \u2014 `calculate:` (window functions) lives in\n queries, not in source definitions.\n\n## Givens (`$NAME` parameters)\n\nSome models declare given parameters (`$TENANT`, `$MAX_ROWS`, \u2026). Validate a\nquery with execution off to learn which givens it references (with their types\nand whether a default exists), then supply values keyed by surface name (no\n`$`). A given with a default is optional; one without must be supplied. For the\nper-type value shapes (dates as ISO strings, records as objects, `filter<T>` as\na Malloy filter string, \u2026) pull `yo_help(\"givens\")` \u2014 don't guess; the compiler\nvalidates and points at the offending field.\n\n## Before writing non-trivial Malloy\n\nBrowse the `language/*` topics first (start with `yo_help(\"language/overview\")`).\nThe language has real scoping and typing rules the compiler enforces \u2014 reading\nthe reference beats guessing.\n"
351
319
  };
352
320
  var prompts = {
@@ -400,6 +368,12 @@ var prompts = {
400
368
  }
401
369
  }
402
370
  };
371
+ var packs = [contentFiles];
372
+ var cachedIndex = null;
373
+ function addHelpContent(files) {
374
+ packs.push(files);
375
+ cachedIndex = null;
376
+ }
403
377
  function slugify(s) {
404
378
  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
405
379
  }
@@ -441,17 +415,18 @@ function splitReference(ns, raw, out) {
441
415
  }
442
416
  function buildIndex() {
443
417
  const topics = [];
444
- for (const [key, raw] of Object.entries(contentFiles)) {
418
+ const merged = Object.assign({}, ...packs);
419
+ const entries = Object.keys(merged).sort().map((key) => [key, merged[key]]);
420
+ for (const [key, raw] of entries) {
445
421
  if (key === LANGUAGE_REFERENCE) {
446
422
  const ns = nameFromKey(key.replace(/\/[^/]+$/, ""));
447
- splitReference(ns, raw, topics);
423
+ splitReference(ns, parseFrontMatter(key, raw).body, topics);
448
424
  } else {
449
425
  topics.push({ name: nameFromKey(key), body: parseFrontMatter(key, raw).body.trim() });
450
426
  }
451
427
  }
452
428
  return topics;
453
429
  }
454
- var cachedIndex = null;
455
430
  function index() {
456
431
  if (!cachedIndex) cachedIndex = buildIndex();
457
432
  return cachedIndex;
@@ -491,6 +466,100 @@ function engineSkills() {
491
466
  if (!raw) return [];
492
467
  return [parseFrontMatter("writing-malloy-with-mcp", raw)];
493
468
  }
469
+ var HOST_ONLY = "host_only";
470
+ var DEFAULT_RESULT_BYTES = 25e3;
471
+ function toContent(result) {
472
+ const { malloy_text, [HOST_ONLY]: _hostOnly, ...rest } = result;
473
+ const content = [
474
+ { type: "text", text: JSON.stringify(rest, null, 2) }
475
+ ];
476
+ if (typeof malloy_text === "string" && malloy_text.length > 0) {
477
+ content.push({ type: "text", text: malloy_text });
478
+ }
479
+ return { content, structuredContent: { ...rest } };
480
+ }
481
+ function argString(args, key) {
482
+ const v = args[key];
483
+ return v === void 0 || v === null ? "" : String(v);
484
+ }
485
+ function argOptString(args, key) {
486
+ const v = args[key];
487
+ return v === void 0 || v === null || v === "" ? void 0 : String(v);
488
+ }
489
+ function argOptNumber(args, key) {
490
+ const v = args[key];
491
+ if (v === void 0 || v === null) return void 0;
492
+ const n = Number(v);
493
+ return Number.isFinite(n) ? n : void 0;
494
+ }
495
+ function argOptBool(args, key) {
496
+ const v = args[key];
497
+ if (v === void 0 || v === null) return void 0;
498
+ return v === true || v === "true";
499
+ }
500
+ function argRecord(args, key) {
501
+ const v = args[key];
502
+ if (v && typeof v === "object" && !Array.isArray(v)) {
503
+ return v;
504
+ }
505
+ return void 0;
506
+ }
507
+ function yoHelpTool() {
508
+ return {
509
+ name: "yo_help",
510
+ title: prompts.shared.tools.yo_help.title,
511
+ description: prompts.shared.tools.yo_help.description,
512
+ inputSchema: {
513
+ type: "object",
514
+ properties: {
515
+ topic: {
516
+ type: "string",
517
+ description: 'A topic name from the index, e.g. "explore/how-to" or "language/joins" (case-insensitive). Omit to list all topic names.'
518
+ }
519
+ },
520
+ additionalProperties: false
521
+ },
522
+ handler: async (args) => {
523
+ const topic = argOptString(args, "topic");
524
+ if (!topic) return { topics: listHelpTopics() };
525
+ const hit = getHelpTopic(topic);
526
+ if (!hit) {
527
+ return { error: `No topic matches '${topic}'.`, topics: listHelpTopics() };
528
+ }
529
+ return { name: hit.name, body: hit.body };
530
+ }
531
+ };
532
+ }
533
+ function sharedSkills() {
534
+ return engineSkills();
535
+ }
536
+ function attachHelp(result) {
537
+ const problems = result.problems;
538
+ if (!Array.isArray(problems) || problems.length === 0) return result;
539
+ const help = [];
540
+ const seen = /* @__PURE__ */ new Set();
541
+ for (const p of problems) {
542
+ if (!p.help_topic || seen.has(p.help_topic)) continue;
543
+ seen.add(p.help_topic);
544
+ const hit = getHelpTopic(p.help_topic);
545
+ if (hit) help.push(hit);
546
+ }
547
+ return help.length ? { ...result, help } : result;
548
+ }
549
+ function withHelp(tool) {
550
+ return { ...tool, handler: async (args) => attachHelp(await tool.handler(args)) };
551
+ }
552
+
553
+ // ../mcp-engine/dist/chunk-QRE2RJG5.js
554
+ import { prettify as internalPrettify } from "@malloydata/malloy/internal";
555
+ import {
556
+ MalloyError,
557
+ expressionIsAggregate,
558
+ expressionIsAnalytic
559
+ } from "@malloydata/malloy";
560
+ import { tagFromAnnotations } from "@malloydata/malloy";
561
+ import { API, MalloyError as MalloyError2 } from "@malloydata/malloy";
562
+ import { MalloyError as MalloyError3 } from "@malloydata/malloy";
494
563
  function mapProblems(problems) {
495
564
  return problems.map((p) => {
496
565
  const out = {
@@ -1499,516 +1568,346 @@ async function runRestricted(runtime, entry, query, opts = {}) {
1499
1568
  return { ok: false, problems: [...loadProblems, errorProblem(e, entry.href)] };
1500
1569
  }
1501
1570
  }
1502
- function titleFromName(name) {
1503
- return name.split(/[_-]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
1571
+ var REFINE_HINT = "Aggregate, filter, or do top-N in Malloy rather than fetching rows to post-process; select fewer columns if rows are wide.";
1572
+ function utf8Length(text) {
1573
+ let bytes = 0;
1574
+ for (let i = 0; i < text.length; i++) {
1575
+ const c = text.charCodeAt(i);
1576
+ if (c < 128) bytes += 1;
1577
+ else if (c < 2048) bytes += 2;
1578
+ else if (c >= 55296 && c < 56320 && i + 1 < text.length) {
1579
+ const next = text.charCodeAt(i + 1);
1580
+ if (next >= 56320 && next < 57344) {
1581
+ bytes += 4;
1582
+ i++;
1583
+ } else bytes += 3;
1584
+ } else bytes += 3;
1585
+ }
1586
+ return bytes;
1504
1587
  }
1505
- function datasetTitle(name, declared) {
1506
- const t = declared?.trim();
1507
- return t || titleFromName(name);
1588
+ function fittingPrefix(rows, maxBytes) {
1589
+ let bytes = 2;
1590
+ for (let i = 0; i < rows.length; i++) {
1591
+ const rowBytes = utf8Length(JSON.stringify(rows[i]) ?? "null");
1592
+ if (bytes + rowBytes + 1 > maxBytes) return i;
1593
+ bytes += rowBytes + 1;
1594
+ }
1595
+ return rows.length;
1508
1596
  }
1509
- function readDatasetMeta(model) {
1510
- const m = model;
1511
- let title;
1512
- try {
1513
- const tag = m.annotations.parseAsTag().tag;
1514
- if (tag.has("dataset")) {
1515
- title = tag.tag("dataset")?.text("title") ?? tag.text("title");
1597
+ async function applyResultBudget(full, policy, ctx) {
1598
+ const { stable_result, ...wire } = full;
1599
+ if (!wire.ok || !wire.rows) return wire;
1600
+ const maxBytes = policy?.maxResultBytes ?? DEFAULT_RESULT_BYTES;
1601
+ const keep = fittingPrefix(wire.rows, maxBytes);
1602
+ if (keep >= wire.rows.length) return wire;
1603
+ let fullResultUri;
1604
+ if (policy?.spill) {
1605
+ try {
1606
+ fullResultUri = (await policy.spill(full, ctx))?.uri;
1607
+ } catch {
1516
1608
  }
1517
- } catch {
1518
- }
1519
- let description;
1520
- try {
1521
- const docs = m.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
1522
- if (docs.length) description = docs.join("\n");
1523
- } catch {
1524
1609
  }
1525
- return { ...title ? { title } : {}, ...description ? { description } : {} };
1610
+ const out = {
1611
+ ...wire,
1612
+ rows: wire.rows.slice(0, keep),
1613
+ rows_returned: keep,
1614
+ truncated: {
1615
+ reason: "byte_budget",
1616
+ hint: keep === 0 ? "A single row exceeds the response byte budget \u2014 project fewer columns or un-nest the result. " + REFINE_HINT : `Result truncated to ${keep} of ${wire.row_count} rows to fit the response byte budget. ` + REFINE_HINT,
1617
+ ...fullResultUri ? { full_result: fullResultUri } : {}
1618
+ }
1619
+ };
1620
+ return out;
1526
1621
  }
1527
- function nameToSlug(s) {
1528
- return s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 48) || "dataset";
1622
+ var guidance = {
1623
+ core: prompts.core.instructions,
1624
+ develop: prompts.develop.instructions,
1625
+ explore: prompts.explore.instructions
1626
+ };
1627
+ function assembleInstructions(kind) {
1628
+ const surface = kind === "develop" ? guidance.develop : guidance.explore;
1629
+ return [surface, guidance.core].filter(Boolean).join("\n\n");
1529
1630
  }
1530
- var DATASETS_DIR = "datasets";
1531
- var ENTRY_FILE = "index.malloy";
1532
- async function layoutFromListing(list, label = "this repo") {
1533
- const root = await list("");
1534
- if (root.length === 0) {
1535
- return { ok: false, error: `${label} is empty or could not be read.` };
1536
- }
1537
- const hasRootEntry = root.some((e) => e.type === "file" && e.name === ENTRY_FILE);
1538
- const hasDatasetsDir = root.some((e) => e.type === "dir" && e.name === DATASETS_DIR);
1539
- if (hasRootEntry && hasDatasetsDir) {
1540
- return {
1541
- ok: false,
1542
- error: `This repo has both a top-level ${ENTRY_FILE} and a ${DATASETS_DIR}/ directory, and those are two different layouts. Use one: keep ${ENTRY_FILE} at the root to publish a single dataset, or move it under ${DATASETS_DIR}/<name>/ and delete the root one to publish several.`
1543
- };
1544
- }
1545
- if (hasRootEntry) return { ok: true, kind: "single" };
1546
- if (!hasDatasetsDir) {
1547
- return {
1548
- ok: false,
1549
- error: `No ${ENTRY_FILE} at the root of ${label}, and no ${DATASETS_DIR}/ directory either. A model repo needs one or the other.`
1550
- };
1551
- }
1552
- const subdirs = (await list(DATASETS_DIR)).filter((e) => e.type === "dir");
1553
- if (subdirs.length === 0) {
1554
- return {
1555
- ok: false,
1556
- empty: true,
1557
- error: `${DATASETS_DIR}/ has no subdirectories \u2014 each dataset is a directory under it.`
1558
- };
1559
- }
1560
- const found = [];
1561
- const missing = [];
1562
- for (const d of subdirs) {
1563
- const inside = await list(`${DATASETS_DIR}/${d.name}`);
1564
- if (inside.some((e) => e.type === "file" && e.name === ENTRY_FILE)) {
1565
- found.push({ name: nameToSlug(d.name), dir: `${DATASETS_DIR}/${d.name}` });
1566
- } else {
1567
- missing.push(`${DATASETS_DIR}/${d.name}`);
1568
- }
1569
- }
1570
- if (missing.length > 0) {
1571
- return {
1572
- ok: false,
1573
- error: `${missing.join(", ")}: every directory under ${DATASETS_DIR}/ is a dataset and needs its own ${ENTRY_FILE}. Add one, or move the directory out of ${DATASETS_DIR}/ if it is shared code (a sibling \`lib/\` is imported by relative path).`
1574
- };
1575
- }
1576
- const byName2 = /* @__PURE__ */ new Map();
1577
- for (const d of found) byName2.set(d.name, [...byName2.get(d.name) ?? [], d.dir]);
1578
- const collided = [...byName2.entries()].filter(([, dirs]) => dirs.length > 1);
1579
- if (collided.length > 0) {
1631
+ function refModelProblem(ref, e) {
1632
+ const msg = e instanceof Error ? e.message : String(e);
1633
+ return codeProblem("model-not-found", `Cannot use model '${ref}': ${msg}`);
1634
+ }
1635
+ function refNudge(ref, inspect) {
1636
+ const also = inspect.also ? ` and ${inspect.also}=<the source you queried>` : "";
1637
+ return (p) => {
1638
+ if (p.code !== "field-not-found") return p;
1580
1639
  return {
1581
- ok: false,
1582
- error: collided.map(([name, dirs]) => `${dirs.join(" and ")} both publish a dataset named "${name}"`).join("; ")
1640
+ ...p,
1641
+ message: `${p.message} \u2014 call ${inspect.tool} with ${inspect.param}="${ref}"${also} to see what fields, measures, views, and joins exist.`,
1642
+ help_topic: p.help_topic ?? "language/fields"
1583
1643
  };
1584
- }
1585
- return { ok: true, kind: "multi", datasets: found.sort((a, b) => a.name.localeCompare(b.name)) };
1644
+ };
1586
1645
  }
1587
- var MAX_FILE = 4 * 1024 * 1024;
1588
- var MAX_TOTAL = 64 * 1024 * 1024;
1589
- function renderGivenType2(t) {
1590
- if (t.type === "filter expression") {
1591
- return t.filterType ? `filter<${t.filterType}>` : "filter";
1592
- }
1593
- if (t.type === "array") {
1594
- const elem = t.elementTypeDef;
1595
- if (!elem) return "array";
1596
- if (elem.type === "record_element") return "record[]";
1597
- return `${renderGivenType2(elem)}[]`;
1598
- }
1599
- return t.type;
1600
- }
1601
- function defaultValue(e) {
1602
- if (!e) return void 0;
1603
- switch (e.node) {
1604
- case "filterLiteral":
1605
- return e.filterSrc;
1606
- case "stringLiteral":
1607
- return e.literal;
1608
- case "numberLiteral":
1609
- return Number(e.literal);
1610
- case "true":
1611
- return true;
1612
- case "false":
1613
- return false;
1614
- case "dateLiteral":
1615
- case "timestampLiteral":
1616
- case "timestamptzLiteral":
1617
- return e.literal;
1618
- default:
1619
- return void 0;
1646
+ async function executeQuery(m, args, fix, result) {
1647
+ const malloy = argString(args, "malloy");
1648
+ const execute = argOptBool(args, "execute") ?? true;
1649
+ const givens = argRecord(args, "givens");
1650
+ const rowLimit = Math.max(1, Math.min(1e4, argOptNumber(args, "max_rows") ?? DEFAULT_ROW_LIMIT));
1651
+ if (!execute) {
1652
+ const v = await validateRestricted(m.runtime, m.entry, malloy);
1653
+ return { ...v, problems: v.problems.map(fix) };
1620
1654
  }
1655
+ const full = await runRestricted(m.runtime, m.entry, malloy, {
1656
+ rowLimit,
1657
+ givens,
1658
+ requireGivens: m.requireGivens
1659
+ });
1660
+ const budgeted = await applyResultBudget(full, result, { toolName: "query", args });
1661
+ return { ...budgeted, problems: budgeted.problems.map(fix) };
1621
1662
  }
1622
- function describeGivenSpec(name, g) {
1623
- const spec = { name, type: renderGivenType2(g.type) };
1624
- if (g.type.type === "filter expression" && g.type.filterType) {
1625
- spec.filterType = g.type.filterType;
1626
- }
1627
- const dflt = defaultValue(g.default);
1628
- if (dflt !== void 0) spec.default = dflt;
1629
- try {
1630
- const docs = g.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
1631
- if (docs.length) spec.description = docs.join("\n");
1632
- } catch {
1633
- }
1634
- try {
1635
- const dict = g.annotations.parseAsTag().tag.dict ?? {};
1636
- const tags = {};
1637
- for (const [key, t] of Object.entries(dict)) {
1638
- const eq = t.eq;
1639
- if (typeof eq === "string" || typeof eq === "number" || typeof eq === "boolean") {
1640
- tags[key] = eq;
1641
- } else if (eq === void 0 && !t.dict) {
1642
- tags[key] = true;
1663
+ function queryTool(host, opts = {}) {
1664
+ const inspect = opts.inspect ?? { tool: "describe_source", param: "model_ref", also: "source" };
1665
+ return {
1666
+ name: "query",
1667
+ title: prompts.shared.tools.query.title,
1668
+ description: prompts.shared.tools.query.description,
1669
+ inputSchema: {
1670
+ type: "object",
1671
+ properties: {
1672
+ model_ref: {
1673
+ type: "string",
1674
+ description: "Model ref \u2014 a published model name, or (on a local develop server) the path of the root model file."
1675
+ },
1676
+ malloy: { type: "string", description: "Malloy query text, e.g. `run: orders -> { ... }`." },
1677
+ question: {
1678
+ type: "string",
1679
+ description: "Plain-English description of what this query answers; hosts may record or share it."
1680
+ },
1681
+ givens: {
1682
+ type: "object",
1683
+ description: "Values for $NAME givens, keyed by name (no $). Validate with execute:false to learn which givens the query needs."
1684
+ },
1685
+ execute: { type: "boolean", description: "Default true. false \u2192 compile/validate only (no execution)." },
1686
+ max_rows: { type: "integer", minimum: 1, maximum: 1e4, description: `Row cap (default ${DEFAULT_ROW_LIMIT}).` }
1687
+ },
1688
+ required: ["model_ref", "malloy"],
1689
+ additionalProperties: false
1690
+ },
1691
+ handler: async (args) => {
1692
+ const ref = argString(args, "model_ref");
1693
+ if (!ref.trim()) {
1694
+ return { ok: false, problems: [codeProblem("model-ref-required", prompts.shared.errors["no-model-ref"])] };
1643
1695
  }
1644
- }
1645
- if (Object.keys(tags).length) spec.tags = tags;
1646
- const suggestDict = dict.suggest?.dict;
1647
- if (suggestDict) {
1648
- const suggest = {};
1649
- for (const key of ["source", "dimension", "query"]) {
1650
- const eq = suggestDict[key]?.eq;
1651
- if (typeof eq === "string") suggest[key] = eq;
1696
+ try {
1697
+ return await host.withModel(
1698
+ ref,
1699
+ (m) => executeQuery(m, args, refNudge(ref, inspect), opts.result)
1700
+ );
1701
+ } catch (e) {
1702
+ return { ok: false, problems: [refModelProblem(ref, e)] };
1652
1703
  }
1653
- if (suggest.source || suggest.query) spec.suggest = suggest;
1654
1704
  }
1655
- } catch {
1656
- }
1657
- return spec;
1705
+ };
1658
1706
  }
1659
- async function dashboardGivenSpecs(runtime, entry, runExpr) {
1660
- try {
1661
- const mm = runtime.loadModel(entry);
1662
- const pq = await mm.loadQuery(`run: ${runExpr}`).getPreparedQuery();
1663
- const specs = [];
1664
- for (const [name, g] of pq.givens) {
1665
- specs.push(describeGivenSpec(name, g));
1666
- }
1667
- return { ok: true, givens: specs };
1668
- } catch (e) {
1669
- return { ok: false, error: e instanceof Error ? e.message : String(e) };
1707
+ async function resolveModel(host, source, modelRef) {
1708
+ if (modelRef) return { model_ref: modelRef };
1709
+ if (!host.list) {
1710
+ return {
1711
+ problem: codeProblem(
1712
+ "model-ref-required",
1713
+ "Pass model_ref + source. Use list_sources to see which model a source lives in."
1714
+ )
1715
+ };
1670
1716
  }
1671
- }
1672
- function docText(t) {
1673
- try {
1674
- const docs = t.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
1675
- return docs.length ? docs.join("\n") : void 0;
1676
- } catch {
1677
- return void 0;
1717
+ const entries = (await host.list()).entries;
1718
+ const hits = entries.filter((e) => e.sources?.some((s) => s.source_ref === source));
1719
+ if (hits.length === 1) return { model_ref: hits[0].model_ref };
1720
+ if (hits.length === 0) {
1721
+ return {
1722
+ problem: codeProblem(
1723
+ "source-not-found",
1724
+ `No exported source named '${source}' in any model you can see. Call list_sources, or pass model_ref if it is an internal source.`
1725
+ )
1726
+ };
1678
1727
  }
1728
+ return {
1729
+ problem: codeProblem(
1730
+ "source-ambiguous",
1731
+ `Source '${source}' exists in more than one model: ${hits.map((h) => h.model_ref).join(", ")}. Pass model_ref to pick one.`
1732
+ )
1733
+ };
1679
1734
  }
1680
- function resolveTile(tile, source) {
1681
- const t = tile.trim();
1682
- if (source && !t.includes("->")) return `${source} -> ${t}`;
1683
- return t;
1735
+ function srcNudge(modelRef, source) {
1736
+ return (p) => {
1737
+ if (p.code !== "field-not-found") return p;
1738
+ return {
1739
+ ...p,
1740
+ message: `${p.message} \u2014 call describe_source with source="${source}"` + (modelRef ? ` model_ref="${modelRef}"` : "") + " to see what fields, measures, views, and joins exist.",
1741
+ help_topic: p.help_topic ?? "language/fields"
1742
+ };
1743
+ };
1684
1744
  }
1685
- function readGivens(tag) {
1686
- const givensTag = tag.tag("artifact", "givens");
1687
- if (!givensTag) return void 0;
1688
- const givens = {};
1689
- for (const [key, t] of Object.entries(givensTag.dict ?? {})) {
1690
- const eq = t.eq;
1691
- if (typeof eq === "string" || typeof eq === "number" || typeof eq === "boolean") {
1692
- givens[key] = eq;
1693
- }
1694
- }
1695
- return Object.keys(givens).length ? givens : void 0;
1745
+ function definedNamesIn(malloy) {
1746
+ const names = /* @__PURE__ */ new Set();
1747
+ const re = /\b([A-Za-z_]\w*)\s+is\b/g;
1748
+ let m;
1749
+ while ((m = re.exec(malloy)) !== null) names.add(m[1]);
1750
+ return names;
1696
1751
  }
1697
- function readArtifactTag(ident, q) {
1698
- let tag;
1699
- try {
1700
- tag = q.annotations.parseAsTag().tag;
1701
- } catch {
1702
- return void 0;
1703
- }
1704
- if (!tag.has("artifact")) return void 0;
1705
- const nested = tag.tag("artifact");
1706
- const description = docText(q);
1707
- const name = nested?.text("name") ?? tag.text("name") ?? ident.defaultName;
1708
- const title = nested?.text("title") ?? tag.text("title") ?? description?.split("\n")[0] ?? ident.defaultName;
1709
- const rawTiles = nested?.textArray("tiles") ?? tag.textArray("tiles");
1710
- if (rawTiles && rawTiles.length) {
1711
- const resolved = rawTiles.map((t) => resolveTile(t, ident.source));
1712
- const cols = nested?.numeric("dashboard_columns") ?? tag.numeric("dashboard_columns");
1713
- const autorunText2 = nested?.text("autorun") ?? tag.text("autorun");
1714
- const givens2 = readGivens(tag);
1715
- if (resolved.length === 1) {
1716
- const info3 = { name, query: resolved[0], title };
1717
- if (ident.source) info3.source = ident.source;
1718
- if (description) info3.description = description;
1719
- if (autorunText2 === "false") info3.autorun = false;
1720
- if (givens2) info3.givens = givens2;
1721
- if (typeof cols === "number")
1722
- info3.warnings = [
1723
- "dashboard_columns is ignored on a single-tile artifact (one tile renders like a single-query `# artifact`, laid out by the tile query\u2019s own `# dashboard` tag)"
1724
- ];
1725
- return info3;
1752
+ function queryFieldFix(modelRef, source, malloy) {
1753
+ const defined = definedNamesIn(malloy);
1754
+ const nudge = srcNudge(modelRef, source);
1755
+ return (p) => {
1756
+ if (p.code !== "field-not-found") return p;
1757
+ const name = /'([^']+)'/.exec(p.message)?.[1];
1758
+ if (name && defined.has(name)) {
1759
+ return {
1760
+ ...p,
1761
+ message: `'${name}' is defined in this query, but one field can't reference another in the same stage. To build a value from other aggregates (a ratio, a share), declare the parts in an \`extend:\` block (measures can reference each other), then use them.`,
1762
+ help_topic: "explore/query-examples"
1763
+ };
1726
1764
  }
1727
- const info2 = { name, query: "", title, tiles: resolved };
1728
- if (ident.source) info2.source = ident.source;
1729
- if (description) info2.description = description;
1730
- if (typeof cols === "number") info2.dashboard_columns = cols;
1731
- if (autorunText2 === "false") info2.autorun = false;
1732
- if (givens2) info2.givens = givens2;
1733
- return info2;
1734
- }
1735
- const info = { name, query: ident.runExpr, title };
1736
- if (ident.source) info.source = ident.source;
1737
- if (ident.view) info.view = ident.view;
1738
- if (description) info.description = description;
1739
- const autorunText = nested?.text("autorun") ?? tag.text("autorun");
1740
- if (autorunText === "false") info.autorun = false;
1741
- const givens = readGivens(tag);
1742
- if (givens) info.givens = givens;
1743
- return info;
1765
+ return nudge(p);
1766
+ };
1744
1767
  }
1745
- async function artifactQueries(runtime, entry) {
1746
- try {
1747
- const model = await runtime.loadModel(entry).getModel();
1748
- const artifacts = [];
1749
- const modelComposite = readArtifactTag({ runExpr: "", defaultName: "dashboard" }, model);
1750
- if (modelComposite && (modelComposite.tiles || modelComposite.query)) artifacts.push(modelComposite);
1751
- for (const queryName of model.queries().named) {
1752
- const pq = model.getPreparedQueryByName(queryName);
1753
- const info = readArtifactTag({ runExpr: queryName, defaultName: queryName }, pq);
1754
- if (info) artifacts.push(info);
1755
- }
1756
- for (const src of model.explores) {
1757
- const srcComposite = readArtifactTag(
1758
- { runExpr: "", defaultName: src.name, source: src.name },
1759
- src
1760
- );
1761
- if (srcComposite && (srcComposite.tiles || srcComposite.query)) artifacts.push(srcComposite);
1762
- for (const field of src.allFields) {
1763
- if (!field.isQueryField()) continue;
1764
- const view = field;
1765
- const info = readArtifactTag(
1766
- {
1767
- runExpr: `${src.name} -> ${view.name}`,
1768
- defaultName: view.name,
1769
- source: src.name,
1770
- view: view.name
1771
- },
1772
- view
1773
- );
1774
- if (info) artifacts.push(info);
1775
- }
1776
- }
1777
- return { ok: true, artifacts };
1778
- } catch (e) {
1779
- return { ok: false, error: e instanceof Error ? e.message : String(e) };
1780
- }
1768
+ function sourceAsMalloy(s) {
1769
+ return s?.body ? `source: ${s.body}` : "";
1781
1770
  }
1782
- async function collectDrillTargets(runtime, entry) {
1783
- try {
1784
- const model = await runtime.loadModel(entry).getModel();
1785
- const targets = /* @__PURE__ */ new Set();
1786
- for (const src of model.explores) {
1787
- for (const field of src.allFields) {
1788
- const tagged = field;
1789
- let tag;
1790
- try {
1791
- tag = tagged.annotations.parseAsTag().tag;
1792
- } catch {
1793
- continue;
1794
- }
1795
- const drill = tag.tag("drill");
1796
- if (!drill) continue;
1797
- const to = drill.textArray("to") ?? (drill.text("to") ? [drill.text("to")] : []);
1798
- for (const t of to) if (t && t !== "self") targets.add(t);
1799
- }
1800
- }
1801
- return { ok: true, targets: [...targets] };
1802
- } catch (e) {
1803
- return { ok: false, error: e instanceof Error ? e.message : String(e) };
1771
+ function buildQueryExamples(ds) {
1772
+ const ref = (name, mustQuote) => mustQuote ? `\`${name}\`` : name;
1773
+ const out = [];
1774
+ const view = Object.keys(ds.views)[0];
1775
+ if (view) out.push(`run: ${ds.name} -> ${view}`);
1776
+ const dims = Object.entries(ds.dimensions).filter(([, m]) => "type" in m);
1777
+ const dim = dims.find(([, m]) => m.type === "string") ?? dims[0];
1778
+ const measure = Object.entries(ds.measures)[0];
1779
+ if (dim && measure) {
1780
+ const [dName, dField] = dim;
1781
+ const [mName, mField] = measure;
1782
+ const m = ref(mName, mField.must_quote);
1783
+ out.push(
1784
+ `run: ${ds.name} -> {
1785
+ group_by: ${ref(dName, dField.must_quote)}
1786
+ aggregate: ${m}
1787
+ order_by: ${m} desc
1788
+ limit: 10
1789
+ }`
1790
+ );
1804
1791
  }
1792
+ return out;
1805
1793
  }
1806
- async function modelArtifact(runtime, entry, defaultName) {
1807
- try {
1808
- const model = await runtime.loadModel(entry).getModel();
1809
- const composite = readArtifactTag({ runExpr: "", defaultName }, model);
1810
- if (composite && (composite.tiles || composite.query)) return { ok: true, artifact: composite };
1811
- for (const queryName of model.queries().named) {
1812
- const pq = model.getPreparedQueryByName(queryName);
1813
- const info = readArtifactTag({ runExpr: queryName, defaultName }, pq);
1814
- if (info && !info.tiles) return { ok: true, artifact: info };
1815
- }
1816
- for (const src of model.explores) {
1817
- for (const field of src.allFields) {
1818
- if (!field.isQueryField()) continue;
1819
- const view = field;
1820
- const info = readArtifactTag(
1821
- { runExpr: `${src.name} -> ${view.name}`, defaultName, source: src.name, view: view.name },
1822
- view
1823
- );
1824
- if (info && !info.tiles) return { ok: true, artifact: info };
1794
+ function listSourcesTool(host) {
1795
+ return {
1796
+ name: "list_sources",
1797
+ title: prompts.explore.tools.list_sources.title,
1798
+ description: prompts.explore.tools.list_sources.description,
1799
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
1800
+ handler: async () => {
1801
+ const { entries } = await host.list();
1802
+ const models = /* @__PURE__ */ Object.create(null);
1803
+ for (const e of entries) {
1804
+ const m = {};
1805
+ if (e.description) m.description = e.description;
1806
+ if (e.sources?.length) {
1807
+ const sources = /* @__PURE__ */ Object.create(null);
1808
+ for (const s of e.sources) {
1809
+ const o = {};
1810
+ if (s.description) o.description = s.description;
1811
+ if (s.must_quote) o.must_quote = true;
1812
+ sources[s.source_ref] = o;
1813
+ }
1814
+ m.sources = sources;
1815
+ }
1816
+ if (e.dashboards?.length) {
1817
+ const dashboards = /* @__PURE__ */ Object.create(null);
1818
+ for (const d of e.dashboards) {
1819
+ const o = {};
1820
+ if (d.title) o.title = d.title;
1821
+ if (d.description) o.description = d.description;
1822
+ if (d.url) o.url = d.url;
1823
+ dashboards[d.name] = o;
1824
+ }
1825
+ m.dashboards = dashboards;
1826
+ }
1827
+ models[e.model_ref] = m;
1825
1828
  }
1826
- }
1827
- return { ok: true, artifact: void 0 };
1828
- } catch (e) {
1829
- return { ok: false, error: e instanceof Error ? e.message : String(e) };
1830
- }
1831
- }
1832
- var INSTANCE_PLACEHOLDER = "{{INSTANCE_NAME}}";
1833
- function renderInstructions(text, instanceName) {
1834
- return text.replaceAll(INSTANCE_PLACEHOLDER, instanceName);
1835
- }
1836
- var VIRTUAL_BASE = "memory://mcp-engine/";
1837
- function normalizeUrl2(u) {
1838
- if (u.includes("://")) return new URL(u);
1839
- return url.pathToFileURL(path.resolve(u));
1840
- }
1841
- function inlineVirtualUrl(baseUrl) {
1842
- if (baseUrl) return new URL("__inline__.malloy", normalizeUrl2(baseUrl));
1843
- return new URL(VIRTUAL_BASE + "__inline__.malloy");
1844
- }
1845
- function prepareSource(base, input) {
1846
- const inline = "source" in input;
1847
- const entry = inline ? inlineVirtualUrl(input.baseUrl) : normalizeUrl2(input.url);
1848
- const cache = /* @__PURE__ */ new Map();
1849
- if (inline) cache.set(entry.href, input.source);
1850
- const reader = {
1851
- readURL: async (u) => {
1852
- const cached = cache.get(u.href);
1853
- if (cached !== void 0) return cached;
1854
- const text = await base.readURL(u);
1855
- const str2 = typeof text === "string" ? text : String(text);
1856
- cache.set(u.href, str2);
1857
- return str2;
1829
+ return { ok: true, guidance: prompts.explore.guidance, models };
1858
1830
  }
1859
1831
  };
1860
- return { reader, entry, readSource: (href) => cache.get(href) };
1861
- }
1862
- var DEFAULT_RESULT_BYTES = 25e3;
1863
- function argString(args, key) {
1864
- const v = args[key];
1865
- return v === void 0 || v === null ? "" : String(v);
1866
- }
1867
- function argOptString(args, key) {
1868
- const v = args[key];
1869
- return v === void 0 || v === null || v === "" ? void 0 : String(v);
1870
- }
1871
- function argOptNumber(args, key) {
1872
- const v = args[key];
1873
- if (v === void 0 || v === null) return void 0;
1874
- const n = Number(v);
1875
- return Number.isFinite(n) ? n : void 0;
1876
- }
1877
- function argOptBool(args, key) {
1878
- const v = args[key];
1879
- if (v === void 0 || v === null) return void 0;
1880
- return v === true || v === "true";
1881
- }
1882
- function argRecord(args, key) {
1883
- const v = args[key];
1884
- if (v && typeof v === "object" && !Array.isArray(v)) {
1885
- return v;
1886
- }
1887
- return void 0;
1888
1832
  }
1889
- function yoHelpTool() {
1833
+ function describeSourceTool(host) {
1890
1834
  return {
1891
- name: "yo_help",
1892
- title: prompts.shared.tools.yo_help.title,
1893
- description: prompts.shared.tools.yo_help.description,
1835
+ name: "describe_source",
1836
+ title: prompts.explore.tools.describe_source.title,
1837
+ description: prompts.explore.tools.describe_source.description,
1894
1838
  inputSchema: {
1895
1839
  type: "object",
1896
1840
  properties: {
1897
- topic: {
1841
+ source: { type: "string", description: "The source to describe (a source the model publishes)." },
1842
+ model_ref: {
1898
1843
  type: "string",
1899
- description: 'A topic name from the index, e.g. "explore/how-to" or "language/joins" (case-insensitive). Omit to list all topic names.'
1844
+ description: "The model the source lives in (the model_ref from list_sources). Optional when the source name is unique across the catalog."
1900
1845
  }
1901
1846
  },
1847
+ required: ["source"],
1902
1848
  additionalProperties: false
1903
1849
  },
1904
1850
  handler: async (args) => {
1905
- const topic = argOptString(args, "topic");
1906
- if (!topic) return { topics: listHelpTopics() };
1907
- const hit = getHelpTopic(topic);
1908
- if (!hit) {
1909
- return { error: `No topic matches '${topic}'.`, topics: listHelpTopics() };
1851
+ const source = argString(args, "source");
1852
+ const modelRefArg = argOptString(args, "model_ref");
1853
+ if (!source.trim()) {
1854
+ return {
1855
+ ok: false,
1856
+ model_ref: modelRefArg ?? "",
1857
+ source,
1858
+ problems: [codeProblem("source-required", "A source name is required. Use list_sources to see them.")]
1859
+ };
1860
+ }
1861
+ const r = await resolveModel(host, source, modelRefArg);
1862
+ if ("problem" in r) {
1863
+ return { ok: false, model_ref: modelRefArg ?? "", source, problems: [r.problem] };
1864
+ }
1865
+ const modelRef = r.model_ref;
1866
+ try {
1867
+ return await host.withModel(modelRef, async (m) => {
1868
+ const ref = m.ref ?? modelRef;
1869
+ const compiled = await compile(m.runtime, m.entry, { readSource: m.readSource });
1870
+ if (!compiled.ok || !compiled.model) {
1871
+ return { ok: false, model_ref: ref, source, problems: compiled.problems };
1872
+ }
1873
+ const built = buildSourceDescribe(compiled.model, source);
1874
+ if (!built) {
1875
+ const available = Object.keys(compiled.model.sources);
1876
+ return {
1877
+ ok: false,
1878
+ model_ref: ref,
1879
+ source,
1880
+ problems: [
1881
+ ...compiled.problems,
1882
+ codeProblem(
1883
+ "source-not-found",
1884
+ `No source named '${source}' in '${ref}'. Sources: ${available.join(", ") || "(none)"}.`
1885
+ )
1886
+ ]
1887
+ };
1888
+ }
1889
+ const malloy_text = sourceAsMalloy(compiled.model.sources[source]);
1890
+ const base = {
1891
+ ok: true,
1892
+ model_ref: ref,
1893
+ source,
1894
+ guidance: prompts.explore.guidance,
1895
+ described_source: built.described_source,
1896
+ problems: compiled.problems
1897
+ };
1898
+ const examples = buildQueryExamples(built.described_source);
1899
+ if (examples.length) base.examples = examples;
1900
+ if (Object.keys(built.joins).length) base.joins = built.joins;
1901
+ if (Object.keys(built.join_source_map).length) base.join_source_map = built.join_source_map;
1902
+ return malloy_text ? { ...base, malloy_text } : base;
1903
+ });
1904
+ } catch (e) {
1905
+ return { ok: false, model_ref: modelRef, source, problems: [refModelProblem(modelRef, e)] };
1910
1906
  }
1911
- return { name: hit.name, body: hit.body };
1912
- }
1913
- };
1914
- }
1915
- function sharedSkills() {
1916
- return engineSkills();
1917
- }
1918
- function attachHelp(result) {
1919
- const problems = result.problems;
1920
- if (!Array.isArray(problems) || problems.length === 0) return result;
1921
- const help = [];
1922
- const seen = /* @__PURE__ */ new Set();
1923
- for (const p of problems) {
1924
- if (!p.help_topic || seen.has(p.help_topic)) continue;
1925
- seen.add(p.help_topic);
1926
- const hit = getHelpTopic(p.help_topic);
1927
- if (hit) help.push(hit);
1928
- }
1929
- return help.length ? { ...result, help } : result;
1930
- }
1931
- function withHelp(tool) {
1932
- return { ...tool, handler: async (args) => attachHelp(await tool.handler(args)) };
1933
- }
1934
- var REFINE_HINT = "Aggregate, filter, or do top-N in Malloy rather than fetching rows to post-process; select fewer columns if rows are wide.";
1935
- function fittingPrefix(rows, maxBytes) {
1936
- let bytes = 2;
1937
- for (let i = 0; i < rows.length; i++) {
1938
- const rowBytes = Buffer.byteLength(JSON.stringify(rows[i]) ?? "null", "utf8");
1939
- if (bytes + rowBytes + 1 > maxBytes) return i;
1940
- bytes += rowBytes + 1;
1941
- }
1942
- return rows.length;
1943
- }
1944
- async function applyResultBudget(full, policy, ctx) {
1945
- const { stable_result, ...wire } = full;
1946
- if (!wire.ok || !wire.rows) return wire;
1947
- const maxBytes = policy?.maxResultBytes ?? DEFAULT_RESULT_BYTES;
1948
- const keep = fittingPrefix(wire.rows, maxBytes);
1949
- if (keep >= wire.rows.length) return wire;
1950
- let fullResultUri;
1951
- if (policy?.spill) {
1952
- try {
1953
- fullResultUri = (await policy.spill(full, ctx))?.uri;
1954
- } catch {
1955
- }
1956
- }
1957
- const out = {
1958
- ...wire,
1959
- rows: wire.rows.slice(0, keep),
1960
- rows_returned: keep,
1961
- truncated: {
1962
- reason: "byte_budget",
1963
- hint: keep === 0 ? "A single row exceeds the response byte budget \u2014 project fewer columns or un-nest the result. " + REFINE_HINT : `Result truncated to ${keep} of ${wire.row_count} rows to fit the response byte budget. ` + REFINE_HINT,
1964
- ...fullResultUri ? { full_result: fullResultUri } : {}
1965
1907
  }
1966
1908
  };
1967
- return out;
1968
- }
1969
- var guidance = {
1970
- core: prompts.core.instructions,
1971
- develop: prompts.develop.instructions,
1972
- explore: prompts.explore.instructions
1973
- };
1974
- function assembleInstructions(kind) {
1975
- const surface = kind === "develop" ? guidance.develop : guidance.explore;
1976
- return [surface, guidance.core].filter(Boolean).join("\n\n");
1977
- }
1978
- function refModelProblem(ref, e) {
1979
- const msg = e instanceof Error ? e.message : String(e);
1980
- return codeProblem("model-not-found", `Cannot use model '${ref}': ${msg}`);
1981
- }
1982
- function refNudge(ref, inspect) {
1983
- const also = inspect.also ? ` and ${inspect.also}=<the source you queried>` : "";
1984
- return (p) => {
1985
- if (p.code !== "field-not-found") return p;
1986
- return {
1987
- ...p,
1988
- message: `${p.message} \u2014 call ${inspect.tool} with ${inspect.param}="${ref}"${also} to see what fields, measures, views, and joins exist.`,
1989
- help_topic: p.help_topic ?? "language/fields"
1990
- };
1991
- };
1992
- }
1993
- async function executeQuery(m, args, fix, result) {
1994
- const malloy = argString(args, "malloy");
1995
- const execute = argOptBool(args, "execute") ?? true;
1996
- const givens = argRecord(args, "givens");
1997
- const rowLimit = Math.max(1, Math.min(1e4, argOptNumber(args, "max_rows") ?? DEFAULT_ROW_LIMIT));
1998
- if (!execute) {
1999
- const v = await validateRestricted(m.runtime, m.entry, malloy);
2000
- return { ...v, problems: v.problems.map(fix) };
2001
- }
2002
- const full = await runRestricted(m.runtime, m.entry, malloy, {
2003
- rowLimit,
2004
- givens,
2005
- requireGivens: m.requireGivens
2006
- });
2007
- const budgeted = await applyResultBudget(full, result, { toolName: "query", args });
2008
- return { ...budgeted, problems: budgeted.problems.map(fix) };
2009
1909
  }
2010
- function queryTool(host, opts = {}) {
2011
- const inspect = opts.inspect ?? { tool: "describe_source", param: "model_ref", also: "source" };
1910
+ function exploreQueryTool(host, opts) {
2012
1911
  return {
2013
1912
  name: "query",
2014
1913
  title: prompts.shared.tools.query.title,
@@ -2016,331 +1915,472 @@ function queryTool(host, opts = {}) {
2016
1915
  inputSchema: {
2017
1916
  type: "object",
2018
1917
  properties: {
1918
+ source: { type: "string", description: "The source the query runs against." },
1919
+ malloy: { type: "string", description: "Malloy query text, e.g. `run: orders -> { ... }`." },
2019
1920
  model_ref: {
2020
1921
  type: "string",
2021
- description: "Model ref \u2014 a published model name, or (on a local develop server) the path of the root model file."
1922
+ description: "The model the source lives in (optional when the source name is unique)."
2022
1923
  },
2023
- malloy: { type: "string", description: "Malloy query text, e.g. `run: orders -> { ... }`." },
2024
1924
  question: {
2025
1925
  type: "string",
2026
1926
  description: "Plain-English description of what this query answers; hosts may record or share it."
2027
1927
  },
2028
1928
  givens: {
2029
1929
  type: "object",
2030
- description: "Values for $NAME givens, keyed by name (no $). Validate with execute:false to learn which givens the query needs."
1930
+ description: "Values for $NAME givens, keyed by name (no $). Discover which a query needs with execute:false."
1931
+ },
1932
+ execute: {
1933
+ type: "boolean",
1934
+ description: "Default true. false \u2192 compile/validate only (returns SQL + the givens the query references)."
2031
1935
  },
2032
- execute: { type: "boolean", description: "Default true. false \u2192 compile/validate only (no execution)." },
2033
1936
  max_rows: { type: "integer", minimum: 1, maximum: 1e4, description: `Row cap (default ${DEFAULT_ROW_LIMIT}).` }
2034
1937
  },
2035
- required: ["model_ref", "malloy"],
1938
+ required: ["source", "malloy"],
2036
1939
  additionalProperties: false
2037
1940
  },
2038
1941
  handler: async (args) => {
2039
- const ref = argString(args, "model_ref");
2040
- if (!ref.trim()) {
2041
- return { ok: false, problems: [codeProblem("model-ref-required", prompts.shared.errors["no-model-ref"])] };
1942
+ const source = argString(args, "source");
1943
+ const modelRefArg = argOptString(args, "model_ref");
1944
+ const execute = argOptBool(args, "execute") ?? true;
1945
+ const r = await resolveModel(host, source, modelRefArg);
1946
+ if ("problem" in r) return { ok: false, problems: [r.problem] };
1947
+ const modelRef = r.model_ref;
1948
+ if (modelRefArg && host.list) {
1949
+ const entries = (await host.list()).entries;
1950
+ const here = entries.find((e) => e.model_ref === modelRef);
1951
+ const inModel = here?.sources?.some((s) => s.source_ref === source) ?? false;
1952
+ const elsewhere = entries.filter((e) => e.model_ref !== modelRef && e.sources?.some((s) => s.source_ref === source)).map((e) => e.model_ref);
1953
+ if (here && !inModel && elsewhere.length > 0) {
1954
+ return {
1955
+ ok: false,
1956
+ problems: [
1957
+ codeProblem(
1958
+ "source-not-in-model",
1959
+ `Model '${modelRef}' has no source '${source}' \u2014 it's in: ${elsewhere.join(", ")}. Pass that model_ref, or fix the source name.`
1960
+ )
1961
+ ]
1962
+ };
1963
+ }
2042
1964
  }
2043
1965
  try {
2044
- return await host.withModel(
2045
- ref,
2046
- (m) => executeQuery(m, args, refNudge(ref, inspect), opts.result)
2047
- );
1966
+ return await host.withModel(modelRef, async (m) => {
1967
+ const ref = m.ref ?? modelRef;
1968
+ const res = await executeQuery(
1969
+ m,
1970
+ args,
1971
+ queryFieldFix(modelRef, source, argString(args, "malloy")),
1972
+ opts.result
1973
+ );
1974
+ if (!execute) return { ...res, model_ref: ref };
1975
+ const { sql, ...rest } = res;
1976
+ const out = { ...rest, model_ref: ref };
1977
+ if (sql !== void 0) out[HOST_ONLY] = { sql };
1978
+ return out;
1979
+ });
2048
1980
  } catch (e) {
2049
- return { ok: false, problems: [refModelProblem(ref, e)] };
1981
+ return { ok: false, problems: [refModelProblem(modelRef, e)] };
2050
1982
  }
2051
1983
  }
2052
1984
  };
2053
1985
  }
2054
- async function resolveModel(host, source, modelRef) {
2055
- if (modelRef) return { model_ref: modelRef };
2056
- if (!host.list) {
2057
- return {
2058
- problem: codeProblem(
2059
- "model-ref-required",
2060
- "Pass model_ref + source. Use list_sources to see which model a source lives in."
2061
- )
2062
- };
2063
- }
2064
- const entries = (await host.list()).entries;
2065
- const hits = entries.filter((e) => e.sources?.some((s) => s.source_ref === source));
2066
- if (hits.length === 1) return { model_ref: hits[0].model_ref };
2067
- if (hits.length === 0) {
2068
- return {
2069
- problem: codeProblem(
2070
- "source-not-found",
2071
- `No exported source named '${source}' in any model you can see. Call list_sources, or pass model_ref if it is an internal source.`
2072
- )
2073
- };
2074
- }
1986
+ function exploreSurface(host, opts = {}) {
1987
+ const tools = [];
1988
+ if (host.list) tools.push(listSourcesTool(host));
1989
+ tools.push(describeSourceTool(host));
1990
+ tools.push(exploreQueryTool(host, opts));
1991
+ tools.push(yoHelpTool());
2075
1992
  return {
2076
- problem: codeProblem(
2077
- "source-ambiguous",
2078
- `Source '${source}' exists in more than one model: ${hits.map((h) => h.model_ref).join(", ")}. Pass model_ref to pick one.`
2079
- )
1993
+ tools: tools.map(withHelp),
1994
+ instructions: assembleInstructions("explore"),
1995
+ skills: sharedSkills()
2080
1996
  };
2081
1997
  }
2082
- function srcNudge(modelRef, source) {
2083
- return (p) => {
2084
- if (p.code !== "field-not-found") return p;
2085
- return {
2086
- ...p,
2087
- message: `${p.message} \u2014 call describe_source with source="${source}"` + (modelRef ? ` model_ref="${modelRef}"` : "") + " to see what fields, measures, views, and joins exist.",
2088
- help_topic: p.help_topic ?? "language/fields"
2089
- };
2090
- };
1998
+
1999
+ // ../mcp-engine/dist/index.js
2000
+ import path from "node:path";
2001
+ import url from "node:url";
2002
+ var productContentFiles = {
2003
+ "authoring/start.md": "---\ndescription: Start here when authoring in a clone of a model repo (Claude Code on the web) \u2014 the setup checks, then the edit \u2192 preview_changes \u2192 propose loop\n---\n\n# Authoring a model repo from a clone\n\nYou're in a session with a clone of a model repo, such as Claude Code on the\nweb, and this instance's connector. Edit files in the clone. This instance\ncompiles your edits with its own warehouse connections and shows them, with\nreal data and dashboards, before anything is pushed. Git is only for proposing\nthe finished change.\n\n## First: check the setup\n\nDo these in order. If one fails, tell the person exactly what's wrong and stop.\n\n1. **The tools.** You need `preview_changes`, `list_repos` and `check_repo`. If\n they're missing, either the person isn't an admin on this instance or the\n connector isn't turned on for this session. Say both possibilities.\n2. **The repo.** Run `git remote get-url origin`. `list_repos` must list a repo\n whose `github` is that `owner/name`. If none does, the instance doesn't\n publish this repo, and an admin has to add it.\n3. **The round trip.** Call `preview_changes` with no files:\n - `repo`: the remote, as printed\n - `label`: `git branch --show-current`\n - `base`: `git merge-base HEAD origin/<published branch>`. `list_repos` names\n the published branch, usually `main`.\n\n Every dataset should come back `ok`. If one doesn't, it's broken on the\n published branch too. Say so before you change anything.\n\nThen tell the person it works and ask what they want, unless they already said.\n\n## The loop\n\n1. **Branch.** Work on a branch named for the task, e.g. `claude/returns`.\n Never commit to the published branch.\n2. **Look before writing.**\n - For a new dataset, read the data first with `list_tables` and\n `describe_table`, and ask the person what it should answer.\n - For a change, read the model and the dashboards in the clone.\n `dashboards/*.malloy` and their components exist only here, not in this\n instance's tools.\n3. **Edit, then `preview_changes`.** Send only what differs from `base`:\n - `files`: the full text of each file in `git diff --name-only --diff-filter=d <base>`\n (changed or added; `d` leaves out deletions), plus\n untracked files (`git ls-files --others --exclude-standard`).\n - `deleted`: files removed since `base` (`git diff --name-only --diff-filter=D <base>`).\n - Committed or not doesn't matter. The preview is your working copy.\n4. **Read the answer.** Each dataset is either `ok`, with sources and\n dashboards, or `FAILED` with the compile error. Fix it and preview again.\n5. **Check the numbers.** Use `query` and `describe_source` with the preview\n address as `model_ref`, e.g. `malloyyo_test@claude/returns:returns`. Do the\n work in Malloy, not by post-processing rows.\n6. **Show the person.** Give them the dashboard links from the answer. The pages\n are previews: only admins see them, and nothing is published.\n7. Repeat. Each `preview_changes` replaces what that label's addresses show.\n\n## Adding a dataset\n\n- **Check the repo's layout first.** `list_repos` says it in `addingDatasets`.\n A repo with `datasets/<name>/` directories takes a new one directly. A\n single-dataset repo (`index.malloy` at its root) needs restructuring first;\n `yo_help(\"repo/datasets\")` covers that, and it's a separate change to agree\n with the person.\n- **Look at the data.** Use `list_tables(repo, connection)` with a connection\n from `list_repos`; narrow it with `schema` or `like`, and on BigQuery\n `schema` (the dataset) is required. Then `describe_table` for each table\n that matters: columns, row count and five rows. On DuckDB, a \"table\" can be\n a file path or URL (Parquet, CSV, JSON).\n- **Ask before modeling.** Find out what the person wants to answer: the main\n entities, what one row of each table is, how the tables join, and the few\n measures that matter. A model built from their questions beats one copied\n from the schema.\n- **Write `datasets/<name>/index.malloy`.** The directory names the dataset,\n so make it a short lowercase slug. Use the connection names from\n `list_repos`, e.g. `source: orders is warehouse.table('sales.orders') extend { \u2026 }`.\n Give each source a `#\"` description, and each measure one too; they're what\n people read in `describe_source`.\n- **Stay in your lane.** Don't touch other datasets or `malloy-config.json`\n unless the person asked. A connection or credential that doesn't exist yet is\n an admin's job, outside this change.\n- **It's created at publish.** Until then, the new dataset exists only in\n previews (`status: \"new\"`).\n\n## Proposing it\n\nWhen the person is happy with it:\n\n1. Commit with messages that say why, then push the branch.\n2. Open a pull request, saying what changed and including a sample result.\n3. `check_repo(repo, pull_request: <number>)`. This checks what merging would\n produce. A green preview doesn't cover changes others made to the published\n branch since you started.\n4. **Merging is the person's decision.** Ask first, even if you can merge.\n5. After the merge, `publish_repo(repo)`, unless the repo publishes on push. New\n datasets are created then.\n\n## Good to know\n\n- **Limits.** One preview carries up to 200 changed files and 512KB. Beyond\n that, push the branch and use `fetch_branch(repo, branch)`, which reads it\n from GitHub.\n- **`base` must be on GitHub.** The merge-base with the published branch always\n is. If you rebased onto newer work, recompute it.\n- **Malloy syntax.** `#\"` is a description, a line starting with `#` is an\n annotation (not a comment), and `//` is a comment.\n- **Drafts.** Dashboards someone made in chat are drafts. Promoting one into\n the repo is in `yo_help(\"dashboards/drafts\")`.\n- **Branch previews** in more depth are in `yo_help(\"repo/branches\")`.\n- **A repo that isn't on GitHub** was published with the CLI. There's no clone\n to author in, so it can't be changed this way.\n",
2004
+ "dashboards/authoring.md": '---\ndescription: How to author a dashboard \u2014 a self-contained file in the dashboards/ directory that defines its own query; the entry point for dashboard how-to\n---\n\n# Authoring dashboards\n\nA dashboard is a **self-contained `.malloy` file in the `dashboards/`\ndirectory**. The file IS the dashboard: it imports the model parts it needs,\ndefines its query (with the filtering it applies), and tags it. No manifest, and\nfor the basic case no JavaScript. Preview with `malloyyo dashboard dev`; check\nwith `malloyyo lint`. Requires `@malloydata/malloy` 0.0.423+.\n\nRelated: `yo_help dashboards/givens-and-controls` (filter controls),\n`dashboards/grid-layout` (columns/colspan/break), `dashboards/charts` (the\n`# bar_chart`/`# line_chart` tags and their channel rules),\n`dashboards/custom-components` (a flat `<name>.jsx`), `dashboards/vega-charts`\n(`<VegaChart>`).\n\n> **Need a chart the `# bar_chart`/`# line_chart`/`# shape_map` tags can\'t do?**\n> Use the `<VegaChart>` COMPONENT (a Vega-Lite spec over query rows) \u2014 NOT a `#`\n> tag; there is no `# vega_lite`. See `yo_help dashboards/vega-charts`.\n\n## The layout\n\n```\nmodel/\n ecommerce.malloy # sources, reusable views/measures, # drill tags\n givens.malloy # given: declarations (the filter controls)\n index.malloy # imports/exports sources \u2014 the MCP/data surface ONLY\n dashboards/\n overview.malloy # one dashboard; the FILENAME is its name/slug\n overview.jsx # optional custom component for overview\n```\n\n**The filename is the dashboard\'s name** \u2014 its URL slug, its `# drill` target,\nand the basename of its optional component. Discovery globs\n`dashboards/*.malloy` and compiles EACH as its own entry \u2014 so dashboards are NOT\ndeclared in, or exported through, `index.malloy` (`index.malloy` is just the\n`query`/`describe_source` data surface).\n\n## Preferred: put the query IN the dashboard file\n\nDefine the query right in `dashboards/<name>.malloy` and tag it `# artifact`, so\nthe given mapping (the `where: \u2026 ~ $GIVEN`) is visible next to the dashboard:\n\n```malloy\n// dashboards/overview.malloy\n##! experimental.givens\nimport "../ecommerce.malloy" // BARE import: source + givens in scope\n\n#" Business health at a glance \u2014 sales, margin, orders.\n# artifact { title="Business Overview" } dashboard {columns=6}\nquery: overview is order_items -> {\n where: // the given mapping, HERE\n inventory_items.product_brand ~ $BRAND, // multi-filter where: is\n inventory_items.product_category ~ $CATEGORY, // COMMA separated\n created_at ~ $PERIOD\n # colspan=2\n aggregate: total_sales, total_gross_margin, order_count\n # colspan=3\n nest:\n # line_chart\n sales_trend is by_month\n top_brands\n # shape_map\n sales_by_state\n}\n```\n\nThat\'s a complete dashboard: the runtime auto-renders a title (the tag\'s\n`title`, else the `#"` doc), a control for every given the query references, and\nthe result panel. `# artifact` DECLARES the dashboard; `# dashboard {columns=6}`\nis the renderer tag that draws it as KPI tiles + a card grid \u2014 partners, on the\nsame line. Grid rules: `yo_help dashboards/grid-layout`.\n\n**You know you\'re doing it right when the `where: foo ~ $FOO` is in the DASHBOARD\nfile, not the model.** Keep the model\'s sources/views reusable and given-free;\neach dashboard decides its own filtering.\n\n**The bare import is required for controls.** A control renders only when the\ngiven\'s DECLARATION is in the dashboard file\'s scope \u2014 a bare\n`import "../ecommerce.malloy"` (or `import "../givens.malloy"`) brings them all;\nthe runtime shows a control for exactly the givens the query references. A\nselective `import { order_items } from \u2026` brings the filter but NOT the control.\n\nKeep the FILENAME as the name \u2014 don\'t set `name=`, so the URL, the\n`# drill { to=\u2026 }`, and the component basename all agree (one source of truth).\n\n## Other forms\n\n- **A view of a source you extend in the file** \u2014 tag the dashboard `view:` with\n `# artifact` (runs as `<source> -> <view>`). Good when the dashboard needs\n helper views defined alongside it.\n- **Compose existing views**: a model-level `## artifact { tiles=["a -> b", "c -> d"]\n dashboard_columns=6 }` (`##`, ONE line) names several views. Each tile runs as\n its own query (in parallel), and the results are combined into ONE\n `# dashboard` that Malloy\'s dashboard renderer lays out \u2014 so it looks exactly\n like the equivalent single-query dashboard: `dashboard_columns=N` sets the grid\n and `# colspan=N` / `# break` on the tile VIEWS place them. A tile that returns\n a SINGLE ROW with no group-by (an aggregate view) is merged in as top-level KPI\n tiles rather than a card (its `# colspan` is spread across those KPIs). The\n dashboard paints once the tiles are ready, with a single early paint if one tile\n straggles so a slow tile can\'t hold up the rest. Use for multi-tile /\n cross-source; prefer the inline query whenever a dashboard has its own filtering.\n- A `dashboards/*.malloy` with NO `# artifact`/`## artifact` is a shared INCLUDE\n (skipped by discovery) \u2014 put helper sources/views there for several dashboards\n to import.\n\n## Givens (filter controls)\n\nDeclare givens as `filter<T>` in the MODEL (`givens.malloy` or the source file) \u2014\nthey\'re shared and used by the MCP surface too; each dashboard APPLIES them in\nits `where:`. Full control reference: `yo_help dashboards/givens-and-controls`.\nPer-dashboard starting values go in the tag:\n\n```malloy\n# artifact { title="Ford recalls" givens { MANUFACTURER=f\'Ford Motor Company\' } }\n```\n\n## Drill from a dimension\n\n`# drill` on a source `dimension:` (in the model) makes its cells clickable \u2014\nopening another dashboard (seeding the value) or filtering in place:\n\n```malloy\ndimension:\n # drill { to=[category_explorer, self] }\n category is inventory_items.product_category\n```\n\n`to` is a list; each is a **dashboard slug** (a `dashboards/<slug>.malloy`\nfilename) \u2192 opens it, seeding the value into the given named like the dimension\nUPPER-cased (`category` \u2192 `CATEGORY`), or **`self`** \u2192 filter the current\ndashboard in place. Add `given=` when the target given differs. `lint` VERIFIES\nevery `to=` slug resolves to a real dashboard file (a typo/renamed dashboard\nfails loudly, not at click time).\n\n> **malloy#2979 (fixed in 0.0.423):** a `# drill` on a bare `group_by: name` was\n> dropped when nested through `+ {\u2026}`. Put it on the source `dimension:`, or use\n> `group_by: name is concat(name,\'\')`.\n\n## Custom component (optional)\n\nFor bespoke layout/charts, add a flat sibling `dashboards/<name>.jsx` (or\n`.tsx`). Only React + `@malloyyo/dashboard` importable (sandboxed). A bare\n`<Panel/>` renders the whole dashboard; a `<Panel query="\u2026"/>` /\n`<VegaChart query="\u2026"/>` runs a query DEFINED in this dashboard file (by name) or\na `source -> view`. `lint` checks each `query="\u2026"` still resolves. See `yo_help\ndashboards/custom-components`.\n\n## Rules\n- Each dashboard is one `dashboards/<name>.malloy`; the filename is the slug.\n Prefer the inline `query: \u2026 # artifact` form \u2014 the `where: ~ $GIVEN` lives in\n the dashboard file.\n- Bare-import the model (and/or `givens.malloy`) so the controls render.\n- Givens are `filter<T>` declared in the model; options come from `# suggest {\u2026}`;\n interactivity = setting given values, not rewriting query text.\n- `index.malloy` is the data surface, NOT where dashboards live.\n- If a query/given you need is missing, add it (check with `describe_source`).\n\n## Preview & validate\n`malloyyo dashboard dev` \u2192 open the URL; `.malloy`/`.jsx` edits hot-reload.\n`malloyyo lint` checks each dashboard file on its own: it compiles as its entry;\neach tile/query and `# suggest` compiles; `dashboard_columns` is a positive int;\nthe component compiles and its `query="\u2026"` resolve; no duplicate names, no\norphaned component; every `# drill { to=\u2026 }` resolves. Tight loop: the local\n`malloyyo mcp --develop` server hot-reloads edits \u2014 `query(execute:false)` to\ncompile-check, `execute:true` to run. Don\'t validate against a hosted/claude.ai\nconnector \u2014 it serves the PUBLISHED model (stale until `malloyyo publish`).\n',
2005
+ "dashboards/charts.md": "# Charts (`# bar_chart`, `# line_chart`, \u2026)\n\nFor answering one question with a picture, see `yo_help explore/charting-results`;\nthis topic is about dashboard tiles, the dimension-counting rule, and sorting a\nnamed axis.\n\nThe renderer's built-in chart tags cover most dashboard tiles. Tag a nested view\nand it draws:\n\n```malloy\nnest:\n # bar_chart\n sales_by_brand\n # line_chart\n sales_by_month\n```\n\nRelated: `yo_help dashboards/grid-layout` (where tiles sit),\n`dashboards/vega-charts` (`<VegaChart>`, for shapes these tags can't express),\n`dashboards/authoring` (the dashboard file itself).\n\n## Channels: name them, don't leave them to be guessed\n\nA chart has three channels \u2014 **x** (the category axis), **y** (the value), and\n**series** (the colour split). Set them on the tag:\n\n```malloy\n# bar_chart { x=weekday y=drunk }\n# bar_chart { x=nickname y=flight_count series=destination }\n# line_chart { x=sale_date y=['sales', 'cost'] }\n```\n\nLeft unset, the renderer infers them: x prefers a time dimension and otherwise\ntakes the first dimension, y takes the first aggregate, and **series takes any\ndimension left over**. That last rule is the one that surprises people \u2014 see\nbelow. Naming `x` and `y` explicitly costs one line and removes the guesswork.\n\nOther properties: `.stack`, `.size` (`spark`/`xs`/`sm`/`md`/`lg`/`xl`/`2xl`, or\n`size.width` / `size.height`), `.x.limit`, `.series.limit`, and `.independent`\non any channel for nested charts.\n\n## THE RULE: charts count DIMENSIONS, not columns\n\nA chart can carry **one x dimension and one series dimension**. The renderer\ncounts the *dimensions* in the result (`group_by` fields \u2014 not aggregates) and:\n\n- **two dimensions, only `x` named** \u2192 the spare one is promoted to a colour\n series, whether or not you wanted a legend\n- **three or more dimensions, none tagged `series`** \u2192 it refuses:\n *\"Too many dimensions. A bar chart can have at most 2 dimensions: 1 for the x\n axis, and 1 for the series. To use 3+ dimensions, explicitly tag multiple\n fields as series.\"*\n\nThat last sentence is the escape hatch: 3+ dimensions is legal if you say which\nones are the series. What is NOT legal is leaving it to be inferred. If you\ngenuinely want a third dimension in the picture, name it; if you don't, the\nproblem is that a field you didn't think of as a dimension is one.\n\nAggregates are exempt. A result can carry as many measures as you like \u2014 only\nthe ones named in `y` (or the first, if `y` is unset) get plotted, and the rest\nare ignored rather than turned into channels.\n\n**`# hidden` does not exempt a dimension from this count.** It hides a field in\ntables, `big_value` comparisons and `# link` targets; it has no effect on chart\nchannel assignment. A `# hidden` group_by is still a dimension and will still\nbecome a series.\n\n## Sorting a named axis (the common case this rule makes hard)\n\nYou want an axis labelled `Sunday \u2026 Saturday`, or `Jan \u2026 Dec`, in *that* order \u2014\nnot alphabetical. The label has to be a string, but the sort key is a number, and\nthe naive fixes both fail:\n\n```malloy\n// WRONG \u2014 two dimensions: weekday_num becomes a colour series.\ngroup_by:\n # hidden\n weekday_num is day_of_week(exit_date)\n weekday is pick 'Sunday' when day_of_week(exit_date) = 1 \u2026\n```\n\n```malloy\n// ALSO WRONG \u2014 a `select:` stage is a projection, so it has no measures:\n// every column becomes a dimension and a 3-column result is rejected.\n} -> {\n select: weekday is pick 'Sunday' when weekday_num = 1 \u2026 , drunk, avg_price\n}\n```\n\n**Make the sort key a MEASURE.** Measures aren't dimensions, so a sort key\nexpressed as one can never be promoted to a channel:\n\n```malloy\n# bar_chart { x=weekday y=drunk }\nview: by_weekday is {\n group_by: weekday is\n pick 'Sunday' when day_of_week(exit_date) = 1\n pick 'Monday' when day_of_week(exit_date) = 2\n \u2026\n else 'Saturday'\n aggregate:\n drunk\n weekday_sort is min(day_of_week(exit_date)) // orders rows; never a channel\n order_by: weekday_sort asc\n}\n```\n\nOne dimension reaches the chart, the rows arrive in the order you asked for, and\na bar chart preserves query row order for a categorical axis. The same shape\nworks for months (`min(month(date))`), fiscal periods, size buckets, and any\nother \"display a name, sort by a number\" axis.\n\n> `min()` because a sort key needs *some* aggregate function and every row in the\n> group shares the value; `max()` is equally fine.\n\n## Deciding which tile is a chart at all\n\n- **Ranked categories** (top brands, regions by volume) \u2014 `# bar_chart`, ordered\n by the measure. Query order is the bar order.\n- **A value over time** \u2014 `# line_chart` with the time dimension as `x`.\n- **A wide detail table** \u2014 no chart tag. Charting eight columns is worse than\n showing them; give the tile `# colspan=6` instead and label the columns.\n- **Flat data** \u2014 if every bar is within a few percent of the others, the chart\n is saying \"no pattern here\" at the cost of a card. Consider whether the tile\n earns its place.\n\n## Trends by period: drop the incomplete one\n\nA by-year or by-month trend whose final period is partial draws a cliff that\nreads as collapse. Filter to complete periods, using a cutoff that comes from\nthe DATA (e.g. a snapshot/max-date column carried on a joined dimension), not\nfrom the result set \u2014 deriving it from the visible rows will wrongly declare a\nperiod partial as soon as a filter narrows the data.\n\n## Validate\n\n`malloyyo lint` compiles each dashboard and its tiles, but it does not render\nthem \u2014 a chart that compiles can still throw \"Too many dimensions\" in the\nbrowser. See it with `malloyyo dashboard dev`, which runs the queries\nserver-side and renders the real result.\n",
2006
+ "dashboards/custom-components.md": '---\ndescription: Custom dashboard UI \u2014 a flat dashboards/<name>.jsx|tsx sibling composing @malloyyo/dashboard widgets/hooks/helpers with your own React\n---\n\n# Custom dashboard components (`dashboards/<name>.jsx`)\n\nThe default UI (auto-rendered controls + panel) covers most dashboards. When it\nisn\'t enough, add ONE file \u2014 a **flat sibling** `dashboards/<name>.jsx` (or\n`.tsx`) next to the dashboard\'s `dashboards/<name>.malloy` (same basename) \u2014 that\ncomposes the runtime\'s widgets/hooks with your own React. You own layout, copy,\nand theming; the `.malloy` file still owns every query and filter. See also\n`yo_help dashboards/authoring` and `dashboards/vega-charts`.\n\n```tsx\nimport React from "react";\nimport { Controls, Given, Search, Select, TimeRange, Panel, filters, useGiven } from "@malloyyo/dashboard";\n\nexport default function Dashboard({ dashboard, givens }) {\n return (\n <div style={{ maxWidth: 860, margin: "0 auto", padding: 24 }}>\n <h1>{dashboard.title}</h1>\n <Controls>\n <Given name="STATE" /> {/* picks the control from the declaration */}\n <Search given="NAME" /> {/* committing input + typeahead + validation */}\n <TimeRange given="PERIOD" presets={[\n { value: "", text: "All time" },\n { value: filters.lastN(1, "day"), text: "Last day" },\n { value: filters.lastN(1, "week"), text: "Last week" },\n { value: filters.lastN(1, "month"), text: "Last month" },\n ]} /> {/* "Custom range\u2026" is always appended */}\n <Select given="MIN_SAMPLE"\n options={[10, 200, 1000].map(n => ({ value: filters.greaterThan(n), text: `> ${n}` }))} />\n </Controls>\n <Panel givens={givens} /> {/* the dashboard itself (its tiles/query) */}\n <Panel query="baby_names -> births_by_decade" givens={givens} /> {/* a specific query */}\n </div>\n );\n}\n```\n\nFrom `@malloyyo/dashboard` (also handed to the component as props):\n- **Widgets** (headless-ish; restyle via className/style or the `--dash-*` CSS\n vars \u2014 see Theming below): `<Controls/>` (all givens, or compose children;\n grows Apply/Reset under `autorun=false`), `<Given name/>`,\n `<Select given [options]/>`, `<Search given/>` (committing input + typeahead +\n inline \u2715 clear), `<MultiSelect given [options]/>` (chip multi-select for a\n `filter<string>` \u2014 commits an exact-match list via `filters.oneOf`),\n `<Range given [min max]/>`, `<TimeRange given [presets]/>` (temporal presets +\n custom range), `<Checkbox given/>` (bound to a boolean given),\n `<VegaChart spec query|malloy|data givens/>` (a Vega-Lite chart over query\n rows \u2014 see `yo_help dashboards/vega-charts`)\n- **Hooks**: `useGiven(name)` \u2192 {value, set, spec};\n `useOptions(name, typed?)` \u2192 {options, loading} (typeahead);\n `useQuery({query|malloy, givens})` \u2192 {rows, loading, error, truncated} \u2014\n plain rows for your own visuals; `truncated` is null, or {reason, hint}\n when the 5,000-row limit cut the result (aggregate in Malloy, or say so on\n the chart \u2014 `<VegaChart>` and tag-only dashboards already do);\n `useUrlState(key, initial)` \u2192 [value, setValue] \u2014 shareable view-state (below)\n- **Helpers**: `filters.oneOf/contains/between/atLeast/\u2026` build\n filter-expression strings with correct escaping; temporal:\n `filters.lastN(7, "day")` \u2192 `\'7 days\'`, `filters.dateRange("2026-01-01",\n "2026-07-01")`, `filters.afterDate/beforeDate`; read back with\n `filters.values/numberRange/threshold/inLast/temporalRange`;\n `filters.isValid(type, src)` checks typed input.\n Never hand-concatenate a filter string.\n **Escaping rule for custom controls:** a filter given\'s value is an\n EXPRESSION, so committing a raw column value is wrong the moment it contains\n a comma/percent/dash (\'Tesla, Inc.\' parses as two alternatives and matches\n nothing). Commit `filters.oneOf(value)` (exact) or\n `filters.contains(term)` (substring), and unwrap for display with\n `filters.values(src)`. The stock `<Select/>` does this automatically;\n `<Search/>` deliberately commits raw text (its input IS a filter\n expression).\n- `<Panel/>` runs against the DASHBOARD\'s own file: a bare `<Panel/>` renders\n the whole dashboard (its tiles); `<Panel query="\u2026"/>` runs a query defined in\n the dashboard file (by name) or a `source -> view`; `<Panel malloy="\u2026"/>` and\n `runData(text, givens)` run arbitrary Malloy as a RESTRICTED query (no import /\n given: / connection.* / raw SQL / ##! flags \u2014 the model\'s governed surface\n only). `lint` checks each hard-coded `query="\u2026"` still resolves.\n\n## Shareable view-state: `useUrlState`\n\n`useState` is invisible to the page that owns the URL, so a component built on\nit has an address bar that never changes \u2014 the result can\'t be shared or\nbookmarked. **`useUrlState(key, initial)` is a `useState` twin whose value lives\nin the URL**, under a `~key` param:\n\n```jsx\nimport { useUrlState } from "@malloyyo/dashboard";\n\nconst [rack, setRack] = useUrlState("rack", ""); // string\nconst [reuse, setReuse] = useUrlState("reuse", false); // boolean\nconst [board, setBoard] = useUrlState("board", "........"); // string\nconst [topN, setTopN] = useUrlState("n", 20); // number\n```\n\n- Same shape as `useState`: `[value, setValue]`, and `setValue` takes a value\n **or** an updater fn (`setBoard(b => \u2026)`).\n- The value comes from the URL on load, else `initial`. Every change is written\n back (debounced, `replaceState` \u2014 no history spam), so the address bar is\n always a shareable link.\n- Typed by `initial`: string / number / boolean / any JSON-serializable value.\n Strings stay readable in the URL (`~rack=retinas`); objects and arrays are\n JSON. A value equal to `initial` is dropped from the URL, so defaults never\n clutter it, and a malformed value falls back to `initial` instead of throwing.\n- Works identically in `malloyyo dashboard dev`, on a bundled static site, and\n on a hosted instance \u2014 including inside the sandboxed iframe, which cannot\n reach the top-level URL on its own. That\'s why this is a hook and not\n something a component can do with `history.replaceState`.\n\n**Use it for view-state, not query parameters.** A `given:` is the governed,\nfilter-typed query contract: it\'s declared in the model, drives the default\ncontrols, and is visible over MCP \u2014 bind those with `useGiven` and they already\nround-trip through the URL as `$NAME`. `useUrlState` is for everything else a\ncustom component needs to make shareable: a letter rack whose real query inputs\n(allowed letters, min/max length) are computed from it in JS, a board layout, a\nmode toggle. The two namespaces (`$NAME` vs `~key`) never collide.\n\n## Theming\n\nEvery widget is styled by the runtime\'s **default Malloyyo theme** (system\nfont, neutral grays, blue accent, auto light/dark following the viewer\'s OS) \u2014\na bare component looks styled with zero effort, so DON\'T hand-hardcode\n`fontFamily`/colors. The theme is CSS custom properties; override any subset by\nsetting them on a wrapper element (more specific than the runtime\'s `:root`):\n\n```tsx\n<div style={{ "--dash-accent": "#e11d48", "--dash-controls-bg": "#faf5ff" }}>\n <Controls /> \u2026\n</div>\n```\n\nVars: `--dash-font`, `--dash-bg`, `--dash-fg`, `--dash-muted`, `--dash-border`,\n`--dash-accent`, `--dash-accent-fg`, `--dash-control-bg`, `--dash-controls-bg`,\n`--dash-chip-bg`, `--dash-chip-fg`, `--dash-panel-bg`, `--dash-radius`,\n`--dash-danger`. `DefaultDashboard` also takes a `theme={{ accent, controlsBg }}`\nprop (camelCase keys \u2192 `--dash-*`). The results `<Panel>` keeps a light surface\nin both light/dark (the Malloy renderer has no dark theme) \u2014 override\n`--dash-panel-bg` if your renderer output is dark-safe.\n\n**Use `--dash-*` and nothing else.** A custom component renders in its own\n**iframe**, so CSS variables defined by the surrounding page \u2014 including the\nbundled site\'s `--line` / `--card` / `--muted` \u2014 are NOT in scope inside it. A\ncomponent styled against those still renders, but every rule referencing them\nresolves to nothing: borders, dividers and panel backgrounds vanish silently\nwhile text and layout survive, so the page looks *almost* right and the cause\nisn\'t obvious. If you\'re porting CSS that has to work both inside the frame and\non a bundled page, resolve each colour once through the chain and use the alias:\n\n```css\n.my-card {\n --edge: var(--dash-border, var(--line, #e4e6eb));\n --surface: var(--dash-panel-bg, var(--card, #fff));\n border: 1px solid var(--edge);\n background: var(--surface);\n}\n```\n\nThis is a class of bug `lint` cannot see and a screenshot can \u2014 look at custom\ncomponents in `malloyyo dashboard dev` before shipping them.\n\nFor charts beyond the Malloy renderer\'s `#` tags, use `<VegaChart>` \u2014\n`yo_help dashboards/vega-charts`.\n',
2007
+ "dashboards/drafts.md": "---\ndescription: Writing a draft dashboard from a chat client \u2014 one component file, queries inline, saved with save_draft_dashboard; and how one is promoted into the model repo\n---\n\n# Draft dashboards (`save_draft_dashboard`)\n\nA draft is a dashboard stored on this instance rather than in the model repo.\nIt gets a URL, renders like any other dashboard, and can be re-saved as often\nas you like. Read this before writing one.\n\n## The shape\n\nONE React component, default-exported, whose queries are Malloy written inline:\n\n```tsx\nimport { useQuery } from \"@malloyyo/dashboard\";\n\nexport default function Dashboard() {\n const top = useQuery({\n malloy: `run: flights -> { group_by: carrier; aggregate: flight_count; limit: 10 }`,\n });\n const rows = top.rows ?? [];\n return (\n <div style={{ padding: 24 }}>\n <h1 style={{ fontSize: 22, fontWeight: 600 }}>Top carriers</h1>\n {top.loading ? <p>Loading\u2026</p> : <ol>{rows.map((r) => (\n <li key={String(r.carrier)}>{String(r.carrier)}: {Number(r.flight_count).toLocaleString()}</li>\n ))}</ol>}\n </div>\n );\n}\n```\n\nSave it with `save_draft_dashboard({ dataset, name, title, source })`. The\nresult carries a `url` to open and a `dashboard` name that `show_dashboard`\nrenders. Pass the returned `slug` back on the next save to update the same\ndraft instead of making another.\n\n## The queries\n\nInline Malloy runs against what the model PUBLISHES \u2014 the same rules as the\n`query` tool. You may define your own sources, measures and joins derived from\nthe model's sources. You may not `import`, open a connection, write raw SQL, or\ndeclare `given:`. Check a query with `query(execute:false)` before you put it\nin a component; the save also compiles every literal query it finds and reports\nwhat failed.\n\nWrite the whole query as one template literal. A query built by string\nconcatenation can't be checked at save time and only fails when a reader opens\nthe dashboard.\n\n## What you can import\n\nOnly these resolve:\n\n| Import | What you get |\n|---|---|\n| `react` | React itself, hooks included |\n| `@malloyyo/dashboard` | `useQuery`, `useGiven`, `useOptions`, `useUrlState`, `runData`, `filters`, `VegaChart`, `Field`, and the controls: `Controls`, `Given`, `Select`, `Search`, `MultiSelect`, `Range`, `Checkbox`, `TimeRange` |\n\nNothing else \u2014 no chart library, no icon set, no CSS framework, no `fetch`.\nUse inline `style` objects, plain HTML, and `VegaChart` (see\n`yo_help dashboards/vega-charts`) for charts.\n\n`useQuery` returns `{ rows, result, loading, error, truncated }`. `rows` is\nan array of plain objects, at most 5,000 of them; `truncated` is null, or\n`{ reason, hint }` when that limit cut the result. Aggregate in Malloy rather\nthan plotting a prefix as if it were the whole answer \u2014 `<VegaChart>` notes a\ncut result on the page; anything you draw from `rows` yourself must say so\nitself. Numbers can arrive as BigInt or decimal objects, so wrap them\nwith `Number()` before `.toLocaleString()` or arithmetic, and format dates in\nMalloy rather than in JavaScript.\n\n## Presentation\n\n- One clear page title, then the content. No wrapper card around everything.\n- Put a few headline numbers in a row, value large (~40px) with a small label\n beneath; don't stack them vertically.\n- Give each query-backed section its own loading and error state, so a slow one\n doesn't blank the page.\n- Prefer a table under ~8 categories, where exact values and ranking matter;\n use a chart when shape or trend is the point.\n- Keep charts responsive in width and roughly 200\u2013280px tall.\n- Say what the data shows. Don't call a change strong, concerning or surprising.\n\n## When to add a `.malloy` file instead\n\nPass `malloy` as well when the dashboard needs:\n\n- **filters/controls** \u2014 declare givens in the model and the controls render\n themselves (`yo_help dashboards/givens-and-controls`);\n- **named queries** shared across several tiles, or a composite grid\n (`yo_help dashboards/authoring`);\n- **no code at all** \u2014 a tagged Malloy query renders through Malloy's own\n renderer, which is often the better dashboard.\n\nThat file is `dashboards/<name>.malloy`: it imports `\"../index.malloy\"` and\ntags a query `# artifact`.\n\n## Promotion\n\nA draft lives on the instance; the model repo is where dashboards belong. To\nmove one in, from a checkout of the repo:\n\n```bash\nmalloyyo draft list # find the slug\nmalloyyo draft promote <slug> # writes dashboards/<name>.malloy + component\n```\n\nPromotion writes the files and records what the draft became; it never deletes\nthe draft, whose URL people may already hold. A draft whose queries are inline\nneeds them LIFTED into its `.malloy` as named queries \u2014 the component then uses\n`useQuery({ query: \"<name>\" })` \u2014 because a repo dashboard's queries live in\nthe model, not the component. The written `.malloy` carries them as comments to\nwork from. Then `malloyyo lint`, and the usual PR.\n\n**From a clone, without the CLI** (Claude Code on the web):\n\n1. `get_draft_dashboard(dataset, dashboard)` returns the draft's files.\n2. Write them into the clone as `dashboards/<name>.malloy` plus its component,\n lifting the inline queries as described above.\n3. `preview_changes` to see it compiled and rendered (`yo_help(\"authoring/start\")`).\n4. Commit, then call\n `mark_draft_promoted(dataset, dashboard: \"draft-<slug>\", promoted_as: \"<name>\")`.\n\n`malloyyo draft promote` records the promotion itself.\n\n**What happens to the draft.** Once the dataset publishes the promoted\ndashboard, the draft's URL **redirects** to it, keeping any query string, and\nthe draft drops out of listings. Saved links keep working, and nobody picks the\nstale copy from a menu. Until then the draft serves as before.\n\n## Deleting a draft\n\n`delete_draft_dashboard(dataset, dashboard)`, **Delete draft** on the draft's\npage, or `malloyyo draft delete <slug>`. Its author or an admin can. Its link\nstops working, so ask the person first. A promoted draft that's already\npublished doesn't need deleting, and deleting it ends the redirect.\n\n## Iterating\n\n1. `list_sources`, then `describe_source` for the source you'll query.\n2. Validate each query with `query(execute:false)`.\n3. Save the draft; fix anything the report names.\n4. Show the user the URL (or `show_dashboard`), and ask what to change.\n5. Re-save with the same `slug`.\n",
2008
+ "dashboards/givens-and-controls.md": "---\ndescription: Dashboard filter controls \u2014 declare filter<T> givens with # label / suggest / control tags; faceted (related) suggestions\n---\n\n# Dashboard givens & controls\n\nOne given is NOT a control: `$MALLOYYO_EMAIL` is filled from the signed-in\nuser, cannot be set by a caller, and renders no filter \u2014 see\n`yo_help language/who-is-asking` for per-user data.\n\nA dashboard's filters are `filter<T>` **givens** declared in the model; the\n`#` tags on each declaration drive its control. This is part of authoring a\ndashboard \u2014 see also `yo_help dashboards/authoring`.\n\n**Declare the filters as `filter<T>` givens** \u2014 never raw strings/numbers.\nA `filter<string>` value accepts one value ('NY'), alternatives ('NY, CA'),\nwildcards ('Ann%'), negation ('-NY'); a `filter<number>` accepts ranges\n('[1910 to 1930]') and comparisons ('> 200'); a `filter<timestamp>` /\n`filter<date>` accepts relative windows ('7 days' = the last 7 days, 'today',\n'last month') and literal ranges ('2026-01-01 to 2026-07-01' \u2014 NO `@` in\nfilter literals). Apply with `~`; `f''` = empty = no filter (the natural\n\"All\"/\"all time\" \u2014 just `col ~ $X`, no `$X = '' or \u2026` dance):\n\n```malloy\n##! experimental { givens }\ngiven:\n # label=\"State\" control=select suggest { source=baby_names dimension=state }\n STATE :: filter<string> is f'NY'\n # label=\"Brand\" suggest { query=brand_suggest dimension=product_brand }\n BRAND :: filter<string> is f''\n # label=\"Names\" control=multiselect suggest { query=name_suggest dimension=name }\n NAMES :: filter<string> is f''\n # label=\"Years\" range_min=1910 range_max=2025\n YEAR_RANGE :: filter<number> is f'[1910 to 1930]'\n # label=\"Time period\"\n PERIOD :: filter<timestamp> is f''\n # label=\"Include rare names\"\n INCLUDE_RARE :: boolean is false\n```\n\nTags on the declaration drive the control (tag syntax is `key=\"value\"` \u2014\nequals, not colon):\n- `label` \u2014 control caption (defaults to the given's name)\n- `suggest { \u2026 }` \u2014 where the control's options come from. NO Malloy code in\n strings \u2014 just names:\n - `suggest { query=brand_suggest dimension=product_brand }` \u2014 the FIRST\n COLUMN of a named query (declare the query in the model \u2014 governed and\n reviewable). PREFER THIS FORM. The query must be in scope where the dashboard\n runs (bring it in with the dashboard file's bare `import`).\n - `suggest { source=baby_names dimension=state }` \u2014 the DISTINCT VALUES of\n a dimension on a source (the source must be in the dashboard's scope)\n A `dimension` (in either form) is what enables SERVER-SIDE TYPEAHEAD: the\n runtime refines the base query with what the user has typed\n (`\u2026 + { where: lower(field) ~ f'll%'; limit: 50 }`, case-insensitive,\n escaped). Without a dimension the fetched list is filtered client-side.\n Runs as a restricted query; lint checks the declaration compiles.\n\n **RELATED (faceted) filters** \u2014 query-form only: a suggest query may\n reference the OTHER givens, and the runtime runs it with the dashboard's\n current values (the suggested given itself is excluded, so the list never\n collapses to the current pick). Brand suggestions narrow when Category is\n set:\n\n ```malloy\n query: brand_suggest is inventory_items -> product_brand + {\n where:\n product_category ~ $CATEGORY, // NOT product_brand ~ $BRAND\n product_department ~ $DEPARTMENT\n limit: 500\n }\n ```\n\n Declare one `*_suggest` per filter, each referencing the others; `f''`\n defaults mean unset filters don't constrain. `source=` suggests can't do\n this (no place for a `where:`) \u2014 another reason to prefer `query=`.\n- `control=select` \u2014 a fixed dropdown instead of a typeahead search box\n- `control=multiselect` \u2014 a tokenized multi-select for a `filter<string>`:\n each pick is a removable chip, the committed value is an exact-match list\n (`Emma, Olivia, Sophia`). Ideal for \"pick several\" filters (names, brands).\n Suggestions come from the given's `suggest {\u2026}` (server-side typeahead when\n it names a dimension). Empty (start from `f''`) = no filter (all).\n- `range_min` / `range_max` \u2014 bounds; makes a filter<number> given a\n dual-thumb range slider\n- anything else passes through in `spec.tags` for custom components\n\nControl picked from the declaration automatically: numeric range tags \u2192\ndual-thumb slider; `filter<timestamp|timestamptz|date>` \u2192 the TimeRange\nwidget (relative presets: Today / Last 7 days / Last 30 days / \u2026 plus a\n\"Custom range\u2026\" from/to date picker); `control=multiselect` \u2192 chip\nmulti-select; suggest + control=select \u2192 dropdown; boolean \u2192 checkbox;\nanything else \u2192 committing search box with typeahead (an inline \u2715 clears it;\na \"Press \u21B5 to apply\" hint shows while the typed draft differs from what's\nrunning \u2014 free text can't safely re-run per keystroke).\nThe suggest-driven options are DATA VALUES only \u2014 options that aren't column\nvalues (custom time presets, threshold buckets) need a custom component\n(`yo_help dashboards/custom-components`) with explicit `{value, text}` options\nwhere value is a filter expression built with `filters.*`.\n\n## When the query re-runs: live (default) vs. Apply\n\nBy default a dashboard is **live** \u2014 every control change re-runs the query\nimmediately (the committing search box is the exception: free text commits on\nEnter/blur, since a half-typed filter is invalid). To batch changes behind an\n**Apply** button instead, set `autorun=false` on the `# artifact` tag:\n\n```malloy\n# artifact { name=\"births-by-name\" title=\"Births by name\" autorun=false }\n```\n\n`autorun=false` makes `<Controls>` grow an Apply/Reset pair \u2014 controls edit a\ndraft and nothing re-runs until Apply. Reach for it when the query is expensive\nor several filters are usually changed together; leave it off (live) otherwise.\n",
2009
+ "dashboards/grid-layout.md": "---\ndescription: Dashboard grid layout \u2014 # dashboard {columns=N} with # colspan and # break to place KPI tiles and charts\n---\n\n# Dashboard grid layout (`# dashboard {columns=N}`)\n\nBy default a `# dashboard` result flows its KPI tiles and cards and wraps.\nAdd `{columns=N}` to place them on a fixed **N-column grid** instead \u2014 use\n`columns=6`, which divides evenly into 2- and 3-wide cards.\n\n**Key mechanic:** a tag placed ABOVE `aggregate:` or `nest:` applies to EVERY\nitem declared in that block. So you set card widths once per block, not per\nfield.\n\n```malloy\n# artifact { title=\"Customer Insights\" } dashboard {columns=6}\nview: customer_insights is {\n where: created_at ~ $PERIOD\n # colspan=2\n aggregate: total_sales, user_count, order_count, average_order_value\n # colspan=3\n nest:\n # break\n # bar_chart\n users_by_spend_tier\n sales_by_traffic_source\n # shape_map\n sales_by_state\n # colspan=6\n recent_orders // wide detail table \u2192 full width\n}\n```\n\n## The conventions\n\n- **`# colspan=2` above `aggregate:`** \u2014 each KPI / measure tile spans 2 of 6\n columns \u2192 3 tiles per row.\n- **`# colspan=3` above `nest:`** \u2014 each graph or small table spans 3 \u2192 2 per\n row. Per-item render tags (`# line_chart`, `# bar_chart`, `# shape_map`) still\n go on the individual nested items.\n- **`# colspan=6`** \u2014 a single wide / many-column table gets its own full-width\n line. Tag that one item; a per-item `# colspan` overrides the block default.\n- **`# break` on the FIRST nest item** \u2014 starts the graphs on a fresh row, so\n KPI tiles and charts never share one. The renderer splits fields into a new\n grid at each `# break`. Just always add it: it's a no-op when the tiles\n already fill complete rows, and the fix when they don't (e.g. 4 measures\n leave a lone tile a colspan-3 chart would otherwise pack in beside).\n\n`# colspan` only does anything in columns mode \u2014 without `{columns=N}` the\nlayout is free-flow wrap and colspan is ignored. Clamp colspans to `1..N`.\n\nSee also `yo_help dashboards/vega-charts` for custom charts, and the fuller\nauthoring guide surfaced by the local `malloyyo mcp` server.\n",
2010
+ "dashboards/vega-charts.md": '---\ndescription: Custom dashboard charts with Vega-Lite \u2014 the <VegaChart> component, for charts the # renderer tags can\'t do\n---\n\n# Custom charts with Vega-Lite (`<VegaChart>`)\n\nWhen Malloy\'s renderer tags (`# bar_chart`, `# line_chart`, `# shape_map`, \u2026)\ndon\'t cover the chart you want, a dashboard can draw a **Vega-Lite** spec with\nthe `<VegaChart>` component. The chart engine ships in the dashboard runtime, so\nyou author only a JSON spec + a Malloy query \u2014 no library to load.\n\n**It is a COMPONENT, not a `#` tag.** There is no `# vega_lite` or\n`# scatter_chart` tag. `<VegaChart>` lives in a custom component \u2014 a flat sibling\n`dashboards/<name>.jsx` (or `.tsx`) next to the dashboard\'s\n`dashboards/<name>.malloy` \u2014 a different layer from the `#` renderer tags. (The\ndashboard\'s query is declared in the `.malloy` file; the component only\ncustomizes presentation. Preview with `malloyyo dashboard dev`, validate with\n`malloyyo lint`.)\n\n## The recipe\n\n```tsx\nimport { VegaChart } from "@malloyyo/dashboard";\n\n// Encodings point at the query\'s OUTPUT COLUMN NAMES (here: name, births).\nconst spec = {\n mark: { type: "bar", tooltip: true },\n encoding: {\n y: { field: "name", type: "nominal", sort: "-x" },\n x: { field: "births", type: "quantitative" },\n },\n};\n\nexport default function Dashboard({ givens }) {\n return <VegaChart spec={spec} query="births_by_name" givens={givens} />;\n}\n```\n\nThree ways to feed it data:\n- `<VegaChart spec={spec} query="births_by_name" givens={givens}/>` \u2014 a query\n defined in the dashboard\'s `.malloy` file (by name), or a `source -> view`\n- `<VegaChart spec={spec} malloy="source -> view" givens={givens}/>` \u2014 restricted\n Malloy text (same governance as the explore surface: no import / given: /\n connection.* / raw SQL / ##! flags)\n- `<VegaChart spec={spec} data={rows}/>` \u2014 rows you already have from `useQuery`\n\n## Gotchas (the ones that actually bite)\n\n- **Shape the data in Malloy; return FLAT rows.** Do ranking, share/percent\n (`all(x, dim)`), and label lookups (a `pick` for month names) in the QUERY.\n The spec just encodes columns \u2014 it is not the place to reshape data.\n- **Match column names character-for-character.** Run the query once with\n `query(execute:true)` and read the exact output column names; the spec\'s\n `field` values must match them exactly.\n- **The spec\'s `data` is ignored / any `url` is stripped.** The frame has no\n network \u2014 remote data URLs, transform lookups, and remote `image` marks are\n removed. Adapting a Vega-Lite gallery example = delete its\n `"data": {"url": \u2026}` and repoint the encodings; the query rows are inlined for\n you as the dataset.\n- **Nests come back as arrays.** Flatten to plottable rows in the query, or bind\n a nest to its own chart: `<VegaChart data={row.my_nest}/>`.\n- **Huge integers arrive as strings, on purpose.** Integers serialize as JSON\n numbers, but a value beyond \xB12^53 (a snowflake ID, a 64-bit hash) keeps its\n full precision by staying a string \u2014 JSON has no int64. Bound to a\n `quantitative` or `temporal` channel, Vega-Lite would sort such a column\n lexicographically (`"1","10","11","2"`). If a column can get that big and you\n need to plot it, narrow it in the QUERY \u2014 bucket it, rank it, or emit the\n value you actually want on the axis.\n- **Interactivity = setting given values**, never rewriting query text per\n interaction. Client-side chart interactions (tooltip, zoom, brush) work;\n anything that calls a server does not.\n- **Reads well:** for normalized/share data use a diverging color scale with\n `domainMid` (e.g. `1/12` for month-share), and sort a discrete axis by a\n companion numeric field (`month_name` sorted by `month_num`) rather than\n alphabetically.\n\n## Validate\n\n`malloyyo lint` checks the query, the givens, AND the component (it compiles,\nand each `query="\u2026"` it references resolves) \u2014 your only pre-browser check. Then\n`malloyyo dashboard dev` to see it render.\n',
2011
+ "develop/connection-setup.md": '---\ndescription: Setting up a data connection (malloy-config.json)\n---\n\n# Setting up a data connection\n\nA model reaches its data through a **connection** declared in\n`malloy-config.json` at the **root of the model** (next to `index.malloy`). This\nis Malloy\'s standard connection config \u2014 the full reference, with every\nconnector\'s properties, is at\n<https://docs.malloydata.dev/documentation/setup/config>. The essentials:\n\n## The file\n\n```json\n{\n "connections": {\n "mydb": { "is": "duckdb" }\n }\n}\n```\n\n- A connection has a **name** (the key) and a type (`is`). Sources refer to it by\n that name \u2014 `source: x is mydb.table("orders")` or `mydb.sql("SELECT \u2026")` \u2014 so\n the name in the config must match the name in the model.\n- Supported types (`is`): `duckdb` (incl. MotherDuck), `bigquery`, `postgres`,\n `mysql`, `snowflake`, `databricks`, `trino`, `presto`. Each has its own\n properties \u2014 see the full docs.\n\n## Default connections (and when they apply)\n\nSetting `"includeDefaultConnections": true` makes one connection available for\n**each registered database type, named by the type** \u2014 a `duckdb` connection\nnamed `duckdb`, a `postgres` named `postgres`, and so on. Each uses that\nconnector\'s default settings, which for several backends means picking up\ncredentials from the environment (e.g. BigQuery\'s application-default\ncredentials \u2014 see the per-connector setup docs). Connections you name explicitly\nin `connections` always win; the defaults only fill in types you didn\'t list.\n\n```json\n{\n "includeDefaultConnections": true,\n "connections": { "warehouse": { "is": "postgres", "host": "\u2026" } }\n}\n```\n\nmalloyyo has one rule worth knowing:\n\n- **No `malloy-config.json` at all \u2192 defaults are ON.** `duckdb` just works with\n zero setup.\n- **Write a `malloy-config.json` and they turn OFF** unless you add\n `"includeDefaultConnections": true`. A config that only defines, say, a\n `postgres` connection will report *No connection named "duckdb"* if a source\n still references `duckdb`.\n\nThis is deliberate \u2014 your local connections then resolve exactly the way the\npublished server\'s will, rather than silently leaning on a default that would not\nexist in production. (It differs from `malloy-cli`, which forces the defaults on\nunconditionally.)\n\n*No connection named* has one cause that is **not** about your config: if more\nthan one copy of `@malloydata/malloy` is installed, the connectors register with\none copy and malloyyo reads another, and every connection looks missing. malloyyo\ndetects that and says so instead \u2014 if it doesn\'t mention duplicate copies, the\nproblem really is the config. To check by hand: `npm ls @malloydata/malloy`.\n\nGive a connection a **custom name** \u2014 not the bare type default \u2014 whenever you\nhave more than one connection of the same type, or need non-default parameters.\n\n## DuckDB and local files (the common case)\n\nDuckDB can either open a **DuckDB database file** or read **local data files**\n(CSV, Parquet, \u2026) directly.\n\n**A pre-loaded database file** \u2014 point `databasePath` at a `.duckdb` file and\nreference its tables by name (an absolute path is safest):\n\n```json\n{ "connections": { "warehouse": { "is": "duckdb", "databasePath": "/data/warehouse.duckdb" } } }\n```\n\n**Local files, by path** \u2014 read a CSV or Parquet file straight into a source.\nThese paths are **project-relative** \u2014 resolved against the model root, so they\nsurvive publishing:\n\n source: my_csv is duckdb.table(\'data/my_file.csv\')\n source: my_parquet is duckdb.table(\'data/my_file.parquet\')\n\n`.table()` names a single file. When you need something it can\'t express \u2014 a\nglob, a union, any SQL \u2014 wrap it in `.sql()` (its paths are project-relative too):\n\n source: payments is duckdb.sql(\n "SELECT * FROM read_parquet(\'data/payments-*.parquet\')"\n )\n\nThe default `duckdb` connection is **in-memory** \u2014 nothing persists between runs;\nyour data lives in the files (or the `databasePath` database) you read.\n\n**MotherDuck:** a DuckDB connection against an `md:` database, with its\ntoken named in the config: `"motherDuckToken": { "env": "MOTHERDUCK_TOKEN" }`.\nOn a published instance that is the server\'s own MotherDuck token; any other\nname is a variable the operator set for this model. A connection with no\n`motherDuckToken` doesn\'t pick one up from the server\'s environment.\n\n## Secrets \u2014 keep them out of the file\n\nAny property value may be written as `{ "env": "VAR_NAME" }`. It resolves from\n`process.env.VAR_NAME` when the connection opens, so passwords and tokens never\nget committed:\n\n```json\n{\n "connections": {\n "analytics": {\n "is": "postgres",\n "host": "db.internal",\n "databaseName": "analytics",\n "username": "reader",\n "password": { "env": "PG_PASSWORD" }\n }\n }\n}\n```\n\n(The non-secret property names here are illustrative \u2014 each connector\'s exact\nproperties are in the full docs. The `{ "env": \u2026 }` form is the part that\nmatters: it works for any value.)\n\n## malloyyo specifics\n\n- **One file, one place.** Only the `malloy-config.json` at the model root is\n read \u2014 there is no walk-up to parent directories.\n- **Local override:** a `malloy-config-local.json` (do **not** commit it)\n **replaces** `malloy-config.json` entirely when present \u2014 your private variant\n for local credentials or a different database.\n- **The same file ships to production.** Publishing uploads this exact\n `malloy-config.json`, so it must resolve the same way locally and on the\n server \u2014 put anything environment-specific behind `{ "env": \u2026 }` rather than\n hard-coding it. That is what makes the local test window faithful to\n production.\n- Edits are picked up **without a restart** \u2014 the server re-reads the file when\n it changes.\n\n## When a connection will not resolve\n\nFix the connection **first**: a broken connection yields an empty schema and then\na cascade of misleading `field-not-found` errors \u2014 ignore those and fix the\nconnection. A fast check is to compile a probe and see if it alone compiles:\n\n source: _probe is mydb.sql("SELECT 1 AS one")\n',
2012
+ "develop/documenting-models.md": '---\ndescription: Documenting a model \u2014 what each description is for, where it shows, and how long it should be\n---\n\n# Documenting a model\n\nAn AI reading your published model sees it in two steps. `list_sources` comes\nfirst: every source in every model it can see, so it can pick one. Then\n`describe_source`, for the source it picked: fields, views, joins, and your\nguidance for using it. Each kind of documentation is shown at one of those\nsteps. Put each thing where it is read, at the size it is read at.\n\n| You write | It becomes | Shown in | Keep it to |\n|---|---|---|---|\n| `##"` at the top of `index.malloy` | the model\'s description | `list_sources` | a sentence or two (lint warns past 500 characters) |\n| `#"` above a source | the source\'s description | `list_sources` | one sentence on what the source answers (lint warns past 300) |\n| `#(agent)` above a source | the source\'s instructions | `describe_source` | what someone writing a query must know, in a few short paragraphs |\n| `#"` above a dimension, measure or view | its description | `describe_source` | one line |\n| `#(agent)` above a field | its instructions | `describe_source` | a line or two, only where the name and type don\'t say it |\n\n## Why the sizes matter\n\n`list_sources` is read on every question, before anyone knows which source they\nneed, so every description in it is paid for every time. Ten sources with a\nparagraph each make a listing too large to read in one go. The AI ends up\nsearching it instead of reading it, and can miss the source it needed.\n\n`describe_source` is read once a source has been picked, so it can afford more.\nThat is where the detail goes.\n\n## The model: `##"`\n\nTwo hashes. A single `#"` attaches to the next declaration, so `#"` above the\nfirst source documents that source and leaves the model with nothing.\n\n ##" Orders, customers and products from the online store, as finance reports them.\n\nSay what the dataset is, and for whom. Leave out how to query it; that belongs\nto each source.\n\n## A source: `#"`, then `#(agent)`\n\nThe `#"` is how a reader picks this source over the others. Write it as the\nquestions it answers:\n\n #" One row per order line: revenue, margin and discounts by product, customer and day.\n #(agent) Revenue is net of returns; use `gross_revenue` for the pre-return figure.\n #(agent) Join `customers` for region; `order_date` is in UTC.\n source: order_items is ...\n\nEach `#(agent)` line is joined with the others into the source\'s\n`instructions`. That is the place for grain, the measure to prefer, a filter\nthat is almost always wanted, how two similar fields differ, and what the\nvalues of a coded field mean.\n\nA test: if a sentence in the `#"` only helps someone who has already chosen this\nsource, move it to `#(agent)`.\n\n## Fields and views: one line each\n\n #" Sales after returns, in USD.\n measure: revenue is sale_price.sum() - returned_amount.sum()\n\n #" Top products by revenue this year.\n view: top_products is { ... }\n\n`describe_source` shows these next to each name. A view\'s description is often\nall a reader needs to run it, so give every view one.\n\n## Check it\n\n`malloyyo lint` warns when the model has no `##"`, when an exported source has\nno `#"`, and when either runs past the sizes above. These are warnings, so\nthey never block a publish.\n',
2013
+ "develop/getting-started.md": '---\ndescription: Getting started \u2014 build a Malloy model step by step\n---\n\n# Building a Malloy model, step by step\n\nA model is a `malloy-config.json` (the connection to the data) and an\n`index.malloy` (the published query surface), optionally with other `.malloy`\nfiles that `index.malloy` imports. You edit these with your own file tools; the\nMCP tools compile, inspect, and test what you wrote. Never read `.malloy` as\ntext \u2014 compiling a bare source is how you read a table\'s schema.\n\n## 1. Verify the connection first\n\nConfirm the connection named in `malloy-config.json` resolves \u2014 compile a\nthrowaway probe inline with `compile` (no file needed):\n\n source: _probe is CONN.sql("SELECT 1 AS one")\n\nIf it compiles, the connection is good. If not, fix the connection / config\nbefore going further \u2014 a broken connection produces an empty schema and then a\ncascade of misleading `field-not-found` errors; ignore the cascade and fix the\nconnection. Call `yo_help("develop/connection-setup")` for how to set up or repair a connection.\n\n## 2. Identify the tables the model needs\n\nIf you are unsure which tables matter, ask the fox \u2014 they own the data and know\nwhere it lives.\n\n## 3. Get a base source per table\n\nA base is "what\'s in the table and what\'s computable from it" \u2014 no joins.\nDiscover the schema by compiling a bare stub inline with `compile`:\n\n source: users_base is CONN.table("users")\n\n`compile` returns the full column list + types \u2014 that is your schema browser.\nThen write the base into its own file and iterate with `compile_file`, adding\nonly the dimensions and measures intrinsic to that one table:\n\n // users_base.malloy\n source: users_base is CONN.table("users") extend {\n measure: user_count is count()\n }\n\nIf the data lives in files rather than database tables \u2014 common when the\nconnection is DuckDB \u2014 DuckDB lets you name a file path as the table (a\nproject-relative path):\n\n source: users_base is CONN.table(\'data/users.parquet\')\n\nOnly drop to a `.sql()` block when a single file-as-table can\'t express what you\nneed \u2014 e.g. globbing or unioning several files:\n\n source: users_base is CONN.sql("SELECT * FROM read_parquet(\'data/users-*.parquet\')")\n\n(`read_parquet` there is DuckDB SQL, not Malloy \u2014 see `yo_help("develop/connection-setup")`.)\n\n## 4. Assemble index.malloy \u2014 the published surface\n\nImport the bases, join them into the consumer-facing sources, and explicitly\nexport what consumers may query:\n\n import "users_base.malloy"\n import "orders_base.malloy"\n\n source: users is users_base extend {\n join_many: orders is orders_base on id = orders.user_id\n }\n source: orders is orders_base extend { }\n\n export { users, orders }\n\n**Export discipline** \u2014 the model is a published artifact, so be deliberate about\nits public surface:\n\n- Imported names are private. Base sources stay internal scaffolding unless you\n export them.\n- Without an `export` statement, everything you define is public. Add one and the\n surface becomes explicit: only the names you list \u2014 defined or imported \u2014 are\n public.\n- Hide intermediates. A staging source you define only so other sources can build\n on it should not be exported.\n- The export list is the consumer\'s menu \u2014 exactly what the test window and real\n consumers can query, nothing more.\n\n**Document what you export.** A `##"` for the model, a one-sentence `#"` on each\nexported source (what it answers), and `#(agent)` lines for how to query it.\n`list_sources` shows the short ones on every question, so size matters \u2014 see\n`yo_help("develop/documenting-models")`. `malloyyo lint` warns on missing or\noversized descriptions.\n\n## The loop\n\nEdit a file \u2192 `compile_file` \u2192 fix `problems[]` \u2192 `query` (pass the model file\'s\npath as `ref`; `execute: false` validates first and reports the givens the query\nneeds, supplied via `givens`). Query text is restricted \u2014 `import`, `given:`\ndeclarations, `connection.table`/`connection.sql`, raw SQL, and `##!` flags\nbelong in the model file, not the query. When `compile`/`compile_file` returns\n`formatted: false`, call `prettify` and save its output. Use project-relative\ndata paths, not absolute \u2014 they resolve against the project root and survive\npublishing the model.\n',
2014
+ "develop/working-with-models.md": "---\ndescription: Working with an existing Malloy model\n---\n\n# Working with an existing model\n\nAn existing model is an `index.malloy` (plus any `.malloy` files it imports) and\na `malloy-config.json`.\n\n## Understand the model\n\n- **Read `malloy-config.json` directly** \u2014 it is JSON, so read it as text. It\n lists the connection(s) the model queries against; `yo_help(\"develop/connection-setup\")` explains\n the format (and how to set one up or repair it).\n- **Do NOT read `.malloy` as text \u2014 compile it.** `compile_file` returns the\n structured model: each source with its fields, joins, views, and named queries,\n plus `problems[]`. That is how you describe what is in the model. (Compiling a\n bare source \u2014 no `extend` block \u2014 likewise reads a raw table's schema.)\n\n## The loop\n\nEdit a file \u2192 `compile_file` \u2192 fix `problems[]` \u2192 `query`. Pass the model file's\npath as `ref`; `execute: false` validates first and reports the givens the query\nneeds (supplied via `givens`). Query text is restricted \u2014 `import`, `given:`\ndeclarations, `connection.table`/`connection.sql`, raw SQL, and `##!` flags\nbelong in the model file, not the query. When `compile`/`compile_file` returns\n`formatted: false`, run `prettify` and save its output. Use project-relative data\npaths, not absolute.\n",
2015
+ "language/who-is-asking.md": "---\ndescription: Per-user data with $MALLOYYO_EMAIL \u2014 the reserved given this server fills from the signed-in user, how to declare it, and how to run the model locally\n---\n\n# Who is asking \u2014 `$MALLOYYO_EMAIL`\n\nA model can scope what a query returns to the person running it. Declare the\nreserved given, then use it like any other:\n\n```malloy\n##! experimental.givens\ngiven:\n MALLOYYO_EMAIL :: string is ''\n\nsource: orders is duckdb.table('orders.parquet') extend {\n where: owner_email = $MALLOYYO_EMAIL\n}\n```\n\nEvery query against that model \u2014 the `query` tool, a dashboard tile, a saved\nquery, an ltool link \u2014 binds it to the signed-in user's address. Nothing else\nchanges: no per-user models, no filtered copies, no query rewriting.\n\n**The declaration is the opt-in.** A model that does not declare it is\nuntouched, because supplying a given a model never declared is an error in\nMalloy rather than a no-op.\n\n## What a caller cannot do\n\nA caller may not set it. A `givens: { \"MALLOYYO_EMAIL\": \"someone@else.com\" }`\non a `query` call, a dashboard's `?MALLOYYO_EMAIL=` URL, a value baked into a\ncomponent \u2014 all dropped before the query compiles, and the signed-in address\nbound instead. That is the whole point of the feature; do not design around it.\n\nFor the same reason it is not offered as a filter: `query(execute:false)` does\nnot list it among the givens to supply, and a dashboard renders no control for\nit.\n\n## The `MALLOYYO_` prefix is reserved\n\nTwo exist: `MALLOYYO_EMAIL` (the signed-in address) and `MALLOYYO_ROLES` (every\nrole that person holds, as a list \u2014 `where: department in $MALLOYYO_ROLES`).\nDeclaring any other `MALLOYYO_*` given is refused at publish: the prefix means\n\"a value this server vouches for\", and a `$MALLOYYO_ROLE` nothing fills would\nread as though it did. Name your own givens anything else.\n\n## The dataset decides whether it is supplied\n\nDeclaring the given is not enough. An admin ticks what a dataset is scoped by,\nand only then is the value supplied and locked. The two halves check each\nother:\n\n- tick it, and a model that does not declare it **cannot be published** \u2014 the\n data would be served unscoped;\n- declare it without the tick, and nothing supplies it, so your filter runs on\n the declaration default. `publish` says so in that case; do not ignore the\n line.\n\nThat is why the default matters so much (see Notes below): an unsupplied\n`:: string is ''` matches nothing, which is the safe way to be misconfigured.\n\n## Running it locally\n\nLocally there is no one asking, so a tenant-scoped query would come back\nempty \u2014 which looks exactly like a broken dashboard. Set the address in the\nenvironment instead:\n\n```bash\nMALLOYYO_EMAIL=you@example.com malloyyo dashboard dev\n```\n\n`malloyyo lint` needs nothing: it compiles, it does not run. Anything that\nactually runs a query refuses without a value and names the variable, rather\nthan showing you an empty page to debug. Change the address to see another\ntenant's view.\n\nNothing about the identity is committed. On a server the value comes from\nwhoever is signed in; the environment is only the local stand-in, because a\nserver's environment is ONE value for every request and would hand every user\nthe same tenant.\n\n## Not `malloyyo dashboard bundle`\n\nA bundled site has no one asking, and cannot have: there is no server, the\nmodel source is inlined into the page, and DuckDB-WASM fetches the data in the\nreader's own browser. Nothing supplies the identity there \u2014 the bundler only\nintrospects, and no environment travels into a static page. So a tenant-scoped\ndashboard bundles to a page that shows nothing.\n\nDo not answer that by loosening the default. `MALLOYYO_EMAIL :: filter<string>\nis f'\u2026'` with anything permissive publishes every row to every visitor, and the\nraw data is one fetch away regardless. **A model that filters by who is asking\nbelongs on an instance, not in a static bundle.**\n\n## Notes\n\n- Give it a default and make sure the default is the SAFE answer. Watch the\n type: `:: string is ''` matches no rows, which is right, but\n `:: filter<string> is f''` is an EMPTY FILTER, which matches EVERY row. The\n server refuses to run a query when it cannot supply the value (an account\n with no address, say) rather than let a default like that through \u2014 but the\n default is still what a local `dashboard dev` run and any non-server path\n will use, so write one that shows nothing.\n- Filtering belongs in the source (`extend { where: \u2026 }`), not in each query \u2014\n that way it holds for every query anyone writes against it, including ones\n an agent composes later.\n- It is a string, not a verified claim about identity beyond sign-in: it is the\n address the signed-in account carries.\n",
2016
+ "repo/branches.md": "---\ndescription: Branch previews \u2014 a repo's unpublished changes, compiled and usable here as repo@label:dataset; the three ways to make one, and what they're good for\n---\n\n# Branch previews\n\nA **preview** is a model repo with unpublished changes in it, compiled by this\ninstance with its own connections and usable as if it were published:\nqueries, `describe_source`, dashboards. Nothing about it is published. Only\nadmins can make or see one. The workflow for authoring with previews is in\n`yo_help(\"authoring/start\")`; this page covers previews themselves.\n\n## The address\n\nEach dataset in a preview gets an address:\n\n <repo>@<label>:<dataset> e.g. malloyyo_test@claude/returns:returns\n\nThe label is usually the branch name. Pass the address anywhere a dataset goes:\n\n- as `model_ref` to `describe_source` and `query`\n- as `dataset` to `show_dashboard`\n- in a browser, as `/datasets/<address, URL-encoded>/dashboard/<name>`. Every\n tool that makes a preview returns these links, so give them to the person.\n\nThe page shows a banner naming the preview and its commit. Queries against a\npreview make no share links.\n\n## Making one\n\n| From | Use | When |\n| --- | --- | --- |\n| Your clone (Claude Code on the web) | `preview_changes(repo, label, base, files, deleted)` | While authoring. Sends only your edits, committed or not; no push needed. |\n| A branch on GitHub | `fetch_branch(repo, branch)`, or **Fetch from GitHub** on the repo's page | To look at a branch someone else pushed. |\n| A local checkout with the CLI | `malloyyo publish --repo <owner/name> --branch` | Developing on your own machine. |\n\nEach answers with every dataset's compile result, `ok` or the error, plus its\naddress and dashboard links. A dataset that doesn't exist on this instance yet\ngets a preview like any other, which is how a new dataset is tried before it's\ncreated.\n\n## A snapshot, not a live view\n\nA preview shows what was sent or fetched. Making another preview with the same\nlabel replaces what that label's addresses show; older ones stay reachable by\ncommit SHA (`repo@<sha>:dataset`). So preview again after each round of edits,\nor fetch again after each push you want to see. `list_repos` lists each repo's\nlatest previews.\n\n## Then\n\nA preview never becomes the published version. The published version always\ncomes from the repo's published branch. To ship:\n\n1. Push the branch and open a pull request.\n2. `check_repo(repo, pull_request: <n>)` checks what merging would produce.\n3. The person merges.\n4. `publish_repo(repo)`, or the repo's GitHub hook, publishes.\n",
2017
+ "repo/convert-single-dataset.md": "---\ndescription: Move an old single-dataset repo (index.malloy at the root) to the datasets/ layout\n---\n\n# Convert a single-dataset repo\n\nThe old layout put `index.malloy` at the repo root. To move it under `datasets/`:\n\n1. **Pick the dataset's name.** It becomes the directory name and the published\n name, so use what the dataset is already called on the instance \u2014 renaming it\n here would publish a second dataset rather than update the first.\n\n2. **Move everything the model owns**, keeping `malloy-config.json` at the root:\n\n mkdir -p datasets/<name>\n git mv index.malloy *.malloy dashboards datasets/<name>/\n\n Leave at the root: `malloy-config.json`, `.mcp.json`, `.devcontainer/`,\n `.claude/`, `README.md`, and anything that is not the model.\n\n3. **Fix imports that reached outside the model.** Imports between files that\n moved together still resolve \u2014 they kept their relative positions. Only a path\n that pointed at something left behind needs editing, and it needs `../../`\n in front of it.\n\n4. **Verify before publishing:**\n\n malloyyo lint\n\n Lint reads the repo the same way the server does, so a clean lint here means\n the server will accept it. It names the file and line for anything that moved\n wrong.\n\n5. **Publish the repo**, not the dataset:\n\n malloyyo publish --repo <owner/name>\n\n The dataset already exists on the instance, so no `--create-datasets`. The\n name matching is what connects the moved directory to the dataset that was\n already there \u2014 which is why step 1 matters.\n\n### If the dataset is backed by GitHub rather than pushed\n\nAn instance that pulls from the repo needs to learn the dataset moved. The repo's\nlayout is re-read on every refresh, so pushing the converted repo and refreshing\nis enough \u2014 but the dataset's recorded directory is set when it is created. If\nthe refresh reports the dataset as **unpublished** (the repo no longer has its\nold directory) and the new directory as **unclaimed**, an admin updates the\ndataset's directory on the instance, or re-adds the repo.\n\nNothing is deleted either way: a dataset whose directory disappears keeps\nserving its last model until someone decides otherwise.\n\n---\n\n*This topic is transitional. It exists while repos built on the old\nsingle-dataset layout are still in the wild, and goes away with them \u2014 along with\nthe notice `lint` and `publish` print when they meet one.*\n",
2018
+ "repo/datasets.md": '---\ndescription: A model repo holds datasets under datasets/ \u2014 add one, or convert a single-dataset repo to the new layout\n---\n\n# Datasets in a model repo\n\nA model repo publishes **datasets**. Each one is a directory under `datasets/`,\nnamed after the directory:\n\n```\nmalloy-config.json connections \u2014 shared by every dataset\ndatasets/\n finance/\n index.malloy what THIS dataset publishes\n orders.malloy the model behind it\n dashboards/\n spend.malloy\n sales/\n malloy-config.json \u2026unless a dataset brings its own\n index.malloy\n dashboards/\nlib/ shared code, imported by relative path\n```\n\n`malloyyo init` scaffolds the repo and nothing else \u2014 no datasets. You add them.\n\n## The rules worth knowing before you start\n\n- **The directory names the dataset.** `datasets/finance/` publishes `finance`.\n The name is a slug \u2014 it is the URL, what a publish matches on, and what a role\n is granted against \u2014 so a directory that is not already one is converted:\n `datasets/the-look/` publishes `the_look`. `malloyyo lint` prints the name it\n will publish as, next to the directory.\n- **A dataset can say what to CALL it and what it IS**, at model scope in its\n `index.malloy`:\n\n ##" Deals, contacts and companies, as the sales team sees them.\n ## dataset { title="HubSpot CRM" }\n\n Note `##"` \u2014 two hashes. A `#"` attaches to whatever declaration follows it,\n so `#"` above the first source documents that SOURCE and leaves the dataset\n with no description. The description shows where someone is deciding whether\n they want this dataset, or who should see it \u2014 and in `list_sources`, so keep\n it to a sentence or two (`yo_help("develop/documenting-models")`).\n\n With no tag the title is derived from the name \u2014 `hub_spot` \u2192 "Hub Spot" \u2014\n so a dataset that says nothing still reads properly. Use the tag when the\n mechanical version is wrong: an acronym, a product\'s own capitalisation.\n The title is presentation ONLY. It is not unique, nothing is looked up by it,\n and changing it renames nothing.\n- **A dataset publishes exactly what its own `index.malloy` exports.** A source\n next door is not hidden from it, it is absent.\n- **`malloy-config.json` can be at the repo root or in a dataset.** At the root\n it is shared by every dataset. In a dataset it is that dataset\'s own \u2014 and it\n REPLACES the root\'s rather than adding to it, so a dataset that brings its own\n cannot reach a connection only the root declares. Nearest one wins.\n- **The repo publishes as a unit.** Every dataset is linted, and the server\n writes all of them or none.\n- **Never have both layouts.** A root `index.malloy` AND a `datasets/` directory\n is refused. A repo with a root `index.malloy` is the old single-dataset shape:\n `yo_help("repo/convert-single-dataset")`.\n\n## Add a dataset\n\n1. Make the directory and its dashboards folder:\n\n mkdir -p datasets/<name>/dashboards\n\n2. Write the model. Build it the way you build any model \u2014 compile a probe to\n read a schema, then write sources into files. `yo_help("develop/getting-started")`\n is the full procedure. Compile with paths relative to the REPO root:\n\n compile_file("datasets/<name>/orders.malloy")\n\n3. Write `datasets/<name>/index.malloy`, exporting what the dataset publishes:\n\n import { orders, PERIOD } from \'orders.malloy\'\n export { orders, PERIOD }\n\n Imports inside a dataset are relative to that dataset\'s directory, so\n `\'orders.malloy\'` is its sibling. Shared code one level up is\n `\'../../lib/orders.malloy\'`.\n\n4. Check the repo still publishes cleanly:\n\n malloyyo lint\n\n5. Publish:\n\n malloyyo publish --repo <owner/name> --create-datasets\n\n `--create-datasets` is only needed the first time a dataset appears.\n\n## Splitting one dataset into several\n\nOnly worth doing when the datasets really are separate \u2014 different people should\nsee different things, or one of them is scoped by who is asking and the others\nare not. A dataset is the unit of access: everything it publishes, a holder of\nits role gets.\n\nMove the sources for each into its own `datasets/<name>/`, put anything both need\nin `lib/`, and import it with `\'../../lib/<file>.malloy\'`.\n\n**Watch the givens.** A plain `import "../../lib/x.malloy"` brings that file\'s\n`given:` declarations with it, so a shared library that declares `MALLOYYO_EMAIL`\nmakes every dataset importing it scoped by the asker. Import selectively \u2014\n`import { orders } from \'../../lib/x.malloy\'` \u2014 when that is not what you want.\n\n## Trying a change before it\'s published\n\nWork on a branch and preview it here: `yo_help("repo/branches")`.\n',
2019
+ "site/auto-update.md": '# Auto-update a data site weekly\n\nAdd a scheduled GitHub Actions job that rebuilds the data and commits it, so the\npublished Pages site stays current on its own. Use this **after** the site works\n(built with `yo_help("site/data-site")`). If the data never changes, skip this.\n\nThe worked example is `malloydata/malloyyo-imdb` \u2014 fetch and read its\n`scripts/build_data.sh` and `.github/workflows/refresh-data.yml`; adapt, don\'t\ncopy blindly.\n\n## Precondition: one command that rebuilds the data\n\nThe whole thing rests on a single script that turns the source URL(s) into the\ncommitted parquet \u2014 the same script you\'d run by hand. Keep it linear so it\nreads as a recipe:\n\n```bash\n# scripts/build_data.sh\nset -euo pipefail\ncd "$(dirname "$0")/.."\nbash data/get.sh # 1. download source URLs -> data/\nrm -f data/build.duckdb\nmalloy-cli -c malloy-build.json build transform.malloy # 2. transform\necho "ATTACH \'data/build.duckdb\' AS b (READ_ONLY); -- 3. export -> docs/*.parquet\n COPY b.thing TO \'docs/thing.parquet\' (FORMAT parquet)" | malloyyo sql\n```\n\n(If you used Path A \u2014 direct \u2014 the whole script is just the one\n`echo "COPY (FROM read_..(\'https://\u2026\')) TO \'docs/\u2026\'" | malloyyo sql` command.\nNo `data/get.sh`, `malloy-build.json`, `malloy-cli`, or transform needed \u2014 and\nno standalone `duckdb` either, since `malloyyo sql` uses the embedded one.)\n\nGitignore the working files: `data/*.gz`, `data/*.duckdb`, `MANIFESTS/`.\n\n## The workflow\n\n`.github/workflows/refresh-data.yml`:\n\n```yaml\nname: refresh-data\non:\n schedule:\n - cron: "0 6 * * 0" # weekly, Sunday 06:00 UTC\n workflow_dispatch: # ...and on demand from the Actions tab\njobs:\n refresh:\n runs-on: ubuntu-latest\n permissions:\n contents: write # so the job can commit + push\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-node@v4\n with: { node-version: "20" }\n # malloyyo carries its own DuckDB (`malloyyo sql`), so no duckdb CLI to install.\n # Add `@malloydata/cli` only for a `#@ persist` transform (malloy-cli build).\n - run: npm install -g @malloydata/malloyyo @malloydata/cli\n - uses: actions/setup-python@v5 # only if an enrichment step needs it\n with: { python-version: "3.12" }\n - name: Build data\n run: bash scripts/build_data.sh\n - name: Commit refreshed data\n run: |\n git config user.name github-actions\n git config user.email github-actions@github.com\n git add docs/*.parquet\n git commit -m "refresh data $(date -u +%F)" || exit 0 # unchanged = clean no-op\n git push\n```\n\n## Hard-won details (these came from a real first run)\n\n- **`git commit \u2026 || exit 0`** \u2014 an unchanged week means nothing new upstream.\n That is success, not a failed job.\n- **Secondary/enrichment steps must be best-effort.** If the build has a step\n that can fail independently (an external API lookup, an optional metadata\n enrichment) and it isn\'t essential to the data, mark it\n `continue-on-error: true`. Otherwise one flaky API call throws away an\n otherwise-good data refresh \u2014 the commit step never runs and the fresh parquet\n is lost. (In `malloyyo-imdb` this bit us: a poster-image lookup with a missing\n secret failed the whole job until it was made non-blocking.)\n- **Secrets** go in repo settings (Settings \u2192 Secrets and variables \u2192 Actions,\n or `gh secret set NAME`), referenced as `${{ secrets.NAME }}`. A step reading\n a secret that isn\'t set gets an empty string \u2014 pair that with best-effort.\n- **No re-bundle needed for data changes.** The dashboards fetch parquet at\n runtime, so committing fresh parquet updates the live site. Only install\n `@malloydata/malloyyo` and run `malloyyo dashboard bundle` in CI if the job\n also needs to regenerate the HTML (i.e. dashboard code changed \u2014 rare for a\n data refresh).\n- **Test before trusting the schedule.** Push, then Actions tab \u2192 the workflow \u2192\n **Run workflow** (that\'s `workflow_dispatch`). Or `gh workflow run\n refresh-data.yml`, then `gh run watch <id> --exit-status`.\n\n## Git growth, and the flatten\n\nEach committed refresh adds the full parquet to history (~its file size per\nrun). That is intentional simplicity, not a leak. When history gets too big,\nflatten it to a single commit by hand \u2014 **not** as part of the weekly job:\n\n```bash\ngit checkout --orphan flat && git add -A && git commit -m "flatten history"\ngit branch -M flat main && git push -f origin main\n```\n\nOnly do this on a repo you solely own (it force-pushes; other clones must\n`git reset --hard origin/main`). Run it as often or as rarely as you like.\nDocument this in the repo\'s README so future-you remembers it\'s available.\n\n## Done when\n\n- The workflow file is on the default branch (so `workflow_dispatch` shows up)\n- A manual run goes green end-to-end and commits fresh `docs/*.parquet`\n- The Pages site shows the new data\n',
2020
+ "site/data-site.md": '# Build a public data site from a web data pointer\n\nGoal: given one or more **public data URLs**, produce a **GitHub Pages site** of\ninteractive Malloy dashboards that anyone can open in a browser. The data ends\nup as parquet in `docs/`; the dashboards are static HTML that query it\nclient-side with DuckDB-WASM \u2014 so there is no server, no database to run.\n\nTwo reference repos \u2014 read them, they are the ground truth for structure:\n\n- **`malloydata/malloyyo-babynames`** \u2014 the clean base pattern (one model file,\n a few dashboards, `docs/`). Data is static.\n- **`malloydata/malloyyo-imdb`** \u2014 the same, plus a `transform.malloy` that\n cleans raw source files into parquet, plus a **weekly auto-refresh** (that\n part is `yo_help("site/auto-update")`).\n\nFetch either with `gh api repos/<repo>/git/trees/HEAD?recursive=1` and read the\nfiles you need. Match their layout rather than inventing your own.\n\n## The shape of a finished repo\n\n```\nmalloy-config.json connection(s): duckdb (local), optionally md/gs mirrors\nindex.malloy the EXPORT SURFACE \u2014 only what this file exports is live\n<model>.malloy sources, measures, joins, givens (parameters)\nstorage.malloy sources point at the parquet \u2014 docs-local OR an https URL\n (or gs.malloy / md.malloy) same source names, swappable hosting (step 3)\ndashboards/*.malloy the query behind each dashboard\ndashboards/*.jsx the dashboard layout (grid of charts/tables)\ndocs/ PUBLISHED SITE \u2014 bundled HTML (+ the *.parquet if docs-local)\n *.parquet the data, when hosted docs-local (committed; served by Pages)\n *.html .nojekyll written by `malloyyo dashboard bundle`\n.mcp.json written by `malloyyo init` (author-mode Claude)\n```\n\n## Prerequisites (install once)\n\n```bash\nnpm install -g @malloydata/malloyyo # the `malloyyo` command\n```\n\nThat\'s the whole toolchain for the common case. `malloyyo` has **DuckDB built\nin** \u2014 `malloyyo sql` runs SQL (read a URL, `COPY` to parquet) through it, so you\ndo **not** need a standalone `duckdb` CLI.\n\nAdd `@malloydata/cli` (`malloy-cli`) **only** if you do a heavier transform with\nMalloy `#@ persist` (see Path B in `yo_help("site/data-to-parquet")`):\n\n```bash\nnpm install -g @malloydata/cli # only for #@ persist transforms\n```\n\n## Recipe\n\nWork top to bottom. After each step, prove it before moving on.\n\n### 1. Scaffold\n\n```bash\nmkdir my-site && cd my-site && git init\nmalloyyo init # writes .mcp.json (author-mode Claude) + index.malloy stub\n```\n\nCreate `malloy-config.json` with a local DuckDB connection (this is what reads\nthe parquet):\n\n```json\n{ "connections": { "duckdb": { "is": "duckdb" } } }\n```\n\n### 2. Get the web data into `docs/*.parquet`\n\nThis is the one dataset-specific step. Two paths \u2014 pick the simpler one that\nworks. Full detail and copy-paste commands: **`yo_help("site/data-to-parquet")`**.\n\n- **Direct** (default): `malloyyo sql` reads the URL and writes parquet in one\n shot, through the embedded DuckDB:\n ```bash\n echo "COPY (FROM read_csv_auto(\'https://\u2026/thing.csv\')) TO \'docs/thing.parquet\'" | malloyyo sql\n ```\n Use when the web data is already close to what you want to show.\n- **Transform** (when you need to clean / join / rank / reshape): write a\n `transform.malloy` with `#@ persist` sources and build it with `malloy-cli`,\n then export the tables to `docs/*.parquet`. This is the `malloyyo-imdb`\n pattern.\n\nVerify: `malloyyo sql -e "DESCRIBE SELECT * FROM \'docs/thing.parquet\'"` and a\n`SELECT count(*)`.\n\n### 3. Write the model\n\nA storage file \u2014 one source per parquet file \u2014 that the rest of the model builds\non. **Where the parquet lives is a choice** (the two examples differ here):\n\n- **docs-local** (the `malloyyo-imdb` way) \u2014 parquet committed in `docs/`,\n served same-origin by Pages. Self-contained; git carries the data. Address it\n by project-relative path so the same spelling works locally and published:\n ```malloy\n // storage.malloy\n source: thing_table is duckdb.table(\'docs/thing.parquet\') extend {}\n ```\n- **External URL** (the `malloyyo-babynames` way \u2014 it uses `import "gs.malloy"`)\n \u2014 parquet hosted on GCS / a CDN / any https URL; `docs/` holds only the HTML,\n so git stays small. DuckDB-WASM fetches the URL at runtime:\n ```malloy\n // gs.malloy\n source: thing_table is duckdb.table(\'https://storage.googleapis.com/\u2026/thing.parquet\') extend {}\n ```\n\nKeep the **source names identical** across storage files (as babynames does with\n`gs.malloy` / `md.malloy`) so switching hosting is a one-line import change in\nthe model. Start docs-local (simplest); move to a URL if git growth bites.\n\n`<model>.malloy` \u2014 build real sources on top: primary keys, measures, joins,\nand **givens** (the parameters that become the dashboard\'s filter controls).\n`index.malloy` \u2014 re-export exactly the sources/queries/givens the dashboards\nuse. **Only what `index.malloy` exports is visible** to dashboards, `dashboard\ndev`, and the hosted app.\n\nGive each exported source a `#"` doc string: one sentence on which questions it\nanswers. It\'s what `list_sources` shows the hosted app and any MCP client, for\nevery source, on every question \u2014 so keep it short, and put how to query the\nsource (grain, the measure to prefer, a subtle meaning) in `#(agent)` lines,\nwhich `describe_source` shows. Sizes and examples:\n`yo_help("develop/documenting-models")`.\n\nFor Malloy modeling and givens specifics, lean on the author MCP rather than\nguessing: the repo\'s `.mcp.json` wires `mcp__malloyyo_author__*`. Call\n`mcp__malloyyo_author__compile` to check files and\n`mcp__malloyyo_author__yo_help` for topics (`develop/working-with-models`).\n\nThree shapes that compile, pass `lint`, and still produce a dashboard that looks\nright and isn\'t:\n\n- **A stage-level `where:` zeroes measures that carry their own filters.**\n `count() { where: status = \'Sold\' }` needs the sold rows to reach it; a\n `where: in_cellar` on the stage removes them first and the measure reads 0\n everywhere. Constrain the output with `having:` instead.\n- **Grouping finer than the fact scatters the counts.** Group by an attribute\n that only applies to some rows and the measures over the others split across\n groups and read near-zero. Pick the grain the question is asked at; if you\n need both, group at the coarser one and `nest:` the finer.\n- **Detail tables default to raw field names and bare numbers.** `exit_date` and\n `829.57`, and a null renders as `\u2205`. Tag them \u2014 `# label="Opened"`,\n `# label="Paid" currency` \u2014 and `coalesce(field, \'\')` where empty is\n meaningful rather than missing.\n\nAggregate locality is NOT one of these: Malloy\'s symmetric aggregates keep\nmeasures honest through a `join_many` fan-out, and it warns (or errors) rather\nthan silently answering when an `avg`/`sum` crosses a join without explicit\nlocality. `notes.rating.avg()` already averages at the notes grain; ask for\n`source.avg(notes.rating)` only when you want the fan-out-weighted number. See\n`yo_help language/aggregate-locality-symmetric-aggregates`.\n\n### 4. Author dashboards and preview live\n\nEach dashboard is **one self-contained `dashboards/<name>.malloy`** \u2014 the query,\nits filtering, and the tags that lay it out. The filename is the dashboard\'s\nname and URL slug.\n\n**A `.jsx` is OPTIONAL and most dashboards don\'t need one.** The default form \u2014\nan inline query tagged `# artifact` + `# dashboard { columns=6 }` \u2014 renders KPI\ntiles and a card grid with no React at all. Reach for a sibling\n`dashboards/<name>.jsx` only when you want bespoke layout or presentation the\ntags can\'t express (a hand-built card, a picker, a Vega chart).\n\nAuthor with the `malloyyo_author` MCP and its `yo_help` topics \u2014 **read these,\ndon\'t guess the API**: `dashboards/authoring` (the dashboard file),\n`dashboards/grid-layout` (colspans), `dashboards/charts` (chart tags and their\nchannel rules), `dashboards/givens-and-controls` (filters),\n`dashboards/custom-components` and `dashboards/vega-charts` (only if you add a\n`.jsx`).\n\nPreview in a browser with live reload:\n\n```bash\nmalloyyo dashboard dev # serves at http://localhost:4173\n```\n\nTwo things about `dashboard dev` worth knowing:\n\n- It runs the queries **server-side**, through the same local DuckDB the CLI\n uses \u2014 the browser only renders results. So it works without DuckDB-WASM or\n its CDN extensions, and it is the only way to see a custom component render\n against real data short of publishing.\n- It holds **one long-lived connection set with a warm schema cache** (a\n deliberate tradeoff \u2014 refetching schemas per compile reads like a hang on a\n warehouse). The file watcher hot-reloads your `.malloy` edits and re-discovers\n `# artifact` tags, but nothing invalidates that cache, so a change to the\n DATA\'s shape \u2014 a new column in a parquet \u2014 needs a restart. The tell is\n `\'<column>\' is not defined` in the browser while the CLI and `lint` are green.\n\nIterate here until the dashboards look right. **Look at every dashboard before\nyou call it done**: `malloyyo lint` compiles the dashboards against the model but\ndoes not render them, so it cannot see a chart that throws at render time, a\ncomponent whose CSS resolved to nothing, or a column of raw field names.\n`malloyyo test` previews what the hosted claude.ai app would see.\n\n### 5. Build the static site\n\n```bash\nmalloyyo dashboard bundle --out docs\n# optional: add analytics + a title\nmalloyyo dashboard bundle --out docs --title "My Site" --analytics G-XXXXXXXXXX\n```\n\n`bundle` writes the HTML, `.nojekyll`, and assets into `docs/`, next to the\nparquet from step 2. The pages fetch `./*.parquet` relative to the site root, so\nthe data must already be in `docs/` \u2014 always run the data step before bundling.\n\n### 6. Publish on GitHub Pages\n\nCommit `docs/` and turn on Pages (Settings \u2192 Pages \u2192 Deploy from a branch \u2192\n`main` / `docs`). Full steps + gotchas: **`yo_help("site/github-pages")`**.\n\n### 7. (Optional) Keep it fresh automatically\n\nIf the data comes from a URL that updates over time and you want the site to\ntrack it, add a weekly GitHub Actions refresh \u2014 see\n**`yo_help("site/auto-update")`** (worked example: `malloydata/malloyyo-imdb`).\n\n## Done when\n\n- `malloyyo sql -e "SELECT count(*) FROM \'docs/<file>.parquet\'"` returns real rows\n- `malloyyo lint` passes\n- **you have LOOKED at every dashboard** in `malloyyo dashboard dev` \u2014 each one\n renders with no console errors, every tile has data, and the labels read like\n English rather than column names. `lint` passing is not this; a dashboard can\n compile and still throw at render time.\n- `docs/` has the bundled `*.html` + `.nojekyll` alongside the parquet\n- the Pages URL loads and the dashboards populate (data fetch succeeds)\n',
2021
+ "site/data-to-parquet.md": '# Getting web data into `docs/*.parquet`\n\nThe site queries parquet files (in `docs/`, or at an https URL \u2014 see the model\nstep). This is how you turn a public data URL into that parquet. Pick the\nsimplest path that produces clean data.\n\n`malloyyo sql` runs SQL through malloyyo\'s **embedded DuckDB** \u2014 no standalone\n`duckdb` binary. It takes SQL from `-e`, `-f <file>`, or stdin, and runs against\na connection from `malloy-config.json` (default `duckdb`).\n\n## Path A \u2014 Direct (default)\n\nOne command reads the URL and writes parquet. Best when the web data is already\nclose to what you want to display.\n\n```bash\n# CSV / TSV\necho "COPY (SELECT * FROM read_csv_auto(\'https://example.com/data.csv\'))\n TO \'docs/data.parquet\' (FORMAT parquet)" | malloyyo sql\n\n# TSV, gzipped, tab-delimited, header row (IMDb-style)\necho "COPY (SELECT * FROM read_csv_auto(\'https://example.com/data.tsv.gz\',\n delim=\'\\t\', header=true, all_varchar=true))\n TO \'docs/data.parquet\' (FORMAT parquet)" | malloyyo sql\n\n# JSON / NDJSON\necho "COPY (SELECT * FROM read_json_auto(\'https://example.com/data.json\'))\n TO \'docs/data.parquet\' (FORMAT parquet)" | malloyyo sql\n\n# Already parquet on the web \u2014 just fetch it\ncurl -fsSL -o docs/data.parquet \'https://example.com/data.parquet\'\n```\n\nFor anything longer than a line or two, put the SQL in a file and run it with\n`-f`, so it\'s re-runnable and diffable:\n\n```bash\nmalloyyo sql -f scripts/build.sql # a file of ;-separated statements\n```\n\nNotes:\n- DuckDB autoloads `httpfs` for `https://` reads.\n- Keep only the columns/rows the dashboards need \u2014 `SELECT` the columns and add a\n `WHERE` to drop noise. Smaller parquet = faster page loads.\n- Cast types here if the source is all-strings: `col::INT`, `col::DOUBLE`, etc.\n\n## Path B \u2014 Transform with Malloy (when you need to reshape)\n\nUse when the data needs cleaning, joining across files, ranking, or nesting \u2014\nthe `malloydata/malloyyo-imdb` case. You write the transform once in Malloy;\n`malloy-cli build` materializes it; you export the tables to parquet. This path\nalso needs `@malloydata/cli` (`npm install -g @malloydata/cli`).\n\n**1. A build connection** \u2014 `malloy-build.json` (a DuckDB db just for building):\n\n```json\n{ "connections": { "build": { "is": "duckdb", "databasePath": "data/build.duckdb" } } }\n```\n\n**2. `transform.malloy`** \u2014 read the raw source(s) through the `build`\nconnection and mark each output source with `#@ persist name="\u2026"`:\n\n```malloy\n##! experimental.persistence experimental.virtual_source\n\nsource: raw is build.sql("""\n SELECT * FROM read_csv_auto(\'data/raw.csv.gz\', delim=\'\\t\', all_varchar=true, header=true)\n""")\n\n#@ persist name="thing"\nsource: thing_base is raw -> {\n where: some_count::number > 100\n select: id, name, value is value::number\n calculate: rank is rank() { order_by: value::number desc }\n}\n```\n\nDownload the raw files first (a `data/get.sh` that `wget`s the URLs into `data/`,\ngitignored). Gitignore `data/`, `data/*.duckdb`, and `MANIFESTS/`.\n\n**3. Build, then export the persisted tables to `docs/`** \u2014 the export still\ngoes through `malloyyo sql` (no standalone duckdb needed):\n\n```bash\nrm -f data/build.duckdb\nmalloy-cli -c malloy-build.json build transform.malloy # -> tables in build.duckdb\necho "ATTACH \'data/build.duckdb\' AS b (READ_ONLY);\n COPY b.thing TO \'docs/thing.parquet\' (FORMAT parquet)" | malloyyo sql\n```\n\nThe persist `name=` is the table name inside `build.duckdb`; the `COPY` names the\nserved file (they can differ \u2014 e.g. `thing` \u2192 `docs/mysite_thing.parquet`).\n\nWrap steps 1\u20133 in a single `scripts/build_data.sh` so it is one command, by hand\nand in CI. That\'s exactly what `yo_help("site/auto-update")` automates weekly.\n\n## Either way, verify\n\n```bash\nmalloyyo sql -e "DESCRIBE SELECT * FROM \'docs/thing.parquet\'"\nmalloyyo sql -e "SELECT count(*) FROM \'docs/thing.parquet\'"\n```\n\nThen point a storage source at it (docs-local shown; an https URL works too \u2014\nsee the model step in SKILL.md):\n\n```malloy\nsource: thing_table is duckdb.table(\'docs/thing.parquet\') extend {}\n```\n',
2022
+ "site/github-pages.md": '# Publishing the site on GitHub Pages\n\nThe published site is just the `docs/` directory: bundled HTML plus the parquet\nit queries. GitHub Pages serves it directly \u2014 no build step on GitHub\'s side.\n\n## One-time setup\n\n```bash\n# from the repo root, after `malloyyo dashboard bundle --out docs`\ngh repo create <owner>/<name> --public --source=. --remote=origin # or an existing repo\ngit add -A\ngit commit -m "initial data site"\ngit push -u origin main\n```\n\nTurn on Pages, pointing at the `docs/` folder on the default branch:\n\n```bash\ngh api -X POST repos/<owner>/<name>/pages \\\n -f \'source[branch]=main\' -f \'source[path]=/docs\'\n```\n\n(Or in the UI: Settings \u2192 Pages \u2192 Source: **Deploy from a branch** \u2192 Branch\n`main`, folder `/docs`.)\n\nThe site appears at `https://<owner>.github.io/<name>/` within a minute or two.\n\n## Why `docs/` and why `.nojekyll`\n\n- Serving from `/docs` on the main branch keeps the data committed **once**\n (it\'s the same directory you build into), not duplicated on a separate branch.\n- `malloyyo dashboard bundle` writes a `.nojekyll` file so Pages serves the\n bundled assets as-is instead of running them through Jekyll (which would drop\n files beginning with `_`). Keep it committed.\n\n## Updating the site\n\nRe-run the data step and the bundle, then commit `docs/`:\n\n```bash\nbash scripts/build_data.sh # or your Path-A duckdb command \u2192 docs/*.parquet\nmalloyyo dashboard bundle --out docs\ngit add docs && git commit -m "update" && git push\n```\n\nBecause the dashboards fetch the parquet client-side, **committing fresh parquet\nis enough to update the live data** \u2014 you only need to re-`bundle` when you\nchange dashboard code. To automate the data refresh weekly, see the\n`yo_help("site/auto-update")`.\n\n## Gotchas\n\n- **Data must be in `docs/` before you bundle** \u2014 the pages fetch `./*.parquet`\n relative to the site root; `bundle` also reads the parquet to get schemas.\n- **Big parquet grows git history.** Each committed refresh adds the full file.\n Fine for occasional updates; for frequent auto-refresh, see the flatten note\n in `yo_help("site/auto-update")`.\n- **Git LFS does not work with Pages "deploy from a branch"** \u2014 Pages serves the\n LFS pointer text, not the file. Commit parquet as normal git objects.\n- **Private repos**: Pages on private repos needs a paid plan. Use a public repo\n for a public site.\n'
2023
+ };
2024
+ addHelpContent(productContentFiles);
2025
+ function titleFromName(name) {
2026
+ return name.split(/[_-]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
2091
2027
  }
2092
- function definedNamesIn(malloy) {
2093
- const names = /* @__PURE__ */ new Set();
2094
- const re = /\b([A-Za-z_]\w*)\s+is\b/g;
2095
- let m;
2096
- while ((m = re.exec(malloy)) !== null) names.add(m[1]);
2097
- return names;
2028
+ function datasetTitle(name, declared) {
2029
+ const t = declared?.trim();
2030
+ return t || titleFromName(name);
2098
2031
  }
2099
- function queryFieldFix(modelRef, source, malloy) {
2100
- const defined = definedNamesIn(malloy);
2101
- const nudge = srcNudge(modelRef, source);
2102
- return (p) => {
2103
- if (p.code !== "field-not-found") return p;
2104
- const name = /'([^']+)'/.exec(p.message)?.[1];
2105
- if (name && defined.has(name)) {
2106
- return {
2107
- ...p,
2108
- message: `'${name}' is defined in this query, but one field can't reference another in the same stage. To build a value from other aggregates (a ratio, a share), declare the parts in an \`extend:\` block (measures can reference each other), then use them.`,
2109
- help_topic: "explore/query-examples"
2110
- };
2032
+ function readDatasetMeta(model) {
2033
+ const m = model;
2034
+ let title;
2035
+ try {
2036
+ const tag = m.annotations.parseAsTag().tag;
2037
+ if (tag.has("dataset")) {
2038
+ title = tag.tag("dataset")?.text("title") ?? tag.text("title");
2111
2039
  }
2112
- return nudge(p);
2113
- };
2040
+ } catch {
2041
+ }
2042
+ let description;
2043
+ try {
2044
+ const docs = m.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
2045
+ if (docs.length) description = docs.join("\n");
2046
+ } catch {
2047
+ }
2048
+ return { ...title ? { title } : {}, ...description ? { description } : {} };
2114
2049
  }
2115
- function sourceAsMalloy(s) {
2116
- return s?.body ? `source: ${s.body}` : "";
2050
+ function nameToSlug(s) {
2051
+ return s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 48) || "dataset";
2117
2052
  }
2118
- function buildQueryExamples(ds) {
2119
- const ref = (name, mustQuote) => mustQuote ? `\`${name}\`` : name;
2120
- const out = [];
2121
- const view = Object.keys(ds.views)[0];
2122
- if (view) out.push(`run: ${ds.name} -> ${view}`);
2123
- const dims = Object.entries(ds.dimensions).filter(([, m]) => "type" in m);
2124
- const dim = dims.find(([, m]) => m.type === "string") ?? dims[0];
2125
- const measure = Object.entries(ds.measures)[0];
2126
- if (dim && measure) {
2127
- const [dName, dField] = dim;
2128
- const [mName, mField] = measure;
2129
- const m = ref(mName, mField.must_quote);
2130
- out.push(
2131
- `run: ${ds.name} -> {
2132
- group_by: ${ref(dName, dField.must_quote)}
2133
- aggregate: ${m}
2134
- order_by: ${m} desc
2135
- limit: 10
2136
- }`
2137
- );
2053
+ var DATASETS_DIR = "datasets";
2054
+ var ENTRY_FILE = "index.malloy";
2055
+ async function layoutFromListing(list, label = "this repo") {
2056
+ const root = await list("");
2057
+ if (root.length === 0) {
2058
+ return { ok: false, error: `${label} is empty or could not be read.` };
2138
2059
  }
2139
- return out;
2060
+ const hasRootEntry = root.some((e) => e.type === "file" && e.name === ENTRY_FILE);
2061
+ const hasDatasetsDir = root.some((e) => e.type === "dir" && e.name === DATASETS_DIR);
2062
+ if (hasRootEntry && hasDatasetsDir) {
2063
+ return {
2064
+ ok: false,
2065
+ error: `This repo has both a top-level ${ENTRY_FILE} and a ${DATASETS_DIR}/ directory, and those are two different layouts. Use one: keep ${ENTRY_FILE} at the root to publish a single dataset, or move it under ${DATASETS_DIR}/<name>/ and delete the root one to publish several.`
2066
+ };
2067
+ }
2068
+ if (hasRootEntry) return { ok: true, kind: "single" };
2069
+ if (!hasDatasetsDir) {
2070
+ return {
2071
+ ok: false,
2072
+ error: `No ${ENTRY_FILE} at the root of ${label}, and no ${DATASETS_DIR}/ directory either. A model repo needs one or the other.`
2073
+ };
2074
+ }
2075
+ const subdirs = (await list(DATASETS_DIR)).filter((e) => e.type === "dir");
2076
+ if (subdirs.length === 0) {
2077
+ return {
2078
+ ok: false,
2079
+ empty: true,
2080
+ error: `${DATASETS_DIR}/ has no subdirectories \u2014 each dataset is a directory under it.`
2081
+ };
2082
+ }
2083
+ const found = [];
2084
+ const missing = [];
2085
+ for (const d of subdirs) {
2086
+ const inside = await list(`${DATASETS_DIR}/${d.name}`);
2087
+ if (inside.some((e) => e.type === "file" && e.name === ENTRY_FILE)) {
2088
+ found.push({ name: nameToSlug(d.name), dir: `${DATASETS_DIR}/${d.name}` });
2089
+ } else {
2090
+ missing.push(`${DATASETS_DIR}/${d.name}`);
2091
+ }
2092
+ }
2093
+ if (missing.length > 0) {
2094
+ return {
2095
+ ok: false,
2096
+ error: `${missing.join(", ")}: every directory under ${DATASETS_DIR}/ is a dataset and needs its own ${ENTRY_FILE}. Add one, or move the directory out of ${DATASETS_DIR}/ if it is shared code (a sibling \`lib/\` is imported by relative path).`
2097
+ };
2098
+ }
2099
+ const byName = /* @__PURE__ */ new Map();
2100
+ for (const d of found) byName.set(d.name, [...byName.get(d.name) ?? [], d.dir]);
2101
+ const collided = [...byName.entries()].filter(([, dirs]) => dirs.length > 1);
2102
+ if (collided.length > 0) {
2103
+ return {
2104
+ ok: false,
2105
+ error: collided.map(([name, dirs]) => `${dirs.join(" and ")} both publish a dataset named "${name}"`).join("; ")
2106
+ };
2107
+ }
2108
+ return { ok: true, kind: "multi", datasets: found.sort((a, b) => a.name.localeCompare(b.name)) };
2140
2109
  }
2141
- function listSourcesTool(host) {
2142
- return {
2143
- name: "list_sources",
2144
- title: prompts.explore.tools.list_sources.title,
2145
- description: prompts.explore.tools.list_sources.description,
2146
- inputSchema: { type: "object", properties: {}, additionalProperties: false },
2147
- handler: async () => {
2148
- const { entries } = await host.list();
2149
- const models = /* @__PURE__ */ Object.create(null);
2150
- for (const e of entries) {
2151
- const m = {};
2152
- if (e.description) m.description = e.description;
2153
- if (e.sources?.length) {
2154
- const sources = /* @__PURE__ */ Object.create(null);
2155
- for (const s of e.sources) {
2156
- const o = {};
2157
- if (s.description) o.description = s.description;
2158
- if (s.must_quote) o.must_quote = true;
2159
- sources[s.source_ref] = o;
2160
- }
2161
- m.sources = sources;
2162
- }
2163
- if (e.dashboards?.length) {
2164
- const dashboards = /* @__PURE__ */ Object.create(null);
2165
- for (const d of e.dashboards) {
2166
- const o = {};
2167
- if (d.title) o.title = d.title;
2168
- if (d.description) o.description = d.description;
2169
- if (d.url) o.url = d.url;
2170
- dashboards[d.name] = o;
2171
- }
2172
- m.dashboards = dashboards;
2173
- }
2174
- models[e.model_ref] = m;
2110
+ var MAX_FILE = 4 * 1024 * 1024;
2111
+ var MAX_TOTAL = 64 * 1024 * 1024;
2112
+ function renderGivenType2(t) {
2113
+ if (t.type === "filter expression") {
2114
+ return t.filterType ? `filter<${t.filterType}>` : "filter";
2115
+ }
2116
+ if (t.type === "array") {
2117
+ const elem = t.elementTypeDef;
2118
+ if (!elem) return "array";
2119
+ if (elem.type === "record_element") return "record[]";
2120
+ return `${renderGivenType2(elem)}[]`;
2121
+ }
2122
+ return t.type;
2123
+ }
2124
+ function defaultValue(e) {
2125
+ if (!e) return void 0;
2126
+ switch (e.node) {
2127
+ case "filterLiteral":
2128
+ return e.filterSrc;
2129
+ case "stringLiteral":
2130
+ return e.literal;
2131
+ case "numberLiteral":
2132
+ return Number(e.literal);
2133
+ case "true":
2134
+ return true;
2135
+ case "false":
2136
+ return false;
2137
+ case "dateLiteral":
2138
+ case "timestampLiteral":
2139
+ case "timestamptzLiteral":
2140
+ return e.literal;
2141
+ default:
2142
+ return void 0;
2143
+ }
2144
+ }
2145
+ function describeGivenSpec(name, g) {
2146
+ const spec = { name, type: renderGivenType2(g.type) };
2147
+ if (g.type.type === "filter expression" && g.type.filterType) {
2148
+ spec.filterType = g.type.filterType;
2149
+ }
2150
+ const dflt = defaultValue(g.default);
2151
+ if (dflt !== void 0) spec.default = dflt;
2152
+ try {
2153
+ const docs = g.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
2154
+ if (docs.length) spec.description = docs.join("\n");
2155
+ } catch {
2156
+ }
2157
+ try {
2158
+ const dict = g.annotations.parseAsTag().tag.dict ?? {};
2159
+ const tags = {};
2160
+ for (const [key, t] of Object.entries(dict)) {
2161
+ const eq = t.eq;
2162
+ if (typeof eq === "string" || typeof eq === "number" || typeof eq === "boolean") {
2163
+ tags[key] = eq;
2164
+ } else if (eq === void 0 && !t.dict) {
2165
+ tags[key] = true;
2166
+ }
2167
+ }
2168
+ if (Object.keys(tags).length) spec.tags = tags;
2169
+ const suggestDict = dict.suggest?.dict;
2170
+ if (suggestDict) {
2171
+ const suggest = {};
2172
+ for (const key of ["source", "dimension", "query"]) {
2173
+ const eq = suggestDict[key]?.eq;
2174
+ if (typeof eq === "string") suggest[key] = eq;
2175
+ }
2176
+ if (suggest.source || suggest.query) spec.suggest = suggest;
2177
+ }
2178
+ } catch {
2179
+ }
2180
+ return spec;
2181
+ }
2182
+ async function dashboardGivenSpecs(runtime, entry, runExpr) {
2183
+ try {
2184
+ const mm = runtime.loadModel(entry);
2185
+ const pq = await mm.loadQuery(`run: ${runExpr}`).getPreparedQuery();
2186
+ const specs = [];
2187
+ for (const [name, g] of pq.givens) {
2188
+ specs.push(describeGivenSpec(name, g));
2189
+ }
2190
+ return { ok: true, givens: specs };
2191
+ } catch (e) {
2192
+ return { ok: false, error: e instanceof Error ? e.message : String(e) };
2193
+ }
2194
+ }
2195
+ function docText(t) {
2196
+ try {
2197
+ const docs = t.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
2198
+ return docs.length ? docs.join("\n") : void 0;
2199
+ } catch {
2200
+ return void 0;
2201
+ }
2202
+ }
2203
+ function resolveTile(tile, source) {
2204
+ const t = tile.trim();
2205
+ if (source && !t.includes("->")) return `${source} -> ${t}`;
2206
+ return t;
2207
+ }
2208
+ function readGivens(tag) {
2209
+ const givensTag = tag.tag("artifact", "givens");
2210
+ if (!givensTag) return void 0;
2211
+ const givens = {};
2212
+ for (const [key, t] of Object.entries(givensTag.dict ?? {})) {
2213
+ const eq = t.eq;
2214
+ if (typeof eq === "string" || typeof eq === "number" || typeof eq === "boolean") {
2215
+ givens[key] = eq;
2216
+ }
2217
+ }
2218
+ return Object.keys(givens).length ? givens : void 0;
2219
+ }
2220
+ function readArtifactTag(ident, q) {
2221
+ let tag;
2222
+ try {
2223
+ tag = q.annotations.parseAsTag().tag;
2224
+ } catch {
2225
+ return void 0;
2226
+ }
2227
+ if (!tag.has("artifact")) return void 0;
2228
+ const nested = tag.tag("artifact");
2229
+ const description = docText(q);
2230
+ const name = nested?.text("name") ?? tag.text("name") ?? ident.defaultName;
2231
+ const title = nested?.text("title") ?? tag.text("title") ?? description?.split("\n")[0] ?? ident.defaultName;
2232
+ const rawTiles = nested?.textArray("tiles") ?? tag.textArray("tiles");
2233
+ if (rawTiles && rawTiles.length) {
2234
+ const resolved = rawTiles.map((t) => resolveTile(t, ident.source));
2235
+ const cols = nested?.numeric("dashboard_columns") ?? tag.numeric("dashboard_columns");
2236
+ const autorunText2 = nested?.text("autorun") ?? tag.text("autorun");
2237
+ const givens2 = readGivens(tag);
2238
+ if (resolved.length === 1) {
2239
+ const info3 = { name, query: resolved[0], title };
2240
+ if (ident.source) info3.source = ident.source;
2241
+ if (description) info3.description = description;
2242
+ if (autorunText2 === "false") info3.autorun = false;
2243
+ if (givens2) info3.givens = givens2;
2244
+ if (typeof cols === "number")
2245
+ info3.warnings = [
2246
+ "dashboard_columns is ignored on a single-tile artifact (one tile renders like a single-query `# artifact`, laid out by the tile query\u2019s own `# dashboard` tag)"
2247
+ ];
2248
+ return info3;
2249
+ }
2250
+ const info2 = { name, query: "", title, tiles: resolved };
2251
+ if (ident.source) info2.source = ident.source;
2252
+ if (description) info2.description = description;
2253
+ if (typeof cols === "number") info2.dashboard_columns = cols;
2254
+ if (autorunText2 === "false") info2.autorun = false;
2255
+ if (givens2) info2.givens = givens2;
2256
+ return info2;
2257
+ }
2258
+ const info = { name, query: ident.runExpr, title };
2259
+ if (ident.source) info.source = ident.source;
2260
+ if (ident.view) info.view = ident.view;
2261
+ if (description) info.description = description;
2262
+ const autorunText = nested?.text("autorun") ?? tag.text("autorun");
2263
+ if (autorunText === "false") info.autorun = false;
2264
+ const givens = readGivens(tag);
2265
+ if (givens) info.givens = givens;
2266
+ return info;
2267
+ }
2268
+ async function artifactQueries(runtime, entry) {
2269
+ try {
2270
+ const model = await runtime.loadModel(entry).getModel();
2271
+ const artifacts = [];
2272
+ const modelComposite = readArtifactTag({ runExpr: "", defaultName: "dashboard" }, model);
2273
+ if (modelComposite && (modelComposite.tiles || modelComposite.query)) artifacts.push(modelComposite);
2274
+ for (const queryName of model.queries().named) {
2275
+ const pq = model.getPreparedQueryByName(queryName);
2276
+ const info = readArtifactTag({ runExpr: queryName, defaultName: queryName }, pq);
2277
+ if (info) artifacts.push(info);
2278
+ }
2279
+ for (const src of model.explores) {
2280
+ const srcComposite = readArtifactTag(
2281
+ { runExpr: "", defaultName: src.name, source: src.name },
2282
+ src
2283
+ );
2284
+ if (srcComposite && (srcComposite.tiles || srcComposite.query)) artifacts.push(srcComposite);
2285
+ for (const field of src.allFields) {
2286
+ if (!field.isQueryField()) continue;
2287
+ const view = field;
2288
+ const info = readArtifactTag(
2289
+ {
2290
+ runExpr: `${src.name} -> ${view.name}`,
2291
+ defaultName: view.name,
2292
+ source: src.name,
2293
+ view: view.name
2294
+ },
2295
+ view
2296
+ );
2297
+ if (info) artifacts.push(info);
2175
2298
  }
2176
- return { ok: true, guidance: prompts.explore.guidance, models };
2177
2299
  }
2178
- };
2300
+ return { ok: true, artifacts };
2301
+ } catch (e) {
2302
+ return { ok: false, error: e instanceof Error ? e.message : String(e) };
2303
+ }
2179
2304
  }
2180
- function describeSourceTool(host) {
2181
- return {
2182
- name: "describe_source",
2183
- title: prompts.explore.tools.describe_source.title,
2184
- description: prompts.explore.tools.describe_source.description,
2185
- inputSchema: {
2186
- type: "object",
2187
- properties: {
2188
- source: { type: "string", description: "The source to describe (a source the model publishes)." },
2189
- model_ref: {
2190
- type: "string",
2191
- description: "The model the source lives in (the model_ref from list_sources). Optional when the source name is unique across the catalog."
2305
+ async function collectDrillTargets(runtime, entry) {
2306
+ try {
2307
+ const model = await runtime.loadModel(entry).getModel();
2308
+ const targets = /* @__PURE__ */ new Set();
2309
+ for (const src of model.explores) {
2310
+ for (const field of src.allFields) {
2311
+ const tagged = field;
2312
+ let tag;
2313
+ try {
2314
+ tag = tagged.annotations.parseAsTag().tag;
2315
+ } catch {
2316
+ continue;
2192
2317
  }
2193
- },
2194
- required: ["source"],
2195
- additionalProperties: false
2196
- },
2197
- handler: async (args) => {
2198
- const source = argString(args, "source");
2199
- const modelRefArg = argOptString(args, "model_ref");
2200
- if (!source.trim()) {
2201
- return {
2202
- ok: false,
2203
- model_ref: modelRefArg ?? "",
2204
- source,
2205
- problems: [codeProblem("source-required", "A source name is required. Use list_sources to see them.")]
2206
- };
2207
- }
2208
- const r = await resolveModel(host, source, modelRefArg);
2209
- if ("problem" in r) {
2210
- return { ok: false, model_ref: modelRefArg ?? "", source, problems: [r.problem] };
2211
- }
2212
- const modelRef = r.model_ref;
2213
- try {
2214
- return await host.withModel(modelRef, async (m) => {
2215
- const ref = m.ref ?? modelRef;
2216
- const compiled = await compile(m.runtime, m.entry, { readSource: m.readSource });
2217
- if (!compiled.ok || !compiled.model) {
2218
- return { ok: false, model_ref: ref, source, problems: compiled.problems };
2219
- }
2220
- const built = buildSourceDescribe(compiled.model, source);
2221
- if (!built) {
2222
- const available = Object.keys(compiled.model.sources);
2223
- return {
2224
- ok: false,
2225
- model_ref: ref,
2226
- source,
2227
- problems: [
2228
- ...compiled.problems,
2229
- codeProblem(
2230
- "source-not-found",
2231
- `No source named '${source}' in '${ref}'. Sources: ${available.join(", ") || "(none)"}.`
2232
- )
2233
- ]
2234
- };
2235
- }
2236
- const malloy_text = sourceAsMalloy(compiled.model.sources[source]);
2237
- const base = {
2238
- ok: true,
2239
- model_ref: ref,
2240
- source,
2241
- guidance: prompts.explore.guidance,
2242
- described_source: built.described_source,
2243
- problems: compiled.problems
2244
- };
2245
- const examples = buildQueryExamples(built.described_source);
2246
- if (examples.length) base.examples = examples;
2247
- if (Object.keys(built.joins).length) base.joins = built.joins;
2248
- if (Object.keys(built.join_source_map).length) base.join_source_map = built.join_source_map;
2249
- return malloy_text ? { ...base, malloy_text } : base;
2250
- });
2251
- } catch (e) {
2252
- return { ok: false, model_ref: modelRef, source, problems: [refModelProblem(modelRef, e)] };
2318
+ const drill = tag.tag("drill");
2319
+ if (!drill) continue;
2320
+ const to = drill.textArray("to") ?? (drill.text("to") ? [drill.text("to")] : []);
2321
+ for (const t of to) if (t && t !== "self") targets.add(t);
2253
2322
  }
2254
2323
  }
2255
- };
2324
+ return { ok: true, targets: [...targets] };
2325
+ } catch (e) {
2326
+ return { ok: false, error: e instanceof Error ? e.message : String(e) };
2327
+ }
2256
2328
  }
2257
- function exploreQueryTool(host, opts) {
2258
- return {
2259
- name: "query",
2260
- title: prompts.shared.tools.query.title,
2261
- description: prompts.shared.tools.query.description,
2262
- inputSchema: {
2263
- type: "object",
2264
- properties: {
2265
- source: { type: "string", description: "The source the query runs against." },
2266
- malloy: { type: "string", description: "Malloy query text, e.g. `run: orders -> { ... }`." },
2267
- model_ref: {
2268
- type: "string",
2269
- description: "The model the source lives in (optional when the source name is unique)."
2270
- },
2271
- question: {
2272
- type: "string",
2273
- description: "Plain-English description of what this query answers; hosts may record or share it."
2274
- },
2275
- givens: {
2276
- type: "object",
2277
- description: "Values for $NAME givens, keyed by name (no $). Discover which a query needs with execute:false."
2278
- },
2279
- execute: {
2280
- type: "boolean",
2281
- description: "Default true. false \u2192 compile/validate only (returns SQL + the givens the query references)."
2282
- },
2283
- max_rows: { type: "integer", minimum: 1, maximum: 1e4, description: `Row cap (default ${DEFAULT_ROW_LIMIT}).` }
2284
- },
2285
- required: ["source", "malloy"],
2286
- additionalProperties: false
2287
- },
2288
- handler: async (args) => {
2289
- const source = argString(args, "source");
2290
- const modelRefArg = argOptString(args, "model_ref");
2291
- const execute = argOptBool(args, "execute") ?? true;
2292
- const r = await resolveModel(host, source, modelRefArg);
2293
- if ("problem" in r) return { ok: false, problems: [r.problem] };
2294
- const modelRef = r.model_ref;
2295
- if (modelRefArg && host.list) {
2296
- const entries = (await host.list()).entries;
2297
- const here = entries.find((e) => e.model_ref === modelRef);
2298
- const inModel = here?.sources?.some((s) => s.source_ref === source) ?? false;
2299
- const elsewhere = entries.filter((e) => e.model_ref !== modelRef && e.sources?.some((s) => s.source_ref === source)).map((e) => e.model_ref);
2300
- if (here && !inModel && elsewhere.length > 0) {
2301
- return {
2302
- ok: false,
2303
- problems: [
2304
- codeProblem(
2305
- "source-not-in-model",
2306
- `Model '${modelRef}' has no source '${source}' \u2014 it's in: ${elsewhere.join(", ")}. Pass that model_ref, or fix the source name.`
2307
- )
2308
- ]
2309
- };
2310
- }
2311
- }
2312
- try {
2313
- return await host.withModel(modelRef, async (m) => {
2314
- const ref = m.ref ?? modelRef;
2315
- const res = await executeQuery(
2316
- m,
2317
- args,
2318
- queryFieldFix(modelRef, source, argString(args, "malloy")),
2319
- opts.result
2320
- );
2321
- if (!execute) return { ...res, model_ref: ref };
2322
- const { sql, ...rest } = res;
2323
- const out = { ...rest, model_ref: ref };
2324
- if (sql !== void 0) out[HOST_ONLY] = { sql };
2325
- return out;
2326
- });
2327
- } catch (e) {
2328
- return { ok: false, problems: [refModelProblem(modelRef, e)] };
2329
+ async function modelArtifact(runtime, entry, defaultName) {
2330
+ try {
2331
+ const model = await runtime.loadModel(entry).getModel();
2332
+ const composite = readArtifactTag({ runExpr: "", defaultName }, model);
2333
+ if (composite && (composite.tiles || composite.query)) return { ok: true, artifact: composite };
2334
+ for (const queryName of model.queries().named) {
2335
+ const pq = model.getPreparedQueryByName(queryName);
2336
+ const info = readArtifactTag({ runExpr: queryName, defaultName }, pq);
2337
+ if (info && !info.tiles) return { ok: true, artifact: info };
2338
+ }
2339
+ for (const src of model.explores) {
2340
+ for (const field of src.allFields) {
2341
+ if (!field.isQueryField()) continue;
2342
+ const view = field;
2343
+ const info = readArtifactTag(
2344
+ { runExpr: `${src.name} -> ${view.name}`, defaultName, source: src.name, view: view.name },
2345
+ view
2346
+ );
2347
+ if (info && !info.tiles) return { ok: true, artifact: info };
2329
2348
  }
2330
2349
  }
2331
- };
2350
+ return { ok: true, artifact: void 0 };
2351
+ } catch (e) {
2352
+ return { ok: false, error: e instanceof Error ? e.message : String(e) };
2353
+ }
2332
2354
  }
2333
- function exploreSurface(host, opts = {}) {
2334
- const tools = [];
2335
- if (host.list) tools.push(listSourcesTool(host));
2336
- tools.push(describeSourceTool(host));
2337
- tools.push(exploreQueryTool(host, opts));
2338
- tools.push(yoHelpTool());
2339
- return {
2340
- tools: tools.map(withHelp),
2341
- instructions: assembleInstructions("explore"),
2342
- skills: sharedSkills()
2355
+ var INSTANCE_PLACEHOLDER = "{{INSTANCE_NAME}}";
2356
+ function renderInstructions(text, instanceName) {
2357
+ return text.replaceAll(INSTANCE_PLACEHOLDER, instanceName);
2358
+ }
2359
+ var VIRTUAL_BASE = "memory://mcp-engine/";
2360
+ function normalizeUrl2(u) {
2361
+ if (u.includes("://")) return new URL(u);
2362
+ return url.pathToFileURL(path.resolve(u));
2363
+ }
2364
+ function inlineVirtualUrl(baseUrl) {
2365
+ if (baseUrl) return new URL("__inline__.malloy", normalizeUrl2(baseUrl));
2366
+ return new URL(VIRTUAL_BASE + "__inline__.malloy");
2367
+ }
2368
+ function prepareSource(base, input) {
2369
+ const inline = "source" in input;
2370
+ const entry = inline ? inlineVirtualUrl(input.baseUrl) : normalizeUrl2(input.url);
2371
+ const cache = /* @__PURE__ */ new Map();
2372
+ if (inline) cache.set(entry.href, input.source);
2373
+ const reader = {
2374
+ readURL: async (u) => {
2375
+ const cached = cache.get(u.href);
2376
+ if (cached !== void 0) return cached;
2377
+ const text = await base.readURL(u);
2378
+ const str2 = typeof text === "string" ? text : String(text);
2379
+ cache.set(u.href, str2);
2380
+ return str2;
2381
+ }
2343
2382
  };
2383
+ return { reader, entry, readSource: (href) => cache.get(href) };
2344
2384
  }
2345
2385
  var pathSchema = {
2346
2386
  type: "string",
@@ -3789,17 +3829,6 @@ import {
3789
3829
  import {
3790
3830
  fromJsonSchema
3791
3831
  } from "@modelcontextprotocol/server";
3792
- var HOST_ONLY2 = "host_only";
3793
- function toContent(result) {
3794
- const { malloy_text, [HOST_ONLY2]: _hostOnly, ...rest } = result;
3795
- const content = [
3796
- { type: "text", text: JSON.stringify(rest, null, 2) }
3797
- ];
3798
- if (typeof malloy_text === "string" && malloy_text.length > 0) {
3799
- content.push({ type: "text", text: malloy_text });
3800
- }
3801
- return { content, structuredContent: { ...rest } };
3802
- }
3803
3832
  var PASS_THROUGH = {
3804
3833
  getValidator: () => (input) => ({ valid: true, data: input, errorMessage: void 0 })
3805
3834
  };