@malloydata/malloyyo 0.2.62 → 0.2.64
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.
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.
|
|
14
|
+
var version = "0.2.64";
|
|
15
15
|
|
|
16
16
|
// src/update-check.ts
|
|
17
17
|
var UPDATE_CHECK_ARGV = "__update-check";
|
|
@@ -328,7 +328,8 @@ var contentFiles = {
|
|
|
328
328
|
"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",
|
|
329
329
|
"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',
|
|
330
330
|
"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; set the\n`MOTHERDUCK_TOKEN` environment variable.\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',
|
|
331
|
-
"develop/
|
|
331
|
+
"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',
|
|
332
|
+
"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',
|
|
332
333
|
"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",
|
|
333
334
|
"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",
|
|
334
335
|
"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\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,9 +339,9 @@ var contentFiles = {
|
|
|
338
339
|
"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",
|
|
339
340
|
"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",
|
|
340
341
|
"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",
|
|
341
|
-
"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.\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',
|
|
342
|
+
"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',
|
|
342
343
|
"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',
|
|
343
|
-
"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. It\'s what `list_sources` shows the\nhosted app and any MCP client, and it\'s the only place to record the things a\nconsumer can\'t infer \u2014 which source answers which question, and any measure\nwhose meaning is subtle.\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',
|
|
344
|
+
"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',
|
|
344
345
|
"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',
|
|
345
346
|
"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',
|
|
346
347
|
"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"
|
|
@@ -375,7 +376,7 @@ var prompts = {
|
|
|
375
376
|
"title": "Inspect a published source"
|
|
376
377
|
},
|
|
377
378
|
"list_sources": {
|
|
378
|
-
"description": "List the sources you can query, grouped by the model that publishes them, with
|
|
379
|
+
"description": "List the sources you can query, grouped by the model that publishes them, each with a one-line description of what it answers. Pick a source from its description, then describe_source it \u2014 that returns its fields and the model author's instructions for using it \u2014 before writing a query. A model may also report `dashboards` \u2014 pre-built pages for that model, each with a `url` a person can open; offer one when it already covers the question, and query the sources otherwise.",
|
|
379
380
|
"title": "List sources"
|
|
380
381
|
}
|
|
381
382
|
}
|
|
@@ -926,6 +927,7 @@ function walkModel(model, rootUri, opts, readSource) {
|
|
|
926
927
|
runs.push(info);
|
|
927
928
|
}
|
|
928
929
|
const out = { entry: rootUri, sources, queries, runs };
|
|
930
|
+
applyDocs(out, model.annotations);
|
|
929
931
|
const modelAnnotations = annotationList(model.annotations);
|
|
930
932
|
if (modelAnnotations.length > 0) out.annotations = modelAnnotations;
|
|
931
933
|
const givens = [];
|
|
@@ -1164,16 +1166,43 @@ function buildSourceDescribe(compiled, name) {
|
|
|
1164
1166
|
function sourceEntryOf(s) {
|
|
1165
1167
|
const e = { source_ref: s.name };
|
|
1166
1168
|
if (s.description) e.description = s.description;
|
|
1167
|
-
if (s.instructions) e.instructions = s.instructions;
|
|
1168
1169
|
if (s.must_quote) e.must_quote = true;
|
|
1169
1170
|
return e;
|
|
1170
1171
|
}
|
|
1171
1172
|
function modelCatalogEntry(model_ref, model) {
|
|
1172
1173
|
const entry = { model_ref };
|
|
1174
|
+
if (model.description) entry.description = model.description;
|
|
1173
1175
|
const sources = Object.values(model.sources).map(sourceEntryOf);
|
|
1174
1176
|
if (sources.length) entry.sources = sources;
|
|
1175
1177
|
return entry;
|
|
1176
1178
|
}
|
|
1179
|
+
var SOURCE_DESCRIPTION_CHARS = 300;
|
|
1180
|
+
var MODEL_DESCRIPTION_CHARS = 500;
|
|
1181
|
+
function catalogDocWarnings(entry) {
|
|
1182
|
+
const out = [];
|
|
1183
|
+
const help = 'see yo_help("develop/documenting-models")';
|
|
1184
|
+
if (!entry.description) {
|
|
1185
|
+
out.push(
|
|
1186
|
+
`the model has no ##" description \u2014 list_sources shows nothing for what this dataset is (${help})`
|
|
1187
|
+
);
|
|
1188
|
+
} else if (entry.description.length > MODEL_DESCRIPTION_CHARS) {
|
|
1189
|
+
out.push(
|
|
1190
|
+
`the model's ##" is ${entry.description.length} characters; keep it to a sentence or two (under ${MODEL_DESCRIPTION_CHARS}) \u2014 list_sources shows it on every question (${help})`
|
|
1191
|
+
);
|
|
1192
|
+
}
|
|
1193
|
+
for (const s of entry.sources ?? []) {
|
|
1194
|
+
if (!s.description) {
|
|
1195
|
+
out.push(
|
|
1196
|
+
`source '${s.source_ref}' has no #" description \u2014 list_sources is how a reader picks a source (${help})`
|
|
1197
|
+
);
|
|
1198
|
+
} else if (s.description.length > SOURCE_DESCRIPTION_CHARS) {
|
|
1199
|
+
out.push(
|
|
1200
|
+
`source '${s.source_ref}': its #" is ${s.description.length} characters; keep it to one sentence on what the source answers (under ${SOURCE_DESCRIPTION_CHARS}) and move usage guidance to #(agent), which describe_source shows (${help})`
|
|
1201
|
+
);
|
|
1202
|
+
}
|
|
1203
|
+
}
|
|
1204
|
+
return out;
|
|
1205
|
+
}
|
|
1177
1206
|
var RESERVED_GIVEN_PREFIX = "MALLOYYO_";
|
|
1178
1207
|
function withoutReservedGivens(givens) {
|
|
1179
1208
|
if (!givens) return void 0;
|
|
@@ -2060,13 +2089,11 @@ function listSourcesTool(host) {
|
|
|
2060
2089
|
for (const e of entries) {
|
|
2061
2090
|
const m = {};
|
|
2062
2091
|
if (e.description) m.description = e.description;
|
|
2063
|
-
if (e.instructions) m.instructions = e.instructions;
|
|
2064
2092
|
if (e.sources?.length) {
|
|
2065
2093
|
const sources = /* @__PURE__ */ Object.create(null);
|
|
2066
2094
|
for (const s of e.sources) {
|
|
2067
2095
|
const o = {};
|
|
2068
2096
|
if (s.description) o.description = s.description;
|
|
2069
|
-
if (s.instructions) o.instructions = s.instructions;
|
|
2070
2097
|
if (s.must_quote) o.must_quote = true;
|
|
2071
2098
|
sources[s.source_ref] = o;
|
|
2072
2099
|
}
|
|
@@ -2828,6 +2855,13 @@ async function makeRunner(root, opts = {}) {
|
|
|
2828
2855
|
return {};
|
|
2829
2856
|
}
|
|
2830
2857
|
},
|
|
2858
|
+
catalogWarnings: async () => {
|
|
2859
|
+
if (!fs3.existsSync(path4.join(abs, ENTRY))) return [];
|
|
2860
|
+
return lease(async (runtime, entry) => {
|
|
2861
|
+
const compiled = await compile(runtime, entry, { exportedOnly: true });
|
|
2862
|
+
return compiled.ok && compiled.model ? catalogDocWarnings(modelCatalogEntry(ENTRY, compiled.model)) : [];
|
|
2863
|
+
}).catch(() => []);
|
|
2864
|
+
},
|
|
2831
2865
|
async dispose() {
|
|
2832
2866
|
clearIdleTimer();
|
|
2833
2867
|
if (!configPromise) return;
|
|
@@ -3184,7 +3218,9 @@ async function runLint(abs, runner) {
|
|
|
3184
3218
|
const dashboards = [];
|
|
3185
3219
|
if (runner.entryExists()) {
|
|
3186
3220
|
const arts = await runner.artifacts();
|
|
3187
|
-
|
|
3221
|
+
const warnings = await runner.catalogWarnings();
|
|
3222
|
+
const errors = arts.ok ? [] : [arts.error];
|
|
3223
|
+
if (errors.length || warnings.length) dashboards.push({ name: "index.malloy", errors, warnings });
|
|
3188
3224
|
}
|
|
3189
3225
|
const dir = join4(abs, "dashboards");
|
|
3190
3226
|
if (!existsSync4(dir)) return { ok: dashboards.every((d) => d.errors.length === 0), dashboards };
|
|
@@ -28,6 +28,9 @@ Two things to get right before you touch files:
|
|
|
28
28
|
|
|
29
29
|
`##"` is the MODEL's doc string; a single `#"` would attach to the next
|
|
30
30
|
declaration instead. Title derives from the name when absent.
|
|
31
|
+
- **Document each exported source** with a one-sentence `#"` (what it answers)
|
|
32
|
+
and `#(agent)` lines for how to query it. The short ones are read on every
|
|
33
|
+
question, so keep them short — `yo_help("develop/documenting-models")`.
|
|
31
34
|
- **`malloy-config.json` can be at the repo root** (shared by every dataset) or
|
|
32
35
|
**in a dataset** (its own, replacing the root's). Nearest one wins.
|
|
33
36
|
|