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:

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

Example Response:

{
    "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
}