# Text to SQL with MaiAgent Knowledge Base

If you want your AI assistant to help analyze data in Excel or spreadsheet format, you can follow these steps to enable the AI assistant to generate statistical analysis results.

## Step 1: Switch AI Assistant to Agent Mode

{% hint style="info" %}
Please refer to "[Create AI Assistant - Choose Appropriate Response Mode to Create Instructions](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)" to switch AI assistant mode
{% endhint %}

* Agent mode grants the AI assistant the ability to use tools. In this mode, the AI assistant can understand the structure of spreadsheet data and use the Text-to-SQL tool for analysis.

Select MaiAgent in Agent mode. After switching, no changes are needed to the URL field below.

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a8e939c04f14f79c79d29e0e20541ab8a5cc2741%2F1.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-c3a99a7f0c4e92d8c15753a4fd1b9e851f204b0e%2F2.png?alt=media" alt=""><figcaption></figcaption></figure></div>

> You must select the maiagent service and save the result, otherwise the text to SQL tool cannot be enabled

## Step 2: Upload Spreadsheet Files like CSV

### 1. Enter the knowledge base page and click edit operation

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3d81f70151491313c77d4d566dfc94508606d29f%2F123%E5%89%AF%E6%9C%AC.png?alt=media" alt=""><figcaption></figcaption></figure>

### 2. Upload files (.xls, .xlsx, .csv)

{% hint style="info" %}
For detailed knowledge base file upload methods, please refer to: [Knowledge Base Overview - How to Upload Knowledge Base?](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/en/da-zao-qi-ye-zhi-shi-ku/km.md#ru-he-shang-chuan-zhi-shi-ku)
{% endhint %}

You can download the sample file (100 items of food sales file.xlsx) for testing to experience the AI assistant's data analysis capabilities.

> **Number of spreadsheet columns** and **Reranker retrieval segment count** are two completely independent configuration parameters that have no dependency or mutual influence on each other.
>
> For Reranker introduction, please refer to: [Technical Manual - Reranker Model](https://docs.maiagent.ai/tech/quickstart/reranker)

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-bfc482ed75b54d9a0c0bfdfe4b534c23784fc54f%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(1).png?alt=media" alt=""><figcaption><p>File upload screen</p></figcaption></figure> <figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-fc5121a6f2b4c00165ddc86d69bf20f736d8a0af%2Fimage%20(210).png?alt=media" alt=""><figcaption><p>Screen after upload completion</p></figcaption></figure></div>

When the file appears in the knowledge base and the processing status shows "<mark style="color:blue;">Completed</mark>" (as shown in the right image above), the system will automatically create a database, and the AI assistant can read your file to help you generate calculation and statistical results using SQL syntax.

> 📍Note: Text-to-SQL Q\&A functionality cannot be used without uploaded data

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

#### Table Format Notes

* [x] Each worksheet must contain only one table
* [x] The first row of the table must be the column names
* [x] To improve AI data retrieval accuracy and efficiency, it is recommended to annotate data formats after column names, such as: Price (int), Date (datetime)
* [x] If there are special formats (such as currency, percentage, etc.), they need to be uniformly formatted before conversion
* [x] Please ensure that data column names match the actual content and use the correct data types

## Step 3: Converse with AI Assistant

After completing the above steps, you can enter the AI assistant conversation page and directly tell the AI assistant your needs in natural language, just like discussing with another person.

{% hint style="info" %}
For AI assistant conversation interface, please refer to: [Choose Integration Platform](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/release/xuan-ze-chuan-jie-ping-tai), and select the most suitable conversation platform according to your needs.
{% endhint %}

### Data Analysis

The Text to SQL tool can help you analyze data in spreadsheets, for example: "Help me find the best-selling dairy products from last year"

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b49ef5cf4363892753424aa6225e7042392e2c2f%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-10-02%20123605.png?alt=media" alt=""><figcaption></figcaption></figure>

* When you make a request, the AI assistant will automatically invoke the Text-to-SQL tool.
* This tool acts like a translator, converting what you say into SQL syntax that computers understand, allowing the AI assistant to extract data from the database.

The AI assistant will automatically add conditional judgments, sorting criteria, and other query restrictions to convert your needs into more complete query instructions.

* **AI Assistant's Thinking Query:** Find the best-selling dairy products from last year, sorted in descending order by sales quantity. Automatically adds descending order conditions to make results better match your needs.
* **AI Assistant's Response (click on tool response to view):**

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-c4f745270d44290bd00923e4089e242f522e9ccd%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(2).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-ff5cc7add60481f938382af29146017a59aa96fc%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-10-02%20123141%20(1).png?alt=media" alt=""><figcaption></figcaption></figure></div>

**Result**

* The AI assistant found all sales data for "dairy products" and other field data for those items.
* Each row represents one data record, including: Product ID, Product Name, Product Category, Sales Amount, Sales Quantity......
* Based on this data, the AI assistant determined that the best-selling dairy product is "cheese," with a sales quantity of 110 and sales amount of 40,150 yuan.

### Report Creation (Canvas Mode)

The Text to SQL tool can also help you create beautiful reports. This feature requires enabling Canvas mode:

1. Go to "AI Assistant Settings Page > Response Mode Settings" and find <mark style="color:blue;">Agent Mode</mark>

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-41678399a2144df49036f13fbc9a87910ab8fd4a%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(4).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-dbe72984ddec2401d58bf02e457318c4b3b3e160%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(5).png?alt=media" alt=""><figcaption></figcaption></figure></div>

2. Change Agent mode from normal mode to <mark style="color:blue;">**Canvas Mode**</mark>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-c9be337e0574e5ddb418ac8c45a8fe0f338567fb%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(6).png?alt=media" alt=""><figcaption></figcaption></figure>

After saving the settings, you can converse with the AI assistant, for example: "Please help me generate a visualized revenue report after statistics"

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-727fef28fa05ee8af3a6d501bc0dc5a30ca32c94%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-10-02%20142354.png?alt=media" alt=""><figcaption></figcaption></figure>

* **AI Assistant's Thinking Query:** Calculate revenue statistics for each product in the food company, including total revenue, average revenue, revenue standard deviation, revenue distribution ranges, revenue proportion by category, and other statistical indicators. Automatically generates calculation results needed for reports to better match your needs.
* **AI Assistant's Response (click on tool response to view):**

{% code overflow="wrap" %}

```
[('分類營收占比-主食', '10.72%'), ('分類營收占比-乳製品', '11.97%'), ('分類營收占比-冷凍', '9.06%'), ('分類營收占比-罐頭', '10.25%'), ('分類營收占比-肉類', '13.23%'), ('分類營收占比-蔬果', '13.34%'), ('分類營收占比-調料', '4.51%'), ('分類營收占比-零食', '14.53%'), ('分類營收占比-飲料', '12.40%'), ('商品總數', '100'), ('平均營收', '19546.06'), ('最低營收', '1400'), ('最高營收', '63364'), ('營收標準差', '15736.83'), ('總營收', '1954606')]
```

{% endcode %}

**Result**

* The AI assistant obtains all automatically calculated statistical item results from the tool and returns them.
* The AI assistant uses this data as the basis for visualization and creates an interactive report screen using Canvas.

> Click on the "Use Canvas" box to view the screen content

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-4c8190e58d5e582b66ef541ddb971843b792a243%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(7).png?alt=media" alt=""><figcaption></figcaption></figure>

The report display screen is shown below. You can:

1. Switch between viewing original code or screen
2. Switch report content according to the statistical category you want to view (this varies depending on each AI assistant's output)

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-15f5d597a9ca2985c25b2fc6957f5ac514df6d07%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(8).png?alt=media" alt=""><figcaption></figcaption></figure>

When switching to other categories, you can view the category revenue proportion pie chart and distribution analysis bar chart:

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-31de64660cd44f438661d49df69f34556cd7ce3c%2Fimage%20(212).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-47fe3ba711365d2ddc28d0f587773a83cd4ef468%2Fimage%20(213).png?alt=media" alt=""><figcaption></figcaption></figure></div>

## **Conclusion**

Using the MaiAgent Text to SQL tool, you can quickly enable the AI assistant to help you analyze spreadsheet content and generate beautiful reports. Start experiencing now and let the AI assistant become your data analysis helper!

{% hint style="info" %}
**Additional Tips**

* **Data quality is important:** Ensure your spreadsheet data is clean and correct, as this will directly affect the accuracy of the AI assistant's analysis results.
* **Ensure data you don't want to share with AI is properly deleted**: Hidden data in spreadsheets can still be normally parsed by the knowledge base and provided to the AI assistant, so data you don't want exposed to the AI assistant cannot be just hidden but must be actually deleted.
* **Try different questions:** Through different questioning methods, you can uncover more valuable information from the data.
* **Make good use of Canvas mode:** Canvas mode allows you to easily create various visualization reports and present data analysis results more intuitively.
  {% endhint %}