SQL Execution & Results

Once the AI Query Engine generates a valid SQL query, it’s passed to the SQL Execution Layer. This component is responsible for securely connecting to your database, executing the query, and returning results in a clean, structured format.

---

⚙️ What It Does

• Establishes a secure, temporary connection to the PostgreSQL database you provided in db_url

• Executes the AI-generated or tool-filled SQL SELECT statement

• Handles common query errors (e.g., syntax errors, bad column names)

• Returns:

  • Raw SQL results (list of rows)

  • Metadata (e.g., column names)

  • Optional LLM-refined answer

---

🔒 Stateless + Safe

• Billx-Agent does not persist your credentials or connection details

• Each request includes its own db_url — processed in-memory and discarded after execution

• All queries are read-only by design (only SELECT statements are allowed)

---

📥 Input

{
  "db_url": "postgresql://user:pass@host:5432/mydb",
  "sql_query": "SELECT COUNT(*) FROM orders WHERE amount > 1000;"
}

---

📤 Output

{
  "result": [
    { "count": 253 }
  ],
  "columns": ["count"]
}

If /chat or /audio-chat is used, this step is performed automatically after the LLM returns SQL.

---

🧪 Error Handling

If the SQL fails (e.g. due to a typo or invalid column), the system returns a detailed error message:

{
  "error": "column 'ammount' does not exist"
}

---

This module ensures that the AI-generated queries are actually useful — it bridges AI with your real production data.