---
title: "Create Query"
method: POST
path: "/data/projects/{projectId}/queries"
tags: ["Data -- Queries"]
---

# Create Query

`POST /data/projects/{projectId}/queries`

## Request

- Base URL: `https://partner.peaka.studio/api/v1`
- URL: `https://partner.peaka.studio/api/v1/data/projects/{projectId}/queries`
- Auth: HTTP bearer

Creates a new query under the given project. Supports plain and materialized query types. Optionally accepts a path to place the query in a folder hierarchy. A MATERIALIZED query is materialized immediately on create and its result is queryable as `"peaka"."mtquery"."<name>"`; an optional `schedule` keeps it refreshed. To materialize an existing query, send `inputQueryRefId` with the source query's id instead of `inputQuery`: a snapshot of the source SQL is taken at create time and stored as the new query's own `inputQuery` (the source query is left untouched, and later changes to it do not propagate).

## Path parameters

- `projectId` string, required

## Query parameters

- `checkSchemaExists` boolean

## Request body

- QueryRequest
  - `displayName` string: The display name of the query.
  - `inputQuery` string, nullable: The SQL query. Required unless inputQueryRefId is provided.
  - `queryType` 'PLAIN' | 'MATERIALIZED': The type of the query. Defaults to PLAIN.
  - `schedule` MaterializedQuerySchedule, nullable: Schedule configuration of a materialized query. Provide EITHER an interval schedule (`type=interval` with `repeatDuration`) OR a cron schedule (`type=cron` with `cronExpression` and optional `timezone`). Use `type=none` for no schedule. The fields that do not apply to the chosen type are omitted.
    - `type` 'interval' | 'cron' | 'none': Type of schedule.
    - `cronExpression` string, nullable: UNIX cron expression (minute hour day-of-month month day-of-week), e.g. '0 0 * * *' for every day at midnight. Set only when the schedule type is 'cron'.
    - `repeatDuration` string, nullable: ISO-8601 duration between refreshes, e.g. 'PT6H' (every 6 hours), 'PT12H' (twice daily), 'P1D' (daily). Set only when the schedule type is 'interval'.
    - `timezone` string, nullable: IANA timezone used to evaluate the cron expression, e.g. 'UTC' or 'Europe/Istanbul'. Set only when the schedule type is 'cron'.
  - `inputQueryRefId` string, nullable: The id of an existing query to materialize. Valid only if the query type is MATERIALIZED. When set, the materialized query is built from the referenced query's SQL and inputQuery is not required. The reference is resolved when the request is processed: a snapshot of the referenced query's SQL is stored as this query's inputQuery. The reference id itself is not persisted and is not returned in responses; later changes to the referenced query do not propagate. Send the reference again on an update to re-resolve from the source.
  - `path` string, nullable: The folder path to place this query in. Intermediate folders are created automatically. If omitted, the query is placed at the root level.

## Response `200`

Query created

- Query: A saved query belonging to a project.
  - `id` string: The ID of the query.
  - `displayName` string: The display name of the query.
  - `name` string: The name of the query used in SQL, e.g. SELECT * FROM "peaka"."query"."<name>". For a MATERIALIZED query the materialized result is queryable as "peaka"."mtquery"."<name>".
  - `inputQuery` string: The SQL query. For a materialized query created from an existing query (via inputQueryRefId), this holds the snapshot of the source query's SQL resolved when the query was created or last updated with the reference.
  - `queryType` 'PLAIN' | 'MATERIALIZED': The type of the query.
  - `schedule` MaterializedQuerySchedule, nullable: Schedule configuration of a materialized query. Provide EITHER an interval schedule (`type=interval` with `repeatDuration`) OR a cron schedule (`type=cron` with `cronExpression` and optional `timezone`). Use `type=none` for no schedule. The fields that do not apply to the chosen type are omitted.
    - `type` 'interval' | 'cron' | 'none': Type of schedule.
    - `cronExpression` string, nullable: UNIX cron expression (minute hour day-of-month month day-of-week), e.g. '0 0 * * *' for every day at midnight. Set only when the schedule type is 'cron'.
    - `repeatDuration` string, nullable: ISO-8601 duration between refreshes, e.g. 'PT6H' (every 6 hours), 'PT12H' (twice daily), 'P1D' (daily). Set only when the schedule type is 'interval'.
    - `timezone` string, nullable: IANA timezone used to evaluate the cron expression, e.g. 'UTC' or 'Europe/Istanbul'. Set only when the schedule type is 'cron'.
  - `path` string, nullable: The folder path of the query (e.g. "/analytics/dashboards"). Null if not in any folder.
  - `folderId` string, nullable: The ID of the folder containing this query. Null if not in any folder.

---

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