Text to SQL

intent

converts plain english descriptions of data needs into syntactically correct SQL queries. activate this skill when a user describes what data they want, provides (or references) a database schema, and explicitly asks for the SQL query. the skill bridges the gap between natural language intent and executable SQL, handling table selection, joins, filtering, grouping, and ordering. use this when the user says things like "write SQL for this", "convert to a query", "how do I select", or "give me the SQL".

inputs

required inputs:

• natural language description of the data need (what the user wants to retrieve or calculate)
• database schema information in one of these forms: explicit table/column names and types, a CREATE TABLE statement, a DESCRIBE output, or column references from prior context
• SQL dialect specification (PostgreSQL, MySQL, SQLite, T-SQL, etc.) - if not stated, assume PostgreSQL as default
• (optional) existing table aliases if the request spans multiple tables

external connections:

• none. this skill generates SQL text only and does not execute queries, connect to live databases, or fetch schema from external systems

edge cases to handle:

• schema not provided: ask user to supply it before proceeding
• ambiguous column names across multiple tables: request clarification on which table owns the column
• reserved SQL keywords used as column names: quote them appropriately for the dialect
• mismatched data types in join conditions: flag and request correction
• rate limits: not applicable (no API calls)
• network timeouts: not applicable (no external connections)

procedure

step 1: confirm and map schema

1. receive the natural language request
2. check if schema information is present in the request or context
3. if schema is absent, reply: "could you share the table schema? i need column names and types to write the query."
4. if schema is present, extract and normalize it into a map format: {table_name: {column_name: data_type, ...}, ...}
5. note any foreign key relationships mentioned or implied
6. output: schema map, confirmed dialect, list of available tables and columns

step 2: parse natural language intent into SQL clauses

1. identify key phrases in the user's request
2. map each phrase to a SQL component using the intent-to-clause reference table (see below)
3. note which columns are required in the SELECT clause
4. identify WHERE conditions, GROUP BY keys, ORDER BY fields, and LIMIT counts
5. output: structured SQL plan listing SELECT columns, WHERE conditions, JOINs, GROUP BY, ORDER BY, LIMIT

step 3: determine table and join logic

1. identify all tables needed to answer the question
2. if multiple tables are required: a. locate the foreign key or join column connecting each table pair b. if join logic is unclear, ask: "which column links [table1] to [table2]?" c. choose join type: INNER JOIN (default), LEFT JOIN (if left table may have nulls on right), RIGHT JOIN (rare; prefer LEFT with table order reversed)
3. if single table, skip join logic
4. output: list of all tables, join conditions, and join types

step 4: generate and validate query

1. construct the full SQL query following this structure:

   SELECT [columns with table aliases]
   FROM [primary table] [alias]
   [INNER/LEFT/RIGHT JOIN [table] ON condition]*
   WHERE [conditions]
   GROUP BY [columns if aggregates present]
   HAVING [aggregate filters if needed]
   ORDER BY [columns] [ASC|DESC]
   LIMIT [n];
   

2. check all column references against the schema map
3. verify all table aliases are defined and used consistently
4. confirm that any aggregate function (COUNT, SUM, AVG, etc.) has a matching GROUP BY clause
5. test for ambiguous column names (qualify all with aliases)
6. verify JOIN conditions use matching data types
7. output: finalized SQL query + one-line plain english translation (e.g., "returns the top 10 customers by total revenue in 2024")

decision points

if schema is not provided:

• ask the user to supply table names, column names, and data types before writing the query. do not invent or guess schema.

if multiple tables are needed but join keys are unclear:

• request explicit clarification on which column links the tables (e.g., "is orders.customer_id the foreign key to customers.id?").

if the user requests SELECT * without justification:

• in a learning context or exploration, SELECT * is acceptable. in a production context, recommend listing specific columns instead. clarify intent with the user.

if a natural language phrase maps to multiple possible SQL clauses:

• "top N" means ORDER BY [column] DESC LIMIT N, but ask which column to sort by if not stated (e.g., "top 10 by revenue or by date?").
• "recent" or "latest" without a date column context: ask which date/timestamp column to use.
• "each [X]" could mean GROUP BY or PARTITION BY; clarify if windowing is needed.

if the dialect is unstated:

• assume PostgreSQL. if the user later specifies a different dialect (MySQL, SQLite, T-SQL), adapt function names, date handling, and quoting rules accordingly.

if reserved SQL keywords collide with column names:

• quote identifiers: PostgreSQL uses double quotes ("column"), MySQL uses backticks (column), SQLite uses both. ask user or assume double quotes for PostgreSQL.

if an aggregate query lacks GROUP BY:

• flag this as an error: "your query uses COUNT/SUM but has no GROUP BY. did you want grouped results, or a single aggregate row?".

output contract

on success, deliver:

1. a valid, executable SQL query in the specified dialect
2. one-line plain english translation of what the query does
3. (if requested via /text-to-sql/explain mode) the same query with inline comments on each clause
4. (if requested via /text-to-sql/alternatives mode) 2-3 alternative query approaches with trade-offs (e.g., subquery vs CTE, different JOIN order)

data format:

• SQL query as a code block (triple backticks with sql language tag)
• plain text description
• no execution results (the skill does not run queries)

file location:

• if user requests export, deliver as a .sql file with a meaningful name (e.g., top_customers_2024.sql)

guarantees:

• query is syntactically correct for the stated dialect
• all column and table names match the provided schema exactly
• all columns are qualified with table aliases in multi-table queries
• any aggregate function has a corresponding GROUP BY clause
• the query actually answers the stated natural language question

outcome signal

the user knows the skill worked when:

1. they receive a SQL query that is syntactically valid and can be run immediately
2. the query matches their natural language intent exactly (they do not need to edit it)
3. if they run the query against their schema, it returns the data they asked for without errors
4. the one-line translation confirms the query does what they wanted
5. in /explain mode, they understand each part of the query from the inline comments
6. in /alternatives mode, they can see trade-offs between query strategies and pick the one that fits their use case

failure signals (do not output if these occur):

• query references a column not in the schema
• table aliases are undefined or inconsistent
• an aggregate function exists without GROUP BY
• the query is syntactically invalid for the stated dialect
• the query does not actually answer the stated question

---

reference: intent-to-clause mapping

natural language phrase	SQL clause	example
"all", "every", "complete list"	SELECT [all columns or *]	SELECT * FROM orders
"only", "just", "specifically"	SELECT [named columns]	SELECT customer_name, total FROM orders
"where [condition]"	WHERE	WHERE created_at > '2024-01-01'
"sorted by", "in order of", "by"	ORDER BY	ORDER BY total DESC
"grouped by", "each [X]", "per [X]"	GROUP BY	GROUP BY customer_id
"top N", "first N", "N most"	ORDER BY [col] DESC LIMIT N	ORDER BY revenue DESC LIMIT 10
"bottom N", "lowest N"	ORDER BY [col] ASC LIMIT N	ORDER BY revenue ASC LIMIT 5
"not", "exclude", "without"	WHERE NOT / != / <>	WHERE status != 'cancelled'
"both X and Y", "along with"	AND / JOIN	WHERE x > 10 AND y < 20
"either X or Y"	OR	WHERE status = 'active' OR status = 'pending'
"between X and Y"	BETWEEN	BETWEEN 100 AND 500
"like", "containing", "includes", "starts with"	LIKE	LIKE '%example%'
"before", "after", "earlier than"	< / > on date	WHERE date < '2024-01-01'
"latest", "most recent", "newest"	ORDER BY date DESC LIMIT 1	ORDER BY created_at DESC LIMIT 1
"count of", "how many"	COUNT(*)	COUNT(*) AS total_orders
"total of", "sum of"	SUM	SUM(amount) AS revenue
"average of", "mean"	AVG	AVG(price) AS avg_price
"distinct", "unique"	SELECT DISTINCT	SELECT DISTINCT customer_id
"matches", "equals", "is"	=	WHERE region = 'US'

---

reference: join types and when to use

join type	use case	example
INNER JOIN	you want only rows that match on both sides	SELECT o.id, c.name FROM orders o INNER JOIN customers c ON o.customer_id = c.id
LEFT JOIN	you want all rows from the left table plus matches from right; nulls if no match	SELECT o.id, c.name FROM orders o LEFT JOIN customers c ON o.customer_id = c.id
RIGHT JOIN	you want all rows from right table plus matches from left (avoid; rewrite as LEFT with table order flipped)	SELECT o.id, c.name FROM orders o RIGHT JOIN customers c ON o.customer_id = c.id
FULL OUTER JOIN	you want all rows from both tables (PostgreSQL, T-SQL; MySQL does not support)	SELECT o.id, c.name FROM orders o FULL OUTER JOIN customers c ON o.customer_id = c.id
CROSS JOIN	cartesian product (all rows from left paired with all rows from right); use only if intentional	SELECT * FROM colors CROSS JOIN sizes

---

credits: original skill by wangjipeng977 (https://github.com/MiniMax-AI/skills). enriched per implexa quality standards.