jaz-pseudo-sql

Jaz Pseudo-SQL Skill

You are running ad-hoc data queries against the curated reporting schema in Jaz — a read-only SQL DSL exposed via the Jaz API at /api/v1/reports/sql-query/*. Use this skill when:

• The user asks a custom analytical question that doesn't match any download_export(exportType=...) canonical report.
• The user wants a specific CSV slice ("invoices over $5k issued this quarter that are still unpaid") that the structured search_* tools can't express cleanly.
• The user wants to JOIN, GROUP BY, or aggregate across multiple tables in one query.

NOT a general-purpose database surface. Curated schema only — no DML (DELETE/UPDATE/INSERT), no multi-statement input, no access to private columns. Validators reject anything that isn't a single SELECT against an allowed table. See references/error-catalog.md for the full error vocabulary.

Source of truth for the schema

Call get_pseudo_sql_schema first for the live curated catalog (~70 tables, 91 join edges, 47 functions). Pass table to scope it to one table and its joins — the whole catalog is ~18k tokens, one table is ~1k.

The syntax guide is a SEPARATE call, get_pseudo_sql_syntax, returning the canonical jaz-pseudo-sql.md body in agentSkillsDoc.content. It is static — identical for every organization — so fetch it once, cache on version, and skip it entirely if you already have this skill loaded. The two were one response until 2026-09-03; combined they cost ~35k tokens on a call documented as "before any query", of which 42% was the unchanging guide.

The version field is a stable 16-char hex hash; cache by it. If you've already called the tool this session and the version is unchanged on a re-call, the schema and skill body are identical to your cached copy — no need to re-read.

Don't write a pseudo-SQL query from memory. The catalog grows; column names change; the live schema is the only source you should trust.

When NOT to use this skill

Use this instead	When
download_export(exportType='analysis-anomalous-invoices') etc.	Canonical anomaly / audit / risk reports — they're tuned, parameterized, and faster than re-deriving them in SQL. See jaz-api Rule 141.
download_export(exportType='trial-balance') etc.	Statements (TB, BS, P&L, GL, cashflow). The reporting engine handles period closing rules, intercompany eliminations, FX revaluation. SQL would miss these.
search_invoices(filter:...), search_bills, etc.	Listing entities with structured filters. Returns typed objects, supports pagination, faster than SQL.
get_invoice(resourceId) etc.	Single-entity lookup by ID.
view_auto_reconciliation	Bank reconciliation match suggestions.