# queries operations

MCP tools and operation permissions for queries.

Generated from the shared operation catalog. Use [the JSON catalog](https://bytesmap.com/docs/reference/operations.json) for complete input schemas. Required dependency checks can be stricter than the resource permission listed below.

## query_list

List the saved queries in this workspace. Each carries the source it reads and whether it is portable (the bytesmap IR) or native to one engine.

- **HTTP:** `GET /api/queries`
- **SDK:** `client.queries.list(input)`
- **Access:** workspace; query / read
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | string |

## query_create

Save a query without executing it. For editable visual nodes use the saved-flow format returned by flow_catalog and validate with flow_validate. Portable IR and {kind:"native"} queries are also supported for advanced SQL. Read actual source schemas first; never invent columns or infer their meaning.

- **HTTP:** `POST /api/queries`
- **SDK:** `client.queries.create(input)`
- **Access:** workspace; query / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | See schema |
| `name` | Required | string |
| `sourceId` | Required | string |
| `query` | Required | A bytesmap query. Portable: {kind:"growth"\|"row-count"\|"top-values"\|"histogram"\|"chart"\|"rows", …}. Or native: {kind:"native", sourceKind:"<the source's kind>", statement:"…"} in the driver's own language — SQL for SQL engines, a JSON aggregation pipeline for MongoDB. For {kind:"chart"}: `dimensions[].role` is "group" (an axis, at most two) or "series" (a breakdown, at most one), and a series needs `seriesLimit` rather than `limit` — `limit` cuts rows of the joint group-by and can leave a series holding only some of its buckets. `measures[].filter` is a per-measure WHERE; `having` filters the aggregates and its leaves name measure aliases (m0, m1); `offset` pages; `totals` is "none"\|"with"\|"only". `from` is a table ref or a derived relation {isDerived:true, statement, sourceKind, aggregated, columns} — your own SELECT used as the FROM, which the rest of the query then groups, filters and pages. `expression` on a measure or dimension is a raw fragment in the source's dialect: read-only-checked, and it makes the saved query non-portable. |
| `params` | Optional | object |

## query_read

Read one saved query's definition and parameters.

- **HTTP:** `GET /api/queries/:id`
- **SDK:** `client.queries.get(input)`
- **Access:** workspace; query / read
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `id` | Required | string |

## query_update

Update a saved query, including its flow graph nodes, connections, or native statement. Read query_read first and preserve fields you are not changing. Saving does not run the query.

- **HTTP:** `PATCH /api/queries/:id`
- **SDK:** `client.queries.update(input)`
- **Access:** workspace; query / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `sourceId` | Optional | string |
| `name` | Optional | string |
| `query` | Optional | See schema |
| `params` | Optional | object |
| `id` | Required | string |

## query_delete

Delete a saved query definition. Check charts that depend on it before deleting. This does not delete data from its source.

- **HTTP:** `DELETE /api/queries/:id`
- **SDK:** `client.queries.remove(input)`
- **Access:** workspace; query / admin
- **Effect annotation:** May change state or run effects; destructive operation

| Input | Requirement | Description |
| --- | --- | --- |
| `id` | Required | string |

## query_run

Run a saved query and get rows back. Pass `params` to override its defaults — a timestamp param accepts a relative offset like "-7d". The result carries `estimated`, `sampled` and `truncated` flags in `meta` that must be surfaced, not dropped. Saved flows return a FlowChartResults bundle with each chart output and shared execution stats. For flows, params bind declared document.parameters in conditions and named SQL values. Configure paging and limits in the nodes; request paging, counts and explain are not supported.

- **HTTP:** `POST /api/queries/:id/run`
- **SDK:** `client.queries.run(input)`
- **Access:** workspace; query / run
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `params` | Optional | object |
| `maxRows` | Optional | integer |
| `page` | Optional | object |
| `count` | Optional | boolean |
| `explain` | Optional | boolean |
| `id` | Required | string |

## query_cost

Estimate a saved query’s PostgreSQL planner cost without executing it. Includes bounded source reads and extra totals passes. Cost units are not milliseconds or money.

- **HTTP:** `POST /api/queries/:id/cost`
- **SDK:** `client.queries.estimate(input)`
- **Access:** workspace; query / run
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `params` | Optional | object |
| `maxRows` | Optional | integer |
| `page` | Optional | object |
| `count` | Optional | boolean |
| `id` | Required | string |

## chart_suggest

Ask bytesmap which chart fits a saved query, by running it with a tiny row cap and reading the result types. Returns a ready-to-save chart spec. A result that is genuinely a table comes back as {mark:"table"} rather than being forced into a chart.

- **HTTP:** `POST /api/queries/:id/suggest`
- **SDK:** `client.queries.suggestChart(input)`
- **Access:** workspace; query / run
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `id` | Required | string |