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

# DuckDB

> Execute SQL queries against the oleander lake using DuckDB. All queries automatically capture lineage metadata for complete observability. This endpoint is only available on the Pro plan.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/warehouse/query
openapi: 3.0.1
info:
  title: Oleander API
  description: >-
    Oleander implements the api spec as defined by OpenLineage to ingest data.
    We also provide a RESTful API to extract data within our system.
  version: 1.0.0
servers:
  - url: https://oleander.dev
security:
  - bearerAuth: []
paths:
  /api/v1/warehouse/query:
    post:
      summary: DuckDB
      description: >-
        Execute SQL queries against the oleander lake using DuckDB. All queries
        automatically capture lineage metadata for complete observability. This
        endpoint is only available on the Pro plan.
      operationId: queryWarehouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: The SQL query to execute. Supports all DuckDB SQL syntax.
                  example: |-
                    WITH
                      src AS (
                        SELECT
                          *
                        FROM
                          read_json (
                            'https://api.tvmaze.com/search/shows?q=breaking+bad',
                            auto_detect = TRUE
                          )
                      )
                    SELECT
                      src -> 'show' ->> 'name' AS show_name,
                      src -> 'show' ->> 'premiered' AS premiered,
                      src -> 'show' -> 'rating' ->> 'average' AS rating,
                      src -> 'show' -> 'network' ->> 'name' AS network_name
                    FROM
                      src;
                autoSaveByHash:
                  type: boolean
                  description: >-
                    Automatically save query results to a table based on the
                    query hash. If a table with the same hash exists, returns
                    cached results instead of re-executing.
                  default: false
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '400':
          description: Invalid request (e.g. invalid SQL query).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: SQL syntax error
        '401':
          description: >-
            Unauthorized – request either lacks a valid Bearer token or session
            credentials.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '403':
          description: Forbidden – Pro plan required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: This endpoint requires a Pro plan subscription
        '500':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    QueryResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the query executed successfully
        results:
          type: object
          description: Query results with columns, column types, and rows
          properties:
            columns:
              type: array
              items:
                type: string
              description: Column names
            column_types:
              type: array
              items:
                type: string
              description: Column data types
            rows:
              type: array
              items:
                type: array
                items: {}
              description: Query results as an array of row arrays
          required:
            - columns
            - column_types
            - rows
        row_count:
          type: integer
          description: Number of rows returned
        execution_time:
          type: string
          description: Query execution time (e.g., '991ms')
        query:
          type: string
          description: The original SQL query that was executed
        explainResult:
          type: object
          description: Query execution plan explanation
        job:
          type: object
          description: Lineage job information
          properties:
            namespace:
              type: string
              description: Job namespace (typically 'oleander.lake')
            name:
              type: string
              description: Job name (query hash identifier)
          required:
            - namespace
            - name
      required:
        - success
        - results
        - row_count
        - execution_time
        - query
        - job
    Error:
      required:
        - status
      type: object
      properties:
        status:
          type: integer
          format: int32
          default: 500
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````