SingleStore Queries API

openapi: 3.1.0
info:
  title: SingleStore Data Files Queries API
  description: The SingleStore Data API enables developers to execute SQL statements against a SingleStore Helios database over standard HTTP connections without requiring a native database driver or MySQL-compatible client. It supports all SQL statements available through a direct database connection, returning results as JSON-encoded responses using standard HTTP methods and response codes. The API exposes endpoints for executing DDL and DML statements via /api/v2/exec and returning query result sets via /api/v2/query/rows and /api/v2/query/tuples. Authentication is handled using HTTP Basic or Bearer Authentication over HTTPS. The API supports up to 192 parallel requests per aggregator, making it suitable for serverless architectures and custom application integrations.
  version: v2
  contact:
    name: SingleStore Support
    url: https://support.singlestore.com
  termsOfService: https://www.singlestore.com/cloud-terms-and-conditions/
servers:
- url: https://{workspaceHost}
  description: SingleStore Helios workspace endpoint. Replace workspaceHost with the hostname of the target workspace obtained from the Cloud Portal or Management API.
  variables:
    workspaceHost:
      default: your-workspace.singlestore.com
      description: Hostname of the SingleStore Helios workspace to query. Obtain this value from the workspace endpoint field in the Cloud Portal or via the Management API.
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Queries
  description: Execute SQL statements against a SingleStore Helios workspace over HTTP. Supports DDL, DML, and SELECT statements returning results as JSON.
paths:
  /api/v2/exec:
    post:
      operationId: execSQL
      summary: Execute a Sql Statement
      description: Executes a DDL or DML SQL statement against the target workspace and database. Use this endpoint for statements that do not return result sets, such as CREATE TABLE, INSERT, UPDATE, DELETE, and DROP. The endpoint returns execution metadata including the number of rows affected. The request body must not exceed 1 MB in size.
      tags:
      - Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecRequest'
      responses:
        '200':
          description: SQL statement executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v2/query/rows:
    post:
      operationId: queryRows
      summary: Execute a Sql Query and Return Rows
      description: Executes a SQL SELECT statement against the target workspace and database, returning results as an array of JSON objects where each object represents one row with column names as keys. This format is convenient for most use cases but produces larger responses than the tuples format due to the repeated column name keys. The request body must not exceed 1 MB in size.
      tags:
      - Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Query executed successfully; results returned as row objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryRowsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v2/query/tuples:
    post:
      operationId: queryTuples
      summary: Execute a Sql Query and Return Tuples
      description: Executes a SQL SELECT statement against the target workspace and database, returning results as a separate columns array and a rows array of value arrays. This format offers better performance for queries with large result sets because column names are not repeated per row. Use this endpoint when response payload size is a concern.
      tags:
      - Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Query executed successfully; results returned as column/tuple arrays.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTuplesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: The request did not include valid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The SQL statement or request body was malformed or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: The SQL statement failed to execute due to a database or server-side error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ExecResponse:
      type: object
      description: Response returned after successfully executing a DDL or DML statement.
      properties:
        results:
          type: array
          description: Array of result metadata objects, one per statement executed.
          items:
            type: object
            properties:
              lastInsertId:
                type: integer
                description: Auto-increment ID of the last row inserted by an INSERT statement, if applicable.
              rowsAffected:
                type: integer
                description: Number of rows affected by the executed statement.
    Column:
      type: object
      description: Descriptor for a single column in a query result set.
      properties:
        name:
          type: string
          description: Name of the column as defined in the SQL query or table schema.
        dataType:
          type: string
          description: SingleStore data type of the column (e.g., INT, VARCHAR, DATETIME).
        nullable:
          type: boolean
          description: When true, the column may contain NULL values.
    ExecRequest:
      type: object
      description: Request body for executing a DDL or DML SQL statement that does not return a result set.
      required:
      - sql
      properties:
        sql:
          type: string
          description: The SQL statement to execute. Supports all DDL and DML statement types including CREATE, INSERT, UPDATE, DELETE, and DROP.
        database:
          type: string
          description: Name of the database to use when executing the statement. If not provided, the default database for the authenticated user is used.
        args:
          type: array
          description: Positional arguments for parameterized SQL statements. Use ? placeholders in the sql field and provide values in order here.
          items: {}
    QueryRowsResponse:
      type: object
      description: Response returned after a successful SELECT query using the rows format, where each result row is a JSON object with column names as keys.
      properties:
        results:
          type: array
          description: Array of result sets, one per statement in the request.
          items:
            type: object
            properties:
              rows:
                type: array
                description: Array of row objects where each object maps column names to their corresponding values for that row.
                items:
                  type: object
                  additionalProperties: true
    QueryRequest:
      type: object
      description: Request body for executing a SQL SELECT statement and returning a result set.
      required:
      - sql
      properties:
        sql:
          type: string
          description: The SQL SELECT statement to execute. Any valid SingleStore SQL SELECT syntax is supported.
        database:
          type: string
          description: Name of the database to query. If not provided, the default database for the authenticated user is used.
        args:
          type: array
          description: Positional arguments for parameterized SQL queries. Use ? placeholders in the sql field and provide values in order here.
          items: {}
    QueryTuplesResponse:
      type: object
      description: Response returned after a successful SELECT query using the tuples format, where columns are described once and rows are arrays of values.
      properties:
        results:
          type: array
          description: Array of result sets, one per statement in the request.
          items:
            type: object
            properties:
              columns:
                type: array
                description: Array of column descriptor objects defining the name and data type of each column in the result set.
                items:
                  $ref: '#/components/schemas/Column'
              rows:
                type: array
                description: Array of value arrays where each inner array contains the column values for one result row in the same order as the columns array.
                items:
                  type: array
                  items: {}
    Error:
      type: object
      description: Standard error response returned when a Data API request fails.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
        code:
          type: integer
          description: HTTP status code associated with the error.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using SingleStore database credentials. Provide the username and password as a Base-64 encoded username:password string in the Authorization header.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using a JWT token obtained from the SingleStore Cloud Portal.
externalDocs:
  description: SingleStore Data API Documentation
  url: https://docs.singlestore.com/cloud/reference/data-api/