Text-to-SQL

Generate a SQL query based on the given text input and data source schema.

POST /api/ai/v1/text/sql

cURL

Basic

curl --request POST \
  --url https://{subdomain}.domo.com/api/ai/v1/text/sql \
  --header 'Content-Type: application/json' \
  --header 'X-DOMO-Developer-Token: <api-key>' \
  --data '
{
  "input": "What are my total sales by region?",
  "dataSourceSchemas": [
    {
      "dataSourceName": "Store Sales",
      "columns": [
        {
          "type": "STRING",
          "name": "product"
        },
        {
          "type": "LONG",
          "name": "store"
        },
        {
          "type": "LONG",
          "name": "amount"
        },
        {
          "type": "DATETIME",
          "name": "timestamp"
        },
        {
          "type": "STRING",
          "name": "region"
        }
      ]
    }
  ]
}
'

200

{
  "prompt": "# MYSQL\n[{\"dataSourceName\":\"Store_Sales\",\"columns\":[{\"name\":\"product\",\"type\":\"STRING\"},{\"name\":\"store\",\"type\":\"LONG\"},{\"name\":\"amount\",\"type\":\"LONG\"},{\"name\":\"timestamp\",\"type\":\"DATETIME\"},{\"name\":\"region\",\"type\":\"STRING\"}]}]\n# Generate a query to answer the following:\n# What are my total sales by region?",
  "output": "SELECT region, SUM(amount) AS total_sales FROM `Store Sales` GROUP BY region",
  "modelId": "domo.domo_ai.domogpt-medium-v1.2:anthropic"
}

Authorizations

X-DOMO-Developer-Token · string · header · required

Body

application/json

Text to SQL AI Service request.

Text-to-SQL AI Service Request.

Prompt Templates

A prompt template is a string that contains placeholders for parameters that will be replaced with parameter values before the prompt is submitted to the model.

A default prompt template is set for each model configured for the Text-to-SQL AI Service. Individual requests can override the default template by including the promptTemplate parameter.

Prompt Template Parameters

The following request parameters are automatically injected into the prompt template if the associated placeholder is present:

• input
• system
• dataSourceSchemas
• dialect
• commentToken
• escapeChar

Models with built-in support for system prompts and chat message history do not need to include system or chatContext in the prompt template.

Additional parameters can be provided in the parameters map as key-value pairs.

Prompt Template Examples

• "${input}"
• "${system}\n${input}"

input · string · required

The input text.

sessionId · string<uuid>

The AI session ID. If provided, this request will be associated with the specified AI Session.

dataSourceSchemas · object[]

The data source schemas and metadata to be included in the Text-to-SQL task prompt to generate SQL.

Show child attributes

promptTemplate · object

The prompt template to use for the Text-to-SQL task. The default prompt template will be used if not provided.

Show child attributes

parameters · object

Custom parameters to inject into the prompt template if an associated placeholder is present.

Show child attributes

model · string

The ID of the model to use for Text-to-SQL. The specified model must be configured for the Text-to-SQL AI Service by an Admin.

modelConfiguration · object

Additional model-specific configuration parameter key-value pairs. e.g. temperature, max_tokens, etc.

Show child attributes

dialect · string

The SQL dialect to use in the Text-to-SQL task prompt. Defaults to MYSQL.

commentToken · string

The comment token to use in the Text-to-SQL task prompt. Defaults to "#".

escapeChar · string

The escape character to use in the Text-to-SQL task prompt. Defaults to "`".

system · string

The system message to use for the Text-to-SQL task. If not provided, the default system will be used. If the model does not include built-in support for system prompts, this parameter may be included in the prompt template using the "${system}" placeholder.

domoSupported · boolean

Whether the generated SQL should be compatible with Domo's query engine. Defaults to true.

sqlRequestOptions · enum<string>[]

Optional SQL request options to control the behavior of the Text-to-SQL AI Service.

Available options: EXPAND_SELECT_STAR, USE_DATA_SOURCE_ID_AS_TABLE_NAME, UNION_TO_UNION_ALL, DISALLOW_COMMON_TABLE_EXPRESSIONS, DISALLOW_JOINS, DISALLOW_SUBQUERIES, DISALLOW_UNIONS, VALIDATE_REFERENCES, VALIDATE_AGGREGATIONS, VALIDATE_FUNCTIONS

temperature · number<double>

Controls randomness in the model's output. Lower values make output more deterministic.

Required range: 0 <= x <= 2

maxTokens · integer<int32>

The maximum number of tokens to generate in the response.

reasoningConfig · object

Configuration for reasoning behavior and effort level.

Show child attributes

Response

200

application/json

TextAIResponse The generated SQL query and model token usage information.

Response from a text AI Service.

prompt · string

The formatted prompt that was used to generate the response.

choices · object[] · deprecated

The list of choices generated by the model.

Show child attributes

modelId · string

The id of the model used to generate the response.

sessionId · string<uuid>

The id of the AI Session associated with this request.

output · string

The output of the model.

modelProviderUsage · object

The token usage from the model provider.

Show child attributes