> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ondb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handler for SQL queries

> POST /query/sql
Body: { "sql": "SELECT ... FROM app::collection WHERE ..." }

The SQL query must use the "app::collection" format for table references,
which is equivalent to "schema.table" in standard SQL.



## OpenAPI

````yaml /openapi.yaml post /query/sql
openapi: 3.1.0
info:
  title: OnDB API
  description: Monetize anything
  license:
    name: ''
  version: 4.0.0
servers: []
security: []
tags:
  - name: Health
    description: Health check and system status
  - name: Applications
    description: Application management
  - name: Billing
    description: Billing information and usage
  - name: Pricing
    description: Pricing information and quotes
  - name: X402 Payment Protocol
    description: Payment verification and settlement
  - name: Data Storage
    description: Store data to Celestia blockchain
  - name: Data Query
    description: Query and retrieve data
  - name: Collections
    description: Collection management
  - name: Indexes
    description: Index management and relations
  - name: Retention
    description: Data retention policies
  - name: Materialized Views
    description: Materialized view management
  - name: Predefined Queries
    description: Create and execute predefined queries
  - name: View Query
    description: Query materialized view data
  - name: Wallet
    description: App wallet management
  - name: Tasks
    description: Task tracking and status
  - name: Transactions
    description: Transaction status
  - name: Authorization
    description: Authorization grant management
  - name: API Keys
    description: API key management
  - name: Encryption
    description: Encryption settings and configuration
  - name: Payout
    description: Payout settings and history
  - name: API Collections
    description: API collection management
paths:
  /query/sql:
    post:
      tags:
        - Data Query
      summary: Handler for SQL queries
      description: >-
        POST /query/sql

        Body: { "sql": "SELECT ... FROM app::collection WHERE ..." }


        The SQL query must use the "app::collection" format for table
        references,

        which is equivalent to "schema.table" in standard SQL.
      operationId: handle_sql_query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SqlQueryRequest'
        required: true
      responses:
        '200':
          description: SQL query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SqlQueryResponse'
        '400':
          description: Invalid SQL syntax
        '404':
          description: Collection not found
        '500':
          description: Internal server error
      security:
        - api_key: []
components:
  schemas:
    SqlQueryRequest:
      type: object
      description: SQL Query Request
      required:
        - sql
      properties:
        include_history:
          type: boolean
          description: >-
            Include all versions of records (history)

            - true: Return all versions of each record (append-only mode)

            - false (default): Return only latest version of each record
            (deduplicated by user-defined "id" field)
        sql:
          type: string
          description: >-
            SQL query string

            Format: SELECT ... FROM app::collection WHERE ...

            Example: "SELECT name, age FROM myapp::users WHERE age > 18 ORDER BY
            name LIMIT 10"
    SqlQueryResponse:
      type: object
      description: SQL Query Response
      required:
        - data
        - count
        - query
        - app_id
        - collection
      properties:
        app_id:
          type: string
          description: App ID extracted from query
        collection:
          type: string
          description: Collection name extracted from query
        count:
          type: integer
          description: Number of results returned
          minimum: 0
        data:
          type: array
          items: {}
          description: Query results
        query:
          type: string
          description: SQL query that was executed

````