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

# Execute Query

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

## Request

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

Executes a query and returns the result. Accepts a query builder object, a query ID, a query name, or a raw SQL statement.

The **`format`** query parameter controls the shape of the `data` array in the response:

| Value | Description |
|-------|-------------|
| `CELL_TYPED` *(default)* | Each cell is an object with `name`, `displayName`, `dataType`, `order`, and `value`. |
| `SIMPLE` | Each row is a flat JSON object whose keys are the column names. |
| `COMPACT` | Each row is a plain array of values ordered by column position. |

## Path parameters

- `projectId` string, required

## Query parameters

- `format` 'CELL_TYPED' | 'SIMPLE' | 'COMPACT'

## Request body

- union
  - QueryExecuteRequest: Executes a query using the query builder. The <code>from</code> field is required. <p>Minimal example: <pre> { "from": [ { "catalogName": "peaka", "schemaName": "query", "tableName": "samplequery" } ] } </pre> <p>With columns, filters, limit, offset, and orderBy: <pre> { "columns": ["amount"], "from": [ { "catalogName": "wilderman_green", "schemaName": "payment", "tableName": "charges" } ], "filters": { "and": [ [ { "column": { "catalogName": "wilderman_green", "schemaName": "payment", "tableName": "charges", "columnName": "amount" } }, ">", [150] ] ] }, "limit": 50, "offset": 0, "orderBy": ["amount DESC"] } </pre>
    - `columns` string[]: Columns to select. If omitted, all columns (<code>*</code>) are returned.
    - `from` TableForQuery[]: Tables to query from. At least one entry is required.
      - `catalogId` string
      - `catalogName` string
      - `schemaName` string
      - `tableName` string
    - `limit` integer: Maximum number of rows to return.
    - `offset` integer: Number of rows to skip before returning results.
    - `orderBy` string[]: Ordering specifications. Each entry is a column name optionally followed by <code>ASC</code> or <code>DESC</code>. Example: <code>[&quot;amount DESC&quot;, &quot;created_at ASC&quot;]</code>.
    - `filters` object: Filter conditions. Supports <code>and</code>/<code>or</code> logic with column comparisons.
    - `timeout` integer: Query timeout in seconds. A query that runs longer is stopped and the request fails with error code 102. Omitted or 0: no limit. Negative values are rejected.
  - QueryExecuteRequestId: Executes a query by its ID. <pre> { "id": "709922802836177297" } </pre>
    - `id` string: The ID of the query to execute.
    - `timeout` integer: Query timeout in seconds. A query that runs longer is stopped and the request fails with error code 102. Omitted or 0: no limit. Negative values are rejected.
  - QueryExecuteRequestName: Executes a query by its fully qualified name in the format <code>&lt;catalogName&gt;.&lt;schemaName&gt;.&lt;tableName&gt;</code>. <pre> {"qualifiedName": "peaka.query.samplequery"} </pre>
    - `qualifiedName` string: Fully qualified name of the query, e.g. <code>peaka.query.samplequery</code> or <code>peaka.mtquery.samplequery</code> or <code>stripe.payment.charges</code>
    - `timeout` integer: Query timeout in seconds. A query that runs longer is stopped and the request fails with error code 102. Omitted or 0: no limit. Negative values are rejected.
  - QueryExecuteRequestStatement: Executes a raw SQL statement directly via the queries/execute endpoint. <pre> { "statement": "SELECT * FROM \"peaka\".\"query\".\"samplequery\"", "bindArgs": ["arg1", "arg2"] } </pre>
    - `statement` string: The SQL statement to execute.
    - `bindings` object[]: Optional values for the statement's <code>?</code> placeholders, in order. Each is typed by its JSON type: a string is a varchar, a whole number a bigint, a decimal a DECIMAL, <code>true</code>/<code>false</code> a boolean, <code>null</code> a NULL. For example <code>&quot;statement&quot;: &quot;SELECT 1 + ?&quot;, &quot;bindings&quot;: [4]</code> returns 5, and <code>[&quot;usd&quot;]</code> binds a string. For other types, cast in the statement, e.g. <code>CAST(? AS date)</code> with <code>[&quot;2026-09-30&quot;]</code>.
    - `timeout` integer: Query timeout in seconds. A query that runs longer is stopped and the request fails with error code 102. Omitted or 0: no limit. Negative values are rejected.

## Response `200`

Query Result

---

[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)