---
title: "Update a query"
method: PUT
path: "/queries"
tags: ["Queries"]
---

# Update a query

`PUT /queries`

## Request

- Base URL: `https://saturnsql.com/api`
- URL: `https://saturnsql.com/api/queries`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Updates a saved query. Only the fields you send change; `sql` and `folderPath` are optional. Available to API keys with the `write` scope. Changing the `sql` or `variables` of a query that has a schedule also needs the `execute` scope, since the schedule runs it.

## Request body

- object
  - `queryId` string, required
  - `name` string, required
  - `sql` string
  - `folderPath` string, nullable: A single flat folder label, not a nested path ("A/B" is one label); null moves to root; omit to leave unchanged
  - `variables` QueryVariable[]: Replaces the stored declarations. Omit to leave them unchanged; send [] to clear them.
    - `name` string, required: Matches `[A-Za-z_][A-Za-z0-9_]*`
    - `type` 'date' | 'text' | 'number' | 'boolean' | 'dropdown', required
    - `required` boolean: An empty value for a required variable is a 422, not an empty substitution.
    - `default` object, nullable: Used when the value is absent. A `relative` default is only valid on a `date` variable and resolves against the caller time zone (or the schedule time zone).
      - `kind` 'fixed' | 'relative'
      - `value` string: Literal for `fixed`; one of today, yesterday, 7_days_ago, 30_days_ago, 90_days_ago, start_of_this_month, start_of_last_month, end_of_last_month, start_of_this_year for `relative`.
    - `options` string[]: Dropdown only, non-empty. A value outside this list is a 422.

## Response `200`

Updated

- SavedQuery
  - `id` string
  - `name` string
  - `sql` string
  - `connectionId` string, nullable
  - `folderPath` string, nullable: A single flat folder label (not a nested path); "A/B" is one folder named "A/B", not "A" containing "B". null = root.
  - `isShared` boolean
  - `description` string, nullable: Subtitle on the report page. Returned by GET /queries; nothing can set it yet, so always null.
  - `chart` ChartSpec: How a report should be drawn. Stored verbatim and interpreted at render time, since the columns a spec refers to only exist after a run: a spec naming a column the SELECT list no longer returns falls back to the shape-derived guess rather than failing. With no spec stored, the result shape decides — see the "saved query is also a report page" section of the API guide for the rules an agent should write SQL against.
    - `type` 'line' | 'area' | 'bar' | 'scatter' | 'share' | 'number' | 'none', required: `none` suppresses the chart for good, which is why it is distinct from a null `chart`. `share` is never guessed and must be set explicitly: its shape is identical to `bar` and nothing in the data says which is meant.
    - `x` string: Column for the x axis or the category. Absent for `number`.
    - `series` string[]: Measure columns, in order. Capped at 3: the validated palette separates three series by lightness and a fourth has no colour.
    - `group` string: Low-cardinality column splitting a scatter into groups.
  - `userId` string
  - `variables` QueryVariable[]: Declared `{{name}}` variables, in first-appearance order in the SQL. Empty when the query has none.
    - `name` string, required: Matches `[A-Za-z_][A-Za-z0-9_]*`
    - `type` 'date' | 'text' | 'number' | 'boolean' | 'dropdown', required
    - `required` boolean: An empty value for a required variable is a 422, not an empty substitution.
    - `default` object, nullable: Used when the value is absent. A `relative` default is only valid on a `date` variable and resolves against the caller time zone (or the schedule time zone).
      - `kind` 'fixed' | 'relative'
      - `value` string: Literal for `fixed`; one of today, yesterday, 7_days_ago, 30_days_ago, 90_days_ago, start_of_this_month, start_of_last_month, end_of_last_month, start_of_this_year for `relative`.
    - `options` string[]: Dropdown only, non-empty. A value outside this list is a 422.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400`: Validation failed
- `401`: Bad or missing credentials
- `403`: Insufficient scope or plan restriction
- `404`: Resource not found

---

[API](https://skmtc.dev/saturnsql/apis/saturnsql-api.md) · [All operations](https://skmtc.dev/saturnsql/apis/saturnsql-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saturnsql/apis/saturnsql-api/revisions/90a3e54ad115?raw)