openapi: 3.0.0
info:
  title: RisingWave Events Sql API
  version: '1.0'
  description: HTTP API for real-time event ingestion and SQL query execution against a running RisingWave instance. Supports inserting events into streaming tables and running PostgreSQL-compatible SQL queries.
  contact:
    name: RisingWave Labs
    url: https://risingwave.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: /v1
  description: Base API path
tags:
- name: Sql
paths:
  /sql:
    post:
      summary: Execute a SQL query
      operationId: executeSQL
      description: Execute a PostgreSQL-compatible SQL statement against the connected RisingWave instance and return the result set.
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: SQL query to be executed
            example: SELECT * FROM page_views LIMIT 10;
      responses:
        '200':
          description: SQL query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              example:
                columns:
                - name: user_id
                  type: VARCHAR
                  isPrimaryKey: false
                  isHidden: false
                - name: event_type
                  type: VARCHAR
                  isPrimaryKey: false
                  isHidden: false
                - name: url
                  type: VARCHAR
                  isPrimaryKey: false
                  isHidden: false
                - name: ts
                  type: BIGINT
                  isPrimaryKey: false
                  isHidden: false
                rows:
                - user_id: u-42
                  event_type: page_view
                  url: /docs/intro
                  ts: 1717200000000
                rowsAffected: 1
        '400':
          description: Bad request — invalid SQL syntax
        '500':
          description: Internal server error
      tags:
      - Sql
components:
  schemas:
    Column:
      type: object
      required:
      - name
      - type
      - isPrimaryKey
      - isHidden
      properties:
        name:
          type: string
          description: Name of the column
        type:
          type: string
          description: Data type of the column (e.g. VARCHAR, BIGINT, BOOLEAN)
        isPrimaryKey:
          type: boolean
          description: Whether the column is a primary key
        isHidden:
          type: boolean
          description: Whether the column is hidden from standard queries
    QueryResponse:
      type: object
      required:
      - columns
      - rows
      - rowsAffected
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/Column'
          description: Ordered list of columns in the result set
        rows:
          type: array
          items:
            type: object
            description: A single result row. Keys are column names; values are the corresponding typed column values.
          description: Result rows
        rowsAffected:
          type: integer
          format: int32
          description: Number of rows affected or returned by the query
        error:
          type: string
          description: Error message if the query failed; absent on success
externalDocs:
  description: RisingWave Documentation
  url: https://docs.risingwave.com