## OpenAPI
````yaml post /data/projects/{projectId}/queries/execute
openapi: 3.0.1
info:
title: Peaka Gateway API
description: Peaka Gateway API Documentation
version: '1.0'
servers:
- url: https://partner.peaka.studio/api/v1
description: Default Server URL (US Zone)
- url: https://partner.eu.peaka.studio/api/v1
description: EU Zone
security:
- bearerAuth: []
paths:
/data/projects/{projectId}/queries/execute:
post:
tags:
- Data -- Queries
summary: Execute Query
description: >
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. |
operationId: executeQuery
parameters:
- name: projectId
in: path
description: ID of the Project
required: true
schema:
type: string
example: mtKDhe1U
- name: format
in: query
description: 'Response format: CELL_TYPED (default), SIMPLE, or COMPACT'
required: false
schema:
type: string
default: CELL_TYPED
enum:
- CELL_TYPED
- SIMPLE
- COMPACT
example: SIMPLE
requestBody:
description: Execute Query Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/QueryExecuteRequest'
- $ref: '#/components/schemas/QueryExecuteRequestId'
- $ref: '#/components/schemas/QueryExecuteRequestName'
- $ref: '#/components/schemas/QueryExecuteRequestStatement'
examples:
Execute by Query Builder:
description: Execute by Query Builder
value:
from:
- catalogName: peaka
schemaName: query
tableName: samplequery
Execute by Query Builder with Limit:
description: Execute by Query Builder with Limit
value:
columns:
- amount
from:
- catalogName: peaka
schemaName: query
tableName: samplequery
filters: null
limit: 3
offset: 0
orderBy: null
Execute by Query Builder with Filter and Order By:
description: Execute by Query Builder with Filter and Order By
value:
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
Execute by Query ID:
description: Execute by Query ID
value:
id: '709922802836177297'
Execute by Query Name:
description: Execute by Query Name
value:
qualifiedName: peaka.query.samplequery
Execute by SQL Statement:
description: Execute by SQL Statement
value:
statement: SELECT * FROM "peaka"."query"."samplequery"
required: true
responses:
'200':
description: Query Result
content:
application/json:
examples:
CELL_TYPED (default):
description: CELL_TYPED (default)
value:
columns:
- catalogName: peaka
schemaName: query
tableName: samplequery
columnName: event
- catalogName: peaka
schemaName: query
tableName: samplequery
columnName: distinct_id
data:
- - name: event
displayName: event
dataType: varchar
order: 0
value: $mp_web_page_view
- name: distinct_id
displayName: distinct_id
dataType: varchar
order: 1
value: $device:916806fd-8a6c-425b-b5f9-b76b5d6f9d55
SIMPLE:
description: SIMPLE
value:
columns:
- catalogName: peaka
schemaName: query
tableName: samplequery
columnName: event
- catalogName: peaka
schemaName: query
tableName: samplequery
columnName: distinct_id
data:
- event: $mp_web_page_view
distinct_id: $device:916806fd-8a6c-425b-b5f9-b76b5d6f9d55
COMPACT:
description: COMPACT
value:
columns:
- catalogName: peaka
schemaName: query
tableName: samplequery
columnName: event
- catalogName: peaka
schemaName: query
tableName: samplequery
columnName: distinct_id
data:
- - $mp_web_page_view
- $device:916806fd-8a6c-425b-b5f9-b76b5d6f9d55
components:
schemas:
QueryExecuteRequest:
type: object
properties:
columns:
type: array
description: >-
Columns to select. If omitted, all columns (*) are
returned.
items:
type: string
from:
type: array
description: Tables to query from. At least one entry is required.
items:
$ref: '#/components/schemas/TableForQuery'
limit:
type: integer
description: Maximum number of rows to return.
format: int64
offset:
type: integer
description: Number of rows to skip before returning results.
format: int64
orderBy:
type: array
description: >-
Ordering specifications. Each entry is a column name optionally
followed by ASC or DESC.
Example: ["amount DESC", "created_at ASC"].
items:
type: string
filters:
type: object
additionalProperties: true
description: >-
Filter conditions. Supports and/or logic
with column comparisons.
timeout:
type: integer
description: Query timeout in seconds.
format: int32
description: >-
Executes a query using the query builder. The from field is
required.
Minimal example:
{
"from": [
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery"
}
]
}
With columns, filters, limit, offset, and orderBy:
{
"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"]
}
QueryExecuteRequestId:
type: object
properties:
id:
type: string
description: The ID of the query to execute.
timeout:
type: integer
description: Query timeout in seconds.
format: int32
description: |-
Executes a query by its ID.
{
"id": "709922802836177297"
}
QueryExecuteRequestName:
type: object
properties:
qualifiedName:
type: string
description: |-
Fully qualified name of the query, e.g.
peaka.query.samplequery or
peaka.mtquery.samplequery or
stripe.payment.charges
timeout:
type: integer
description: Query timeout in seconds.
format: int32
description: >-
Executes a query by its fully qualified name in the format
<catalogName>.<schemaName>.<tableName>.
{"qualifiedName": "peaka.query.samplequery"}
QueryExecuteRequestStatement:
type: object
properties:
statement:
type: string
description: The SQL statement to execute.
bindings:
type: array
description: Optional bind arguments for parameterised queries.
items:
type: string
timeout:
type: integer
description: Query timeout in seconds.
format: int32
description: |-
Executes a raw SQL statement directly via the queries/execute endpoint.
{
"statement": "SELECT * FROM \"peaka\".\"query\".\"samplequery\"",
"bindArgs": ["arg1", "arg2"]
}
TableForQuery:
type: object
properties:
catalogId:
type: string
catalogName:
type: string
schemaName:
type: string
tableName:
type: string
securitySchemes:
bearerAuth:
type: http
description: >-
Use the Authorization header with the value 'Bearer