# Text to SQL Feature

## **What is Text to SQL?**

**Text to SQL** (also known as Text2SQL) is an intelligent tool that automatically converts **natural language questions** (everyday human language) into **SQL database query statements**. Simply put, it enables AI assistants to "<mark style="color:blue;">understand human language</mark>" and directly operate databases.

{% hint style="info" %}
For more information about Text2SQL, please see: [Technical Manual—Text to SQL](https://docs.maiagent.ai/tech/advanced-genai-tech/text-to-sql)
{% endhint %}

Imagine you're a convenience store owner:

**Traditional approach:**

* You: "Help me check how many bottles of cola were sold yesterday"
* Employee: "Boss, you need to teach me how to use the POS system to query..."
* You: "Click here, select there, enter conditions..."

Requires hands-on teaching, which is time-consuming.

**With Text2SQL:**

* You: "Help me check how many bottles of cola were sold yesterday"
* AI Employee: "Sure!" 💫 *(automatically generates query method and calls database)* → "87 bottles of cola were sold yesterday" ✅

### **Core Functions of Text to SQL**

```
Natural language question → AI understanding and analysis → SQL query statement → Execute query → Return results
```

When you ask the AI assistant "Find yesterday's best-selling beverage," the AI assistant first analyzes your question, understands you're looking for a "beverage" that was the "best-selling" "yesterday," then generates SQL syntax to query the database, and finally tells you the result: "Coca-Cola."

## **What Text to SQL Can Help AI Accomplish**

### **Specific Application Scenarios**

#### **🏥 Medical Clinic**

```
Doctor asks: "Find today's diabetes patient appointments"
AI responds: "There are 5 diabetes patients scheduled today:
- Mr. Wang 10:00 Follow-up visit
- Mrs. Lee 14:30 Follow-up examination
- Miss Chen 16:00 Blood glucose monitoring"
```

#### **🏫 School Management**

```
Teacher asks: "How many students failed this exam?"
AI responds: "This math exam:
- Total students: 45
- Failed: 8 (17.8%)
- Student list for makeup exam has been compiled"
```

#### **🏪 Retail Chain Store**

```
Store manager asks: "Compare monthly revenue of three branches"
AI responds: "November branch revenue comparison:
- Taipei Store: $1,200,000 (↑15%)
- Taichung Store: $950,000 (↑8%)  
- Kaohsiung Store: $800,000 (↓3%)"
```

### **Advantages of Text to SQL**

#### **⚡ Efficiency Improvement**

* **Traditional approach**: Requires SQL expert to write queries → 30 minutes
* **Text2SQL**: Natural language questions → 3 seconds

#### **🎯 Lower Barrier to Entry**

* **No need** to learn complex SQL syntax
* **No need** to memorize database structure
* **Anyone** can query data

#### **📱 Real-time Interaction**

* Get answers immediately after asking
* Support for follow-up questions
* Dynamic adjustment of query conditions

## How to Use Text to SQL Feature in MaiAgent

{% hint style="info" %}
Before using, you need to prepare: Enterprise-associated database or Excel file (upload to knowledge base)

If using a database, we recommend:

* Ensure clear data table structure
* Create appropriate indexes
* Maintain data quality
  {% endhint %}

### 1. Enter AI Assistant Settings

* Select the AI assistant you want to configure
* Switch to the response mode settings page

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-f6c760fd5b0407a4d9558fe7fb10ff8a8bbb52d3%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(7)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e2c3e73ffd40e5dd7828c6105331218414fc711b%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(8)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure></div>

### 2. Switch AI Assistant's Response Mode to Agent Mode

{% hint style="warning" %}
You must switch to Agent mode, otherwise the AI assistant cannot use the Text to SQL feature

For detailed introduction of each response mode, please refer to: [Create AI Assistant](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/build/setup.md#xuan-ze-shi-he-de-hui-da-mo-shi-jian-li-zhi-ling)
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-d86be7a233d62daf3cc9b13bda053a170853f093%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(9)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### 3. Enter Enterprise Database URL

* Use the dropdown menu to select the database service used within the enterprise
* Enter the database service URL used by the enterprise to allow the MaiAgent system to connect and operate within the database

{% hint style="info" %}

* MaiAgent supports:
  * **MySQL**
  * **PostgreSQL**
  * **Oracle DB**
  * **Microsoft SQL Server (MSSQL)**
* The maiagent option applies Excel files you have uploaded in the MaiAgent knowledge base
  {% endhint %}

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b0015159b307dd351f17f57889ed0079cccddc52%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(10).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b42d84db3b492000661ccc098bf24d74a9397dd3%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(11).png?alt=media" alt=""><figcaption></figcaption></figure></div>

{% hint style="danger" %}
Please ensure the URL format is correct and includes necessary connection information, such as: host name, port, database name, username, and password.
{% endhint %}

#### MaiAgent

{% hint style="info" %}
Please refer to: [Using MaiAgent Knowledge Base for Text to SQL](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/tools/text-to-sql-maiagent)
{% endhint %}

#### Microsoft SQL Server(MSSSQL)

Connect to an existing MSSQL database by pasting the MSSQL database connection string

📍Please note: Ensure the database URL is accessible by MaiAgent service

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-8c953e3b3aaea9d6a2ce9622011cd56187c85b81%2Fimage%20(215).png?alt=media" alt=""><figcaption></figcaption></figure>

#### **MySQL**

Connect to an existing MySQL database by pasting the MySQL database connection string

📍Please note: Ensure the database URL is accessible by MaiAgent service

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-329cb7cb01073ddcec1099240d5f9a0baca095d0%2F%E6%88%AA%E5%9C%96%202025-04-25%20%E4%B8%8A%E5%8D%8810.45.19.png?alt=media" alt=""><figcaption></figcaption></figure>

#### **Oracle**

Connect to an existing Oracle database by pasting the Oracle database connection string

📍Please note: Ensure the database URL is accessible by MaiAgent service

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0687b5b3b4e4fa616b4d1fb237030ed59fa813c3%2Fimage%20(216)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

#### **PostgreSQL**

Connect to an existing PostgreSQL database by pasting the PostgreSQL database connection string

📍Please note: Ensure the database URL is accessible by MaiAgent service

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-24cd0b16c511cfaa75fb8bea648f8f8617f37110%2F%E6%88%AA%E5%9C%96%202025-04-25%20%E4%B8%8A%E5%8D%8810.45.57.png?alt=media" alt=""><figcaption></figcaption></figure>

### **4. Click Save to Preserve Settings**

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e2402a782e0f1bed5bf2792cb43c6bc98f82175d%2F%E6%96%B0%E5%A2%9E%E7%B5%84%E7%B9%94%E6%88%90%E5%93%A1%20(12).png?alt=media" alt=""><figcaption></figcaption></figure>

This way, the AI assistant can help you quickly query your inventory, employee information, etc., and compile well-organized reports and trends for you.

## **Common Troubleshooting**

* **Connection failure**: Check database URL format and network connectivity
* **Query error**: Confirm table names and column names are correct
* **Insufficient permissions**: Check database user permission settings
* **Slow response**: Check query complexity, consider adding indexes

***

Text2SQL turns AI assistants into database experts, enabling anyone to use natural language to quickly gain business insights, dramatically improving the efficiency of data-driven decision-making!