Database Agent

The Database Agent connects to relational databases like PostgreSQL, MySQL, and MariaDB. It is ideal for structured data analysis, metrics, and reporting — allowing users to ask natural language questions that get translated into SQL queries.

Steps to Create

1. Click on Agent in the left sidebar, then give your agent a name.

2. Select Database Agent from the Agent Type list and click Next.

3. Connect your database: Enter the connection details —

   • Database Type: PostgreSQL, MySQL, or MariaDB
   • Host and Port
   • Database Name
   • Username and Password

4. Click Test Connection to verify connectivity.

5. Schema Configuration: Once connected, the system fetches your database schema (DDL).

   • Select the tables you want the agent to have access to.
   • Review and enrich table/column descriptions — clear descriptions help the agent generate more accurate SQL.

6. Domain Knowledge (optional): Add domain-specific context to help the agent understand your business logic (e.g., “revenue is calculated as quantity × unit_price”).

7. Review the auto-generated agent description and click Create Agent.

How It Works

When a user submits a question, the Database Agent follows this pipeline:

User Input → Security Check → Question Rewrite → [DDL + Business Logic + Few-shot Examples] → Generate SQL →
Ambiguity Detection →
   [Clear] → Execute Query → Generate Answer
   [Ambiguous] → Request Clarification

Key Components

Security Check

• Detects malicious inputs such as SQL injection, tautologies, and schema enumeration attempts.
• Returns a safe error message for unsafe queries before any processing occurs.

Question Rewriting

• Converts relative dates to absolute dates (e.g., “last 30 days” → actual date range).
• Incorporates follow-up context for multi-turn conversations.

Knowledge Retrieval

• DDL: Database schema definitions used to generate accurate SQL.
• Business Logic: Domain knowledge that guides query interpretation.
• Few-shot Examples: Sample question–SQL pairs that improve generation quality.

Note

DDL is generally a System Prompt

SQL Generation

• Uses chain-of-thought reasoning before producing a query.
• Detects ambiguity and asks for clarification when the question is unclear.
• Auto-retries and repairs queries on execution failure.

---

Run and Test

1. Click Run to start the agent.

2. Enter a test question.

3. The agent will generate and execute the appropriate SQL query and return the results.

---

Debug with Step Run

Discover supports step-by-step execution for agent components, providing a robust debugging mechanism:

1. Click the triangle icon above a component, or open the component’s detail page and select Test Run.

2. Enter a test question and click Run to see the component’s output.

3. Adjust Rerank model, Similarity threshold, or Keyword similarity weight if retrieval results are not as expected.

4. Observe the inputs and outputs of each node to identify where issues occur.

---

Production Considerations

1. Schema descriptions: Provide clear, accurate descriptions for tables and columns — this directly impacts SQL quality.
2. Business logic: Document domain-specific rules (e.g., metric definitions, filters that always apply) in the Domain Knowledge section.
3. Few-shot examples: High-quality question–SQL pairs significantly improve the agent’s accuracy on complex queries.
4. Security: The agent automatically blocks destructive operations (DELETE, DROP, TRUNCATE). Ensure your database user has read-only permissions as an additional safeguard.
5. Synonyms and abbreviations: If your users commonly use shorthand or domain-specific terms, add a thesaurus or synonym mappings to your Domain Knowledge to help the agent interpret them correctly.