# WSQL

WSQL (Wink SQL) is a governed query language over Wink datasources. It looks like
PostgreSQL `SELECT`, with safety restrictions: no writes, automatic tenant scoping,
and no access to physical database tables.

## Agent workflow

1. Call `list_data_sources` and pick real slugs. Do not invent names.
2. Call `get_data_source_detail` for each candidate. Copy column names exactly.
3. If a filter needs a value from a list, call `get_data_source_choices`.
4. Draft WSQL using those slugs and columns.
5. Call `run_wsql_query` with `action` `"validate"`.
6. Ask the user before running a query that returns live data, unless they already
   asked to execute or you are previewing a query for an app they requested.
7. Call `run_wsql_query` with `action` `"execute"` after validation and consent.
   If you are about to build an AI App on this query, inspect the returned rows first.
   Do not bind UI to a shape you have only validated.

`run_wsql_query` takes the WSQL string in `wsql`. The MCP tool always sends it as a WSQL
query. `action` must be `validate` or `execute`.

## Language rules

- Read-only `SELECT` (including joins, filters, grouping, and expressions the validator
  accepts). No inserts, updates, deletes, or DDL.
- Reference datasources by the slug returned from MCP, not by a guessed table name.
- Column names are human-friendly. Preserve exact casing and spaces: `"Invoice Number"`,
  not `invoice_number`, unless the inspected schema actually used the latter.
- Prefer explicit column names or expressions over positional shortcuts (`SELECT 1`,
  ordinal `GROUP BY 1`) when the user's question is about real fields.
- Stay in WSQL. Do not rewrite the query into another SQL dialect or guess physical
  table names.
- If validation fails, read the error, inspect the datasource again if needed, and fix
  the query. Do not keep guessing column names.

## Multi-entity

When the user wants a roll-up across child organisations, pass
`include_child_organisations: true` on the relevant MCP calls. Do not assume roll-up is
on by default.

## Mock data

`use_mock_data` is only when the user asked for mock results. Default to live data.

## What not to do

- Do not invent datasource slugs or columns.
- Do not claim a query ran if you only validated it.
- Stay in WSQL.
- Do not execute destructive-sounding requests; WSQL cannot write, so say so and use AI
  tools if the user actually wants an action in a source system.