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

# SQL Query

> Execute a SQL query on the organization's data warehouse and return presigned URLs to download results.

This endpoint executes SQL queries on the organization's data warehouse (AWS Athena or GCP BigQuery)
and returns presigned URLs for downloading the results directly from cloud storage (S3 or GCS).

**Important**: Customer data never transits through Nekt servers. Results are stored in the
organization's cloud storage and accessed via time-limited presigned URLs (1 hour expiration).

**Requirements**:
- Organization must have completed cloud setup (`cloud_setup_completed = True`)

**Cloud Provider Support**:
- AWS: Executes queries on Athena
- GCP: Executes queries on BigQuery

**Output Formats**:
- `csv`: CSV format (default) - supports simple data types only
- `parquet`: Parquet format - supports all data types including complex types (arrays, structs, etc.)

**Limitations**:
- BigQuery CSV export does not support complex data types (ARRAY, STRUCT, JSON). Use Parquet mode instead.
- Athena UNLOAD for Parquet may not support certain timestamp types. Cast problematic columns in the SQL query.

**Example Request**:
```json
{
    "sql": "SELECT * FROM my_table LIMIT 100",
    "mode": "parquet",
    "mode_options": {"compression": "SNAPPY"}
}
```

**Example Response**:
```json
{
    "state": "SUCCEEDED",
    "presigned_urls": [
        "https://storage.googleapis.com/bucket/query-20251119-154427-123456-000000000000.parquet?..."
    ],
    "data_scanned_in_bytes": 11250,
    "execution_time_in_millis": 408
}
```

<Info>
  **Security**: Your data never transits through Nekt servers. Results are stored in your organization's cloud storage and accessed via time-limited presigned URLs (1 hour expiration).
</Info>


## OpenAPI

````yaml POST /api/v1/sql-query/
openapi: 3.0.3
info:
  title: Nekt API
  version: v1
  description: Nekt API Documentation
  contact:
    email: support@nekt.ai
servers:
  - url: https://api.nekt.ai
security: []
paths:
  /api/v1/sql-query/:
    post:
      tags:
        - Explorer
      description: >-
        Execute a SQL query on the organization's data warehouse and return
        presigned URLs to download results.


        This endpoint executes SQL queries on the organization's data warehouse
        (AWS Athena or GCP BigQuery)

        and returns presigned URLs for downloading the results directly from
        cloud storage (S3 or GCS).


        **Important**: Customer data never transits through Nekt servers.
        Results are stored in the

        organization's cloud storage and accessed via time-limited presigned
        URLs (1 hour expiration).


        **Requirements**:

        - Organization must have completed cloud setup (`cloud_setup_completed =
        True`)


        **Cloud Provider Support**:

        - AWS: Executes queries on Athena

        - GCP: Executes queries on BigQuery


        **Output Formats**:

        - `csv`: CSV format (default) - supports simple data types only

        - `parquet`: Parquet format - supports all data types including complex
        types (arrays, structs, etc.)


        **Limitations**:

        - BigQuery CSV export does not support complex data types (ARRAY,
        STRUCT, JSON). Use Parquet mode instead.

        - Athena UNLOAD for Parquet may not support certain timestamp types.
        Cast problematic columns in the SQL query.


        **Example Request**:

        ```json

        {
            "sql": "SELECT * FROM my_table LIMIT 100",
            "mode": "parquet",
            "mode_options": {"compression": "SNAPPY"}
        }

        ```


        **Example Response**:

        ```json

        {
            "state": "SUCCEEDED",
            "presigned_urls": [
                "https://storage.googleapis.com/bucket/query-20251119-154427-123456-000000000000.parquet?..."
            ],
            "data_scanned_in_bytes": 11250,
            "execution_time_in_millis": 408
        }

        ```
      operationId: v1_sql_query_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSQLQueryRequest'
            examples:
              BasicCSVQuery:
                value:
                  sql: SELECT * FROM "nekt_raw"."customers" LIMIT 100
                summary: Basic CSV Query
                description: Simple query returning results in CSV format (default)
              ParquetQueryWithCompression:
                value:
                  sql: >-
                    SELECT id, name, created_at FROM "nekt_raw"."orders" WHERE
                    status = 'completed'
                  mode: parquet
                  mode_options:
                    compression: SNAPPY
                summary: Parquet Query with Compression
                description: Query with Parquet format and SNAPPY compression
              AWSTimestampHandling:
                value:
                  sql: >-
                    SELECT id, name, CAST(created_at AS TIMESTAMP) AS
                    created_at, CAST(updated_at AS TIMESTAMP) AS updated_at FROM
                    "nekt_raw"."products"
                  mode: parquet
                summary: AWS Timestamp Handling
                description: >-
                  Query with explicit timestamp casting for AWS Athena
                  compatibility
              GCPCSVWithCustomOptions:
                value:
                  sql: >-
                    SELECT * FROM "nekt_raw"."transactions" WHERE date >=
                    '2025-01-01'
                  mode: csv
                  mode_options:
                    delimiter: ;
                    header: true
                    compression: GZIP
                summary: GCP CSV with Custom Options
                description: >-
                  CSV query with custom delimiter and compression for GCP
                  BigQuery
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DataSQLQueryRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DataSQLQueryRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSQLQueryResponse'
              examples:
                SuccessfulResponse:
                  value:
                    state: SUCCEEDED
                    presigned_urls:
                      - >-
                        https://storage.googleapis.com/bucket/query-20251119-154427-123456-000000000000.parquet?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...
                    data_scanned_in_bytes: 11250
                    execution_time_in_millis: 408
                  summary: Successful Response
                  description: Successful query execution with presigned download URLs
                FailedQueryResponse:
                  value:
                    state: FAILED
                    state_change_reason: >-
                      Syntax error: Expected end of input but got identifier
                      'FORM' at line 1, column 15
                  summary: Failed Query Response
                  description: Query execution failed due to SQL syntax error
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    DataSQLQueryRequest:
      type: object
      description: Serializer for SQL query execution request.
      properties:
        sql:
          type: string
          description: >-
            SQL query string to execute using standard SQL syntax (AWS Athena or
            GCP BigQuery depending on your organization's cloud provider)
        mode:
          allOf:
            - $ref: '#/components/schemas/ModeEnum'
          default: csv
          description: >-
            Output format for query results. Options: 'csv' (default, universal
            compatibility) or 'parquet' (better compression and performance,
            recommended for large datasets)


            * `csv` - csv

            * `parquet` - parquet
        mode_options:
          type: object
          additionalProperties: {}
          description: >-
            Additional options for the output format. Available options depend
            on your organization's cloud provider and selected mode:


            **AWS Organizations:**

            - CSV mode: No options supported (AWS Athena limitation)

            - Parquet mode: 'compression' - Compression algorithm (default:
            'SNAPPY', options: 'SNAPPY', 'GZIP', 'NONE')


            **GCP Organizations:**

            - CSV mode: 'delimiter' (default: ','), 'header' (default: true),
            'compression' (optional: 'GZIP')

            - Parquet mode: 'compression' - Compression algorithm (default:
            'SNAPPY', options: 'SNAPPY', 'GZIP', 'NONE')


            Example: {'compression': 'SNAPPY'} or {'delimiter': ';', 'header':
            true, 'compression': 'GZIP'}
      required:
        - sql
    DataSQLQueryResponse:
      type: object
      description: Serializer for SQL query execution response.
      properties:
        state:
          allOf:
            - $ref: '#/components/schemas/StateEnum'
          description: |-
            Query execution state

            * `SUCCEEDED` - SUCCEEDED
            * `FAILED` - FAILED
            * `CANCELLED` - CANCELLED
            * `RUNNING` - RUNNING
        presigned_urls:
          type: array
          items:
            type: string
            format: uri
          description: List of presigned URLs to download result files (1 hour expiration)
        data_scanned_in_bytes:
          type: integer
          description: Amount of data scanned by the query (if succeeded)
        execution_time_in_millis:
          type: integer
          description: Query execution time in milliseconds (if succeeded)
        state_change_reason:
          type: string
          description: Error message (if failed)
      required:
        - state
    ModeEnum:
      enum:
        - csv
        - parquet
      type: string
      description: |-
        * `csv` - csv
        * `parquet` - parquet
    StateEnum:
      enum:
        - SUCCEEDED
        - FAILED
        - CANCELLED
        - RUNNING
      type: string
      description: |-
        * `SUCCEEDED` - SUCCEEDED
        * `FAILED` - FAILED
        * `CANCELLED` - CANCELLED
        * `RUNNING` - RUNNING
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key authentication. Format: ''x-api-key: api_key'''

````