How to Use the SQL Formatter + Explainer + Complexity Meter: Step-by-Step Tutorial

Step 1: Open the SQL Formatter + Explainer

Go to the SQL Formatter + Explainer + Complexity Meter page. You will see the input editor, dialect selector, action buttons, and the advanced options toggle.

Step 2: Paste or Upload Your SQL

The default mode is Paste SQL — type or paste any SQL query directly into the editor. To load a file instead, click the "Upload / Drop" tab and either drag a .sql or .txt file into the drop zone or click to browse. Here is a sample query to try:

SELECT
  c.customer_name,
  COUNT(o.order_id) AS total_orders,
  SUM(o.amount) AS total_revenue
FROM customers c
INNER JOIN orders o ON c.customer_id = o.customer_id
LEFT JOIN refunds r ON o.order_id = r.order_id
WHERE o.status = 'paid'
  AND o.order_date >= '2024-01-01'
  AND r.refund_id IS NULL
GROUP BY c.customer_name
HAVING SUM(o.amount) > 1000
ORDER BY total_revenue DESC
LIMIT 10;

Step 3: Select Your Dialect

Use the Dialect dropdown to choose Generic, PostgreSQL, MySQL, SQL Server, or SQLite. This affects how the parser interprets your SQL and how the formatter handles dialect-specific syntax. If you're not sure, leave it on Generic.

Step 4: Configure Advanced Options

Click "Advanced Options" to expand the settings panel. You can toggle uppercase keywords on or off, choose between 2-space and 4-space indentation, and enable or disable blank lines between major clauses. These settings only affect the formatted output — they don't change the explanation or complexity score.

Step 5: Click Format + Explain

Click the blue "⚡ Format + Explain" button to run all three functions at once. The results panel appears below the editor with five tabs: Formatted SQL, Explanation, Extracted Facts, Complexity, and Errors (only if errors were detected).

You can also run individual functions: "✨ Format" for formatting only, or "💡 Explain" for the explanation and complexity score without reformatting.

Step 6: Review the Formatted SQL

The Formatted SQL tab shows the cleaned-up query with consistent indentation, keyword casing, and clause separation. A stats row at the bottom shows the line count and character count. Click "Copy" to copy the formatted SQL to your clipboard.

Step 7: Read the Plain English Explanation

Switch to the Explanation tab. The Summary section shows a one-or-two sentence description of what the query does. For the sample query, it explains that the query reads data from customers, joining 2 tables, applying 3 filter conditions, grouped by customer_name, returning the top 10 rows.

The Breakdown section lists every structural element as labeled entries: tables read from, joins with types, filter count, grouping fields, aggregates used, sort order, and row limit.

Step 8: Browse the Extracted Facts

The Extracted Facts tab shows a card grid with every piece of structural information the tool identified: statement type, tables, joins, filters, GROUP BY, aggregates, ORDER BY, limit, subqueries, CTEs, and window functions. This is the raw data behind the explanation — useful for documentation or verifying that the parser found everything.

Step 9: Check the Complexity Score

Switch to the Complexity tab. The score is shown as a large number (0–100) with a colored label: Simple, Moderate, Complex, or Very Complex. A colored bar provides a visual indicator. Below the bar, the breakdown lists every element that contributed to the score with its point value.

For the sample query, the score is around 55 (Complex) because it has 3 tables (15 points), 2 joins (20 points, capped at 20), GROUP BY (10 points), and 3 filters (6 points).

Step 10: Copy and Share Results

Use the Copy buttons on the Formatted SQL and Explanation tabs to copy results to your clipboard. You can paste the formatted query back into your editor or include the plain English explanation in documentation, code review comments, or team wikis.