queries operations
MCP tools and operation permissions for queries.
Generated from the shared operation catalog. Use the JSON catalog 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 |