MyScale Query API

openapi: 3.0.1
info:
  title: MyScale SQL (ClickHouse HTTP) Interface Query API
  description: MyScale is a SQL vector database built on a ClickHouse fork (MyScaleDB). Its primary programmatic interface is SQL executed over the ClickHouse-compatible HTTP interface, exposed per cluster on HTTPS port 8443. A client sends a SQL statement (SELECT, INSERT, CREATE TABLE, ALTER, DROP) and authenticates with the cluster username and password via HTTP Basic auth or the X-ClickHouse-User and X-ClickHouse-Key headers. Vector similarity search is expressed in SQL using a VECTOR INDEX column and the distance() function rather than a separate REST surface. This OpenAPI document models that HTTP query interface. The underlying MyScaleDB engine is open source under Apache-2.0; cluster lifecycle management is performed through the MyScale Cloud web console and has no documented public REST management API.
  termsOfService: https://myscale.com/terms/
  contact:
    name: MyScale Support
    url: https://docs.myscale.com/en/
  license:
    name: Apache 2.0 (MyScaleDB engine)
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '1.0'
servers:
- url: https://{clusterHost}:8443
  description: Per-cluster ClickHouse-compatible HTTP endpoint (HTTPS).
  variables:
    clusterHost:
      default: your-cluster-host.aws.myscale.com
      description: Cluster host from the MyScale Cloud console Connection Details (MYSCALE_CLUSTER_URL).
security:
- basicAuth: []
- clickhouseUserHeader: []
  clickhouseKeyHeader: []
tags:
- name: Query
paths:
  /:
    get:
      operationId: ping
      tags:
      - Query
      summary: Health / ping check.
      description: A GET to the root of the HTTP interface returns a simple "Ok." body when the server is reachable, used as a liveness check.
      responses:
        '200':
          description: Server is reachable.
          content:
            text/plain:
              schema:
                type: string
                example: 'Ok.

                  '
    post:
      operationId: query
      tags:
      - Query
      summary: Execute a SQL statement over HTTP.
      description: Executes an arbitrary SQL statement against the cluster. The SQL is sent as the raw request body (text/plain). This single endpoint covers all DDL and DML - SELECT, INSERT, CREATE TABLE (including VECTOR INDEX definitions), ALTER, and DROP - exactly as the ClickHouse HTTP interface behaves. Vector search is performed by issuing a SELECT that orders rows by the distance() function. Results may be requested in formats such as JSON, JSONEachRow, CSV, or TabSeparated via the default_format setting or a FORMAT clause.
      parameters:
      - name: query
        in: query
        required: false
        description: SQL statement, when supplied as a query-string parameter instead of the request body. Body and query parameter may be combined (e.g. DDL in query, data in body for INSERT).
        schema:
          type: string
      - name: database
        in: query
        required: false
        description: Default database for the statement.
        schema:
          type: string
          default: default
      - name: default_format
        in: query
        required: false
        description: Output format when the SQL does not include a FORMAT clause (e.g. JSON, JSONEachRow, CSV, TabSeparated).
        schema:
          type: string
          example: JSON
      requestBody:
        required: false
        description: Raw SQL statement.
        content:
          text/plain:
            schema:
              type: string
            examples:
              createVectorTable:
                summary: Create a table with a vector index
                value: "CREATE TABLE IF NOT EXISTS default.articles\n(\n    id UInt64,\n    title String,\n    content_vector Array(Float32),\n    CONSTRAINT cons_vec_len CHECK length(content_vector) = 768,\n    VECTOR INDEX article_idx content_vector TYPE HNSWFLAT('metric_type=Cosine')\n)\nENGINE = MergeTree ORDER BY id\n"
              vectorSearch:
                summary: Vector similarity search with distance()
                value: 'SELECT id, title, distance(content_vector, [0.1, 0.2, 0.3]) AS dist

                  FROM default.articles

                  ORDER BY dist ASC

                  LIMIT 10

                  '
      responses:
        '200':
          description: Statement executed successfully. The body contains the result set in the requested format (empty for statements that return no rows).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
            text/plain:
              schema:
                type: string
            text/tab-separated-values:
              schema:
                type: string
        '400':
          description: SQL parse or execution error.
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Authentication failed (bad username or password).
          content:
            text/plain:
              schema:
                type: string
        '403':
          description: User not authorized for the requested operation.
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    QueryResult:
      type: object
      description: Result of a SELECT returned in the ClickHouse JSON format. Shape varies with the query; the common envelope includes meta, data, rows, and statistics.
      properties:
        meta:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
        data:
          type: array
          items:
            type: object
            additionalProperties: true
        rows:
          type: integer
        statistics:
          type: object
          properties:
            elapsed:
              type: number
            rows_read:
              type: integer
            bytes_read:
              type: integer
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Cluster username and password (from the MyScale Cloud console Connection Details) supplied as HTTP Basic credentials.
    clickhouseUserHeader:
      type: apiKey
      in: header
      name: X-ClickHouse-User
      description: Cluster username, paired with X-ClickHouse-Key.
    clickhouseKeyHeader:
      type: apiKey
      in: header
      name: X-ClickHouse-Key
      description: Cluster password, paired with X-ClickHouse-User.