> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/database/text2sql.md).

# Text to SQL Feature

## **What is Text to SQL?** <a href="#what-is-text-to-sql" id="what-is-text-to-sql"></a>

**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 the AI Assistant to "<mark style="color:blue;">understand human language</mark>" and directly operate on databases.

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

Imagine you are 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 instruction, which is time-consuming.

**With Text2SQL:**

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

### **Core Features of Text to SQL** <a href="#text-to-sql-core-features" id="text-to-sql-core-features"></a>

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

When you ask the AI Assistant "Find the best-selling beverage from yesterday," the AI Assistant first analyzes your question, understands that you want to find a "beverage" that sold the "best" "yesterday," then generates SQL syntax to query the database, and finally tells you the result: "cola."

## **What Text to SQL Can Help AI Accomplish** <a href="#what-text-to-sql-can-do" id="what-text-to-sql-can-do"></a>

### **Use Cases** <a href="#use-cases" id="use-cases"></a>

#### **Medical Clinic** <a href="#medical-clinic" id="medical-clinic"></a>

```
Doctor asks: "Find today's appointments for diabetic patients"
AI responds: "There are 5 diabetic patients with appointments today:
- Mr. Wang 10:00 follow-up visit
- Mrs. Li 14:30 follow-up checkup
- Ms. Chen 16:00 blood sugar monitoring"
```

#### **School Management** <a href="#school-management" id="school-management"></a>

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

#### **Retail Chain Store** <a href="#retail-chain" id="retail-chain"></a>

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

### **Advantages of Text to SQL** <a href="#text-to-sql-advantages" id="text-to-sql-advantages"></a>

#### **Efficiency Improvement** <a href="#efficiency-improvement" id="efficiency-improvement"></a>

* **Traditional approach**: Requires an SQL expert to write queries → 30 minutes
* **Text2SQL**: Ask in natural language → 3 seconds

#### **Lower Barrier** <a href="#lower-barrier" id="lower-barrier"></a>

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

#### **Real-Time Interaction** <a href="#real-time-interaction" id="real-time-interaction"></a>

* Ask and get answers immediately
* Supports follow-up questions
* Dynamically adjust query conditions

## How to Use Text to SQL in MaiAgent <a href="#how-to-use-text-to-sql-in-maiagent" id="how-to-use-text-to-sql-in-maiagent"></a>

{% hint style="info" %}
Before starting, you need to prepare: an enterprise relational database or Excel files (uploaded to the Knowledge Base)

If using a database, it is recommended that you:

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

### 1. Access AI Assistant Settings <a href="#enter-ai-agent-settings" id="enter-ai-agent-settings"></a>

* Select the AI Assistant you want to configure
* Switch to the Response Mode settings page

### 2. Switch the AI Assistant's Response Mode to Agent Mode <a href="#switch-to-agent-mode" id="switch-to-agent-mode"></a>

{% hint style="warning" %}
Make sure to switch to Agent Mode, otherwise the AI Assistant cannot use the Text to SQL feature

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

### 3. Enter the Enterprise Database URL <a href="#enter-database-url" id="enter-database-url"></a>

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

{% hint style="info" %}

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

<div><figure><img src="/files/1gzHZFov943MTUnj7yTe" alt=""><figcaption></figcaption></figure> <figure><img src="/files/YIN8x8zOR1fNw6yvlg9y" alt=""><figcaption></figcaption></figure></div>

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

#### MaiAgent <a href="#maiagent-database-url" id="maiagent-database-url"></a>

{% hint style="info" %}
Refer to: [Using MaiAgent Knowledge Base for Text to SQL](/maiagent-user-guide/maiagent-user-guide-en/database/text-to-sql-maiagent.md)
{% endhint %}

#### Microsoft SQL Server(MSSSQL) <a href="#mssql-database-url" id="mssql-database-url"></a>

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

Note: Ensure the database URL is accessible by the MaiAgent service

#### **MySQL** <a href="#mysql-database-url" id="mysql-database-url"></a>

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

Note: Ensure the database URL is accessible by the MaiAgent service

<figure><img src="/files/u3olNnEIYNbyc0L94zIt" alt=""><figcaption></figcaption></figure>

#### **Oracle** <a href="#oracle-database-url" id="oracle-database-url"></a>

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

Note: Ensure the database URL is accessible by the MaiAgent service

#### **PostgreSQL** <a href="#postgresql-database-url" id="postgresql-database-url"></a>

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

Note: Ensure the database URL is accessible by the MaiAgent service

<figure><img src="/files/hf9XPJmbhaniwlMjO1IP" alt=""><figcaption></figcaption></figure>

### **4. Click Save to Store the Settings** <a href="#save-settings" id="save-settings"></a>

<figure><img src="/files/EYZHkgMYOdYjamUZADzc" alt=""><figcaption></figcaption></figure>

With this setup, the AI Assistant can help you quickly query your inventory, employee information, and more, and compile well-organized reports and trends for you.

## **Troubleshooting** <a href="#troubleshooting" id="troubleshooting"></a>

* **Connection failed**: Check the database URL format and network connectivity
* **Query error**: Verify that table names and field names are correct
* **Insufficient permissions**: Check database user permission settings
* **Slow response**: Check query complexity and consider adding indexes

***

Text2SQL turns the AI Assistant into a database expert, allowing anyone to quickly obtain business insights using natural language, greatly improving the efficiency of data-driven decision making!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/database/text2sql.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.