Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions
This Skill is used for: Generating SQL query statements through natural language, supporting multi-topic database configuration and table structure management
Capabilities include: Database configuration, topic management, table structure reading, natural language to SQL
Trigger conditions: User needs to configure Text-to-SQL database, create data topics, select data tables, or generate SQL with natural language questions
Prerequisites
Dependency Description
Required packages and versions for scripts:
text
pyyaml>=6.0
sqlalchemy>=2.0.0
API Service Description
This Skill generates SQL through the HTTP API /api/sql_for_skill/ endpoint:
Default API address: https://asksql.ai/
Service needs to be started before calling
Supports custom API address (via --api-url parameter)
API Interface Specification:
Endpoint path: POST /api/sql_for_skill/
Request format: multipart/form-data
Request parameters:
question: User's natural language question (string)
yaml_file: YAML configuration file (uploaded as file)
Response format: JSON array
Response example:
json
[
{
"STATUS": "ok",
"MESSAGE": "",
"SQL": "SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026",
"SQL_NO_PERM": "SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026",
"QUESTION": "This year's total sales"
}
]
Return value: Extract the SQL field from the first element of the response array
Data Configuration Methods
Two Configuration Methods Explained
When the agent guides users through data configuration, it must clearly explain the following two methods:
File naming: Excel filename must match database name (e.g., products.xlsx for products database)
Sheet naming: Each sheet name must exactly match the table name (e.g., orders sheet for orders table)
First row: Must contain column names (field names), cannot be empty
Second row onwards: Actual data rows (optional, used for understanding data types)
The agent should clearly recommend users to prioritize the database URL configuration method. Only use the Excel file method when users cannot provide a database connection.
Method 1: Database URL Configuration
Configuration Steps
Guide the user to provide database connection information
Call the configuration script to save database information:
Note: For MySQL connections, the system automatically converts mysql:// to mysql+pymysql:// for better compatibility. You can also explicitly specify the driver.
Reading Table Structure
After configuration, use the following command to read table structure:
This script generates table_info.json (table name list) and column_info.json (table structure information) files.
Agent reads table list fromtable_info.jsonfile, displays all tables to user completely, provides clear table descriptions
Key emphasis: Table selection is a critical step in topic creation, directly affects SQL generation accuracy and query effectiveness, must be autonomously selected by user based on actual business needs
Ask user: "Please tell me the topic name you want to create (e.g., sales topic, human resources topic)"
Agent is strictly prohibited from selecting tables for topics itself, must require user to explicitly specify needed tables
Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user
Ask user: "Do you want to continue creating other topics?"
User can repeat to create multiple topics (no need to re-read table structure, use existing ./output/column_info.json directly)
2.3 Agent Guidance Recommendations
Agent is prohibited from making assumptions or guessing user intent
Agent must mandatorily guide user to set up topics, cannot allow skipping
Agent is strictly prohibited from setting topics or selecting tables for topics itself, must display all table lists to user after reading table structure, let user completely autonomously select relevant tables based on actual business needs
Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user
Key emphasis: Table selection step cannot be skipped, this is a key link to ensure topic configuration accuracy
Prioritize recommending database connection method to users, only use Excel file method when user cannot provide database connection
Step 3: Query with Natural Language (Includes Topic Selection Logic)
Important: Step 3 can be executed directly (when Step 0 detects existing configuration)
After configuration is complete (or when existing configuration is detected), users can ask questions in natural language, the agent needs to select topic and generate SQL according to the following logic:
3.1 Topic Selection Logic
Scenario: One or more topics exist (user has completed topic setup)
Case A: User question explicitly mentions topic
Agent identifies topic keywords in user question (e.g., "sales", "human resources", "inventory", etc.)
Matches corresponding <topic name>.yaml file in ./output/ directory
If match is successful, directly use that yaml file to call script
If match fails, prompt user that topic does not exist and list available topics
Case B: User question does not explicitly mention topic
Agent analyzes question content, selects most relevant topic from all topics
Agent informs user: "Based on your question, I suggest using [topic name] topic, continue?"
If user confirms, use that topic; if user declines, list all topics for user to select
3.2 Call SQL Generation Script
After determining topic, call API to generate SQL:
All generated files are stored in ./output/ directory:
table_info.json - Table name list
column_info.json - Table structure information
<topic_name>.yaml - Topic configuration files
references/open_semantic_interchange_description.md - YAML file format specification and field definitions (refer to this document when users ask about YAML format, field meanings, or configuration details)
Notes
All scripts are pure functional tools without interaction logic, all inputs are passed through parameters
Database URL and password are saved in local configuration file ./output/text-to-sql-config.json
Topic configuration files are stored in yaml format for easy version management and viewing
Only query_sql.py calls API, other scripts are all executed locally
If database connection fails, check if URL and password are correct
If API service connection fails, check if service is started and address is correct
Prioritize database connection method, only use Excel file method when database connection cannot be provided
When users ask about YAML file format, field definitions, or configuration details, refer to the open_semantic_interchange_description.md document which contains complete specification of the semantic model YAML structure
Usage Examples
Example 0: Detected Existing Configuration (Direct Query)
User: "Query last month's total sales"
Agent: Check ./output/ directory
Agent: Detect existing topic configuration files
Agent: "Detected existing topic configuration, you can ask questions directly."
Agent: Identify topic relevant to the question, use corresponding topic configuration file
Agent: Call query_sql.py to generate SQL
Example 1: Intelligently Guide User to Set Up Topic (Recommended Process)
User: "Help me configure Text-to-SQL"
Agent: Check ./output/ directory
Agent: No yaml configuration files found, need to execute configuration process
Agent: "Please provide database URL and password"
User: "Database URL is URL"
Agent: Call config_db.py to save configuration
Agent: "Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance."
Agent: Call read_tables.py --config-file ./output/text-to-sql-config.json --output-dir ./output to read all tables
Agent: "There are multiple tables in the database, what topic do you want to create?"
User: "Create a topic"
Agent: "Please select tables to include in this topic from the database tables"
User: "Select relevant tables"
Agent: Call generate_yaml.py to generate topic configuration file
Agent: "Do you want to continue creating other topics?"
User: "No need"
User: "Query the top 10 products with highest sales last month"
Agent: Identify topic relevant to the question, use corresponding topic configuration file to call query_sql.py to generate SQL
Example 2: Configure with Excel File
User: "Help me configure Text-to-SQL, but I don't have a database"
Agent: Check ./output/ directory
Agent: No yaml configuration files found, need to execute configuration process
Agent: "Okay, you can use the Excel file method for configuration. Please provide an Excel file with format requirements: each sheet corresponds to a table name, first row is column names"
User: "Provide Excel file path"
Agent: Call read_tables.py --excel-file data_file.xlsx to read Excel data
Agent: "Topic setup is a mandatory step..."
Follow same process as Example 1
Example 3: Set Up Multiple Topics
User: "Help me configure Text-to-SQL"
Agent: Check ./output/ directory
Agent: No yaml configuration files found, need to execute configuration process
Agent: "Please provide database URL and password"
User: "Database URL is URL"
Agent: Call config_db.py to save configuration
Agent: "Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance."
Agent: Call read_tables.py --config-file text-to-sql-config.json to read all tables
Agent: "There are multiple tables in the database, what topic do you want to create?"
User: "Create first topic"
Agent: "Please select tables to include in this topic from the database tables"
User: "Select relevant tables"
Agent: Call generate_yaml.py to generate topic configuration file
Agent: "Do you want to continue creating other topics?"
User: "Create another topic"
Agent: "Please select tables to include in this topic from the database tables"
User: "Select relevant tables"
Agent: Call generate_yaml.py to generate topic configuration file
Agent: "Do you want to continue creating other topics?"
User: "No need"
User: "Query average salary of technical department"
Agent: Identify topic relevant to the question, determine most relevant topic
Agent: "Based on your question, I suggest using relevant topic, continue?"
User: "Yes"
Agent: Call query_sql.py using corresponding topic configuration file to generate SQL
Example 4: User Explicitly Specifies Topic
User configured multiple topics
User: "Use a specific topic to query total orders in 2024"
