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
}

POST /api/v1/sql-query

cURL

cURL

curl --request POST \
  --url https://api.nekt.ai/api/v1/sql-query/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "sql": "<string>",
  "mode": "csv",
  "mode_options": {}
}
'

200

SuccessfulResponse

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

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).

Authorizations

x-api-key · string · header · required

API Key authentication. Format: 'x-api-key: api_key'

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Serializer for SQL query execution request.

sql · string · required

SQL query string to execute using standard SQL syntax (AWS Athena or GCP BigQuery depending on your organization's cloud provider)

mode · enum<string> · default: csv

Output format for query results. Options: 'csv' (default, universal compatibility) or 'parquet' (better compression and performance, recommended for large datasets)

• csv - csv
• parquet - parquet

Available options: csv, parquet

mode_options · object

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'}

Show child attributes

Response

200 - application/json

Serializer for SQL query execution response.

state · enum<string> · required

Query execution state

• SUCCEEDED - SUCCEEDED
• FAILED - FAILED
• CANCELLED - CANCELLED
• RUNNING - RUNNING

Available options: SUCCEEDED, FAILED, CANCELLED, RUNNING

presigned_urls · string<uri>[]

List of presigned URLs to download result files (1 hour expiration)

data_scanned_in_bytes · integer

Amount of data scanned by the query (if succeeded)

execution_time_in_millis · integer

Query execution time in milliseconds (if succeeded)

state_change_reason · string

Error message (if failed)