Import

Any file → selected cell

File → Import (or Insert → Image / file…) opens a picker for any file type. Import always targets the selected cell (except full Metagrid JSON documents — see below). It never wipes your workbook unless you import a full metagrid-v2 document.

• Text-like files (txt, md, code, html, …) → cell text
• Images, PDFs, and other binaries → a file cell (one cell, like a checkbox). Space opens the viewer. Images show a small thumbnail in the cell. Files under ~1.5 MB store data inline; larger files keep name/type/size only.
• PDF form fields — when you open a fillable PDF, map each form field to a Metagrid formula or reference (e.g. Name, A1, Total., =A1&" "&B1). Save bindings on the file cell; preview or download a filled PDF with values resolved from the sheet.

JSON

File → Import of a metagrid-v2 document replaces the current workbook (full document swap).

Other JSON (and Paste with Ctrl+V) maps objects/arrays into structures at the selection. Comments (//, /* … */), trailing commas, and … placeholders are allowed — the nested object/array shape is what becomes lists, tables, and grids:

• Object → list (property names as indexes)
• Array of objects → table (union of keys as headers)
• Array of scalar rows (e.g. [[1,2],[3,4]]) → grid
• Other arrays → list; nested objects/arrays recurse (lists of lists, tables inside lists, …)
• A full metagrid-v2 document in the clipboard replaces the workbook (same as Import JSON)

// Paste this into a cell → list of lists
{
  "team": ["Ada", "Grace"],
  "budget": { "q1": 10, "q2": 12 }
}

Excel (.xlsx / .xls) and CSV

Spreadsheet import inserts into the selected cell. A single-sheet file unwraps: the cell is that sheet’s structure, named after the file, so the path is Filename.path rather than Filename.Sheet.path. Several sheets still become a Dictionary (indexes = sheet names).

• Default: every sheet is a grid (values + formulas, origin shifted to A1).
• Table only when both are true:
  1. The sheet is essentially one rectangular table (header row of labels + data body) — nothing else.
  2. Every formula is a calculated column: same formula pattern on every data row of that column, no mixed value overrides, and refs are table-safe:
     • same-row only (Excel B2 on row 2 → Metagrid Header.)
     • or a whole column in this table / structured column ref (→ bare Header)
     • not absolute cell pins like $A$1 / other-row A1 / sheet-qualified refs
  Values-only pure tables (no formulas) still import as tables when the sheet shape qualifies.
• Grid formulas keep A1 after shifting the used range to the top-left. Table calc columns are rewritten to Metagrid field refs.

Select a cell → Import → budget.xlsx (one sheet)
  → cell named Budget → Grid or Table

Select a cell → Import → workbook.xlsx (several sheets)
  → List {
       Sheet1 → Grid or Table,
       Sheet2 → Grid or Table,
       …
     }

From API

Queries → From API… GETs a URL into the selected cell and (by default) saves the URL plus credentials as a workbook query. Queries never refresh on their own — use Queries → Refresh / Refresh all / Manage. Auth styles:

• Auto — Authorization: Bearer plus X-API-Key / api-key (or HTTP Basic if the value looks like user:pass)
• Bearer / Token / Basic — standard Authorization schemes
• X-API-Key or api-key header, a query parameter (api_key by default), or a custom header

JSON objects and arrays become lists, tables, or grids. Common wrappers (data, results, items, value, JSON:API attributes) are unwrapped. CSV/TSV becomes a grid. If the browser is blocked by CORS (typical for authenticated APIs), the request is retried through the site’s import proxy.

The target cell shows a #n badge (the row in Queries ▸ Manage). Click it to open that query. Manage also lists the cell path and a Go to cell button. Nested results keep a Query segment at the end of the path.