> ## Documentation Index
> Fetch the complete documentation index at: https://domoinc-bradley-turek-pfilter-operators-reference.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Text-to-SQL
> Generate a SQL query based on the given text input and data source schema.
## OpenAPI
````yaml /openapi/product/AI-Services.yaml post /api/ai/v1/text/sql
openapi: 3.1.0
info:
title: AI Services
description: >-
Domo AI Services provide a consistent API to leverage Foundation Models to
solve common problems such as natural language SQL generation (text-to-SQL),
Summarization, Classification, Tool Calling and others.
version: 2.3.3639_master
servers:
- url: https://{subdomain}.domo.com
variables:
subdomain:
description: The Domo instance subdomain.
default: subdomain
security: []
tags:
- name: AI Services - Classification
description: Domo AI Service Classification APIs
- name: AI Services - Data Extraction
description: Domo AI Service Data Extraction APIs
- name: AI Services - Embedding
description: Domo AI Service Embedding APIs
- name: AI Services - Image
description: Domo AI Service Image APIs
- name: AI Services - Messages
description: Domo AI Service Messages APIs
- name: AI Services - Sentiment Analysis
description: Domo AI Service Sentiment Analysis APIs
- name: AI Services - Text
description: Domo AI Service Text APIs
paths:
/api/ai/v1/text/sql:
post:
tags:
- AI Services - Text
summary: Text-to-SQL
description: >-
Generate a SQL query based on the given text input and data source
schema.
operationId: textToSQL
requestBody:
description: Text to SQL AI Service request.
content:
application/json:
schema:
$ref: '#/components/schemas/TextToSQLRequest'
examples:
Basic:
description: Basic Text-to-SQL request.
value:
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
Non-default model:
description: Text-to-SQL request with non-default model.
value:
input: What are my total sales by region?
model: 9f35cc70-47f0-46da-a3e9-92a76c574e41
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
required: true
responses:
'200':
description: >-
TextAIResponse The generated SQL query and model token usage
information.
content:
application/json:
schema:
$ref: '#/components/schemas/TextAIResponse'
examples:
Text-to-SQL Response:
description: Text-to-SQL Response
value:
prompt: >-
# MYSQL
[{"dataSourceName":"Store_Sales","columns":[{"name":"product","type":"STRING"},{"name":"store","type":"LONG"},{"name":"amount","type":"LONG"},{"name":"timestamp","type":"DATETIME"},{"name":"region","type":"STRING"}]}]
# Generate a query to answer the following:
# 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
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
'409':
description: Conflict
security:
- domo-developer-token: []
components:
schemas:
TextToSQLRequest:
type: object
description: |-
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}"
properties:
input:
type: string
description: The input text.
sessionId:
type: string
format: uuid
description: >-
The AI session ID. If provided, this request will be associated with
the specified AI Session.
dataSourceSchemas:
type: array
description: >-
The data source schemas and metadata to be included in the
Text-to-SQL task prompt to generate SQL.
items:
$ref: '#/components/schemas/AIDataSourceSchema'
promptTemplate:
$ref: '#/components/schemas/ParameterizedPromptTemplate'
description: >-
The prompt template to use for the Text-to-SQL task. The default
prompt template will be used if not
provided.
parameters:
type: object
additionalProperties:
type: string
description: >-
Custom parameters to inject into the prompt template if an
associated placeholder is present.
model:
type: string
description: >-
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:
type: object
additionalProperties: {}
description: >-
Additional model-specific configuration parameter key-value pairs.
e.g. temperature, max_tokens, etc.
dialect:
type: string
description: >-
The SQL dialect to use in the Text-to-SQL task prompt. Defaults to
MYSQL.
commentToken:
type: string
description: >-
The comment token to use in the Text-to-SQL task prompt. Defaults to
"#".
escapeChar:
type: string
description: >-
The escape character to use in the Text-to-SQL task prompt. Defaults
to "`".
system:
type: string
description: >-
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:
type: boolean
description: >-
Whether the generated SQL should be compatible with Domo's query
engine. Defaults to true.
sqlRequestOptions:
type: array
description: >-
Optional SQL request options to control the behavior of the
Text-to-SQL AI Service.
items:
type: string
enum:
- 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
uniqueItems: true
temperature:
type: number
format: double
description: >-
Controls randomness in the model's output. Lower values make output
more deterministic.
maximum: 2
minimum: 0
maxTokens:
type: integer
format: int32
description: The maximum number of tokens to generate in the response.
reasoningConfig:
$ref: '#/components/schemas/ReasoningConfig'
description: Configuration for reasoning behavior and effort level.
required:
- input
TextAIResponse:
type: object
description: Response from a text AI Service.
properties:
prompt:
type: string
description: The formatted prompt that was used to generate the response.
choices:
type: array
deprecated: true
description: The list of choices generated by the model.
items:
$ref: '#/components/schemas/Choice'
modelId:
type: string
description: The id of the model used to generate the response.
sessionId:
type: string
format: uuid
description: The id of the AI Session associated with this request.
output:
type: string
description: The output of the model.
modelProviderUsage:
$ref: '#/components/schemas/ModelProviderUsage'
description: The token usage from the model provider.
AIDataSourceSchema:
type: object
description: The schema and additional metadata for a Data Source.
properties:
dataSourceId:
type: string
description: The unique identifier for the data source.
dataSourceName:
type: string
description: The name of the data source.
description:
type: string
description: A description of the data source.
columns:
type: array
description: The columns in the data source.
items:
oneOf:
- $ref: '#/components/schemas/AISchemaColumn'
- $ref: '#/components/schemas/AISchemaCalculation'
ParameterizedPromptTemplate:
type: object
description: |-
A prompt template string that contains placeholders for parameters that will be replaced with parameter values before the prompt
is submitted to the model.
Prompt Template Examples
- "${input}"
- "${system}\n${input}"
properties:
template:
type: string
ReasoningConfig:
type: object
properties:
reasoningEffort:
type: string
enum:
- NONE
- LOW
- MEDIUM
- HIGH
Choice:
type: object
description: A choice generated by a text AI model.
properties:
output:
type: string
description: The text model output.
ModelProviderUsage:
type: object
properties:
inputTokens:
type: integer
format: int64
outputTokens:
type: integer
format: int64
totalTokens:
type: integer
format: int64
reasoningTokens:
type: integer
format: int64
AISchemaColumn:
type: object
description: Data source column metadata.
properties:
name:
type: string
description: The name of the column.
minLength: 1
type:
type: string
description: The type of data in the column.
minLength: 1
displayName:
type: string
description: The column display name.
description:
type: string
description: The column description.
validValues:
type: array
deprecated: true
description: Possible values for the column if only certain values are allowed.
items:
deprecated: true
uniqueItems: true
defaultValue:
description: The default value for the column.
synonyms:
type: array
description: Synonyms for the column name.
items:
type: string
uniqueItems: true
classification:
type: string
description: The classification for the data in the column.
defaultAggregation:
type: string
description: The default aggregation for the column.
required:
- name
- type
AISchemaCalculation:
allOf:
- $ref: '#/components/schemas/AISchemaColumn'
- type: object
properties:
templateId:
type: integer
format: int64
description: The function template ID.
formula:
type: string
description: The formula for the calculation.
aggregatable:
type: boolean
description: Whether the calculation is able to be aggregated.
legacyId:
type: string
description: The function template legacy ID.
description: Data source column metadata for a calculation.
required:
- name
- type
securitySchemes:
domo-developer-token:
type: apiKey
name: X-DOMO-Developer-Token
in: header
````