Open a JSON document and return its size and top-level shape. Accepts a file path or inline text, and transparently decodes Zstd, Base64-Zstd and PostgreSQL bytea (\x…) payloads. Malformed JSON is auto-repaired and flagged. Returns a docId (d1, d2, …) that every other tool takes. The document itself is never returned — read it with get_schema, run_query, profile or sample instead. Prefer path for an existing or large document. For a single question, skip this step: those tools also take filePath.

First step toward a spreadsheet: find the repeatable arrays and object maps in a loaded document that can become linked tables. Returns table anchors, row counts, fields, types, and deterministic format suggestions; document values are not returned. Next, draft_spec writes a mapping and convert writes the file. For field names and types use get_schema, for coverage and statistics profile, and for real values sample.

Draft a reviewable converter spec for a loaded document, usually after inspect shows its tables. This does not convert anything: pass the spec to convert, inline or as the file you saved. Save it to outPath for human editing, or omit outPath to return the JSON under the response cap; an existing outPath is refused unless overwrite=true. format picks one .xlsx workbook or a .zip of CSVs; baseDate gives time-only columns a date.

Write a loaded document out as linked tables — one .xlsx workbook, or a .zip of CSVs — by running a frozen converter spec deterministically. The spec comes from draft_spec, reviewed or edited: pass it inline as spec or as a file in specPath, exactly one of the two. format overrides the format the spec names. Returns row/skipped/warning counts, never the output rows. An existing outPath is refused unless overwrite=true. For one query's result as a single CSV or JSONL file, use export_result instead.

Field names and types of the document — never values. With no path, describes the whole document; with a path, describes just what it selects, merged across matches (so $.tasks[*] describes an element, not the first element). Array shapes are inferred from up to 30 elements; use profile for exact coverage/counts. Start here: it is how you learn which paths run_query can use. For one question, pass filePath directly; it opens the file and returns a reusable docId in the same call. A path that matches nothing returns an error naming that path.

Use this instead of ad-hoc Python for JSON counts, filtered exact sums/averages/min/max, composite groups, distinct values, top/bottom ranking, and field projection. It scans server-side and returns only the bounded answer. Pass filePath for a one-call answer, or docId to reuse an open document. For field names and types use get_schema; for coverage and statistics of many fields at once, profile; to judge counts against expectations, run_checks. Grammar (a JSONPath subset with aggregation pipes):

Paths: $.key $['odd key'] $[3] $[-1] $[1:5] $.arr[] $..key (recursive) A [...] step attaches directly to what precedes it: $['odd key'], $.a['b c'] — never $.['odd key']. Any key that is not a plain identifier (space, '-', '.') must be bracketed: $['line-items'], @['unit price']. $.arr is the array itself; $.arr[] is its elements — $.orders[] | count counts the orders, $.orders | count is 1. Predicates filter the CHILDREN of the current node: $.tasks[?(...)] A [?(...)] step already yields the matched elements — never follow it with []. Operators: == != > >= < <= (numbers and strings) Boolean: && || ! Grouping: ( ) — there is no !~; negate with !( … ) Strings: @.name contains 'x' | startsWith | endsWith | @.name =~ /safe-regex/i Membership: @.status in ['A','B'] Arrays: @.tags contains 'x' Set: @.field — true unless the key is missing, null or false ('' and 0 count as set) Explicit: @.field present (key exists) | missing (no key) | isNull (value is null) Fields compare to fields: @.capacity.used > @.capacity.max A predicate holds one level only: no predicate inside a predicate, no $ path inside it Pipes: append AT MOST ONE, at the very end. Pipes never chain — | top(...) | pluck(...) is invalid. | count | sum(@.x) | avg(@.x) | min(@.x) | max(@.x) | distinct | group(@.x, @.y) | top(@.score, @.id) | bottom(@.score, @.id) | pluck(@.a, @.b.c) top/bottom/pluck already name their output columns — never add a second pipe to project them. A pipe argument is one plain field path (@.a.b) — no [], no arithmetic, no second query. A pipe without args operates on the matched values themselves: $.a[].n | sum

Examples: "how many tasks have no route" → $.tasks[?(!@.routeId)] | count "how many orders are there" → $.orders[] | count "failed tasks by reason" → $.tasks[?(@.status =~ /^failed$/i)] | group(@.failureReason) "tasks that are not cancelled" → $.tasks[?(!(@.status =~ /^cancelled$/i))] "top delayed tasks" → $.tasks[] | top(@.delayMinutes, @.id, @.status) "highest value orders showing just their id and amount" → $.orders[] | top(@.amount, @.id) "all statuses that appear" → $..status | distinct "ids and etas of pending tasks" → $.tasks[?(@.status =~ /^pending$/i)] | pluck(@.id, @.eta) "total line value of failed orders" → $.orders[?(@.status =~ /^failed$/i)].items[].lineTotal | sum "sum of the line-total column" → $['line-items'][*] | sum(@['line-total']) "the run id" → $['meta data']['run id'] "tasks outside india" → $.tasks[?(@.loc.lat < 8 || @.loc.lat > 37)]

Matches come back as path + preview; use | pluck(@.a, @.b) to project real fields into rows, or the sample tool for whole values. Only 10 detail rows return by default; set limit=0 for a count-only summary or page with offset+limit. Aggregates always scan every match. Numeric predicates and aggregates keep int64 and decimal digits exact. For only a count, append | count; the response is one scalar.

Profile one or more fields across every selected record in one server-side scan; this replaces ad-hoc Python loops for discovering or summarizing unfamiliar JSON fields. Pass filePath for a one-call answer, or docId to reuse an open document. Returns present/missing/null counts, type counts, distinct count, exact numeric sum/min/max/average, lengths, and top values. Use fields like "status" or "capacity.used" relative to each selected record; omit fields to auto-discover up to 20 fields on selected records or profile selected scalar values. For a filtered count or a group breakdown use run_query; for whole records use sample.

Read n real values at a path, exactly as they were parsed (int64 and decimal digits intact). A path that selects one container samples its children; a path that selects many nodes samples those nodes. Pass filePath for a one-call sample, or docId to reuse an open document. Use it to see what records really hold; to count or aggregate use run_query, for statistics profile, and for names and types get_schema.

Compare two documents opened with load_doc and return change counts plus the first 25 changes. There is no filePath shortcut: load both first. docIdA is the older side: additions and removals read A → B. Give keySpec to align arrays by identity (e.g. "id,orderId") so reordered elements are not reported as wholesale changes.

The CSV-only shortcut for export_result: run a query and write its complete table to a CSV file (RFC 4180, exact digits, formula-injection safe). Returns only the path, row count and byte size — the rows themselves never enter the conversation. The query must produce a table: use | pluck(…), | group(…) or | distinct. The file is streamed and published atomically, with the same 50 MB limit; an existing path is refused unless overwrite=true. Pass filePath to open and export an input file in one call, or docId to reuse an open document. For JSONL or nested values use export_result; for linked multi-table spreadsheets, convert.

Write every query match to a local file without sending the data through the conversation. JSONL accepts bare filtered matches and preserves nested values; CSV requires | pluck(…), | group(…) or | distinct. The response contains only format, path, exact row count, byte size and complete=true. Exports refuse rather than silently truncate when the 50 MB output safety limit would be exceeded. Output is streamed to a temporary file and published atomically; an existing path is refused unless overwrite=true. Pass filePath to open and export an input file in one call, or docId to reuse an open document. export_csv is this tool fixed to CSV. Use convert for linked multi-table spreadsheets, and run_query when a bounded answer in the conversation is enough.

Run deterministic checks — a query plus the count it expects — against a document; one verdict per check: pass, fail, or inconclusive (a | group or | distinct hit its 100,000-value cap, so the count is only a lower bound; never reported as a pass). Pass playbookPath for a jsonloupe playbook file, or checks inline. Playbook functions are JavaScript and are never run here. Expectations: {"type":"no-matches"}, {"type":"at-least-one"}, {"type":"exact-count","count":N}, {"type":"at-most","count":N}, {"type":"at-least","count":N}, {"type":"between","min":M,"max":N}. A check counts matches (groups/distinct values for | group / | distinct); value pipes like | sum are refused. A document that is not valid JSON is refused unless allowRepair is true. Failed and inconclusive checks list their first matched paths. Pass filePath for a one-call answer, or docId to reuse an open document. Use it to gate a document on counts you expect; for an open-ended count or breakdown use run_query.