TEXT2SQL

⚙️ Configuration

Dependency Description

Required packages and versions for scripts:

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.ucap.com.cn/

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:

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

📋 Tips & Best Practices

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