Translate natural language to SQL

POST

/queries/translate

Production API

Convert a natural language query to DataFusion SQL.

Features:

Understands table schemas and column types
Supports semantic/vector search via knn_* functions and text_to_embedding
Validates generated SQL syntax (optional)
Returns confidence level and explanations

Request Body:

tables: Map of table aliases (as used in SQL) to table IDs
query: Natural language query to translate
includeExplanation: Include explanation of generated SQL (default: false)
validateSyntax: Validate SQL syntax before returning (default: true)

Example Request:

{
  "tables": {
    "orders": "tbl_abc123",
    "customers": "tbl_def456"
  },
  "query": "Find customers who placed orders over $1000 last month",
  "includeExplanation": true
}

Phase 1 Constraint: All tables must belong to the same team.

Authorizations

bearerAuth
cookieAuth

Request Body

object

tables

required

Map of table aliases (as used in SQL) to table IDs

object

key

additional properties

string

query

required

Natural language query to translate

string

>= 1 characters <= 4000 characters

includeExplanation

Include explanation of the generated SQL

boolean

validateSyntax

Validate SQL syntax via EXPLAIN before returning

boolean

default: true

Responses

200

Translation successful

object

sql

required

Generated DataFusion SQL query

string

explanation

Explanation of the generated SQL (if requested)

string

warnings

required

Warnings or assumptions made during translation

Array<string>

referencedTables

required

Table aliases referenced in the SQL

Array<string>

referencedColumns

required

Columns referenced in the SQL (format: table.column)

Array<string>

usesVectorSearch

required

Whether the query uses vector search functions

boolean

confidence

required

Confidence level of the translation

string

Allowed values: high medium low

400

Bad request - invalid input or translation failed

object

error

required

Error message

string

code

required

Error code

string

Allowed values: TABLES_NOT_FOUND TRANSLATION_FAILED VALIDATION_FAILED INVALID_REQUEST

401

Unauthorized - Authentication required or invalid token

object

error

required

string

code

string

details

nullable

retryable

boolean

402

Payment required - insufficient credits

403

Forbidden - Insufficient permissions

object

error

required

string

code

string

details

nullable

retryable

boolean

404

One or more dataset tables not found

object

error

required

Error message

string

code

required

Error code

string

Allowed values: TABLES_NOT_FOUND TRANSLATION_FAILED VALIDATION_FAILED INVALID_REQUEST