> 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/en/build/database/text-to-sql-maiagent.md).

# Text to SQL with a MaiAgent Database

This article explains how to upload spreadsheets such as Excel and CSV to the MaiAgent database so the Agent can query and analyze your data in natural language

To have an Agent help you analyze spreadsheet data such as Excel and CSV, just upload the files to the MaiAgent database. The Agent can then query the data in natural language and produce statistical analysis results.

{% hint style="info" %}
For an introduction to the Text to SQL concept, see: [Text to SQL Feature](/maiagent-user-guide/en/build/database/text2sql.md)
{% endhint %}

## Step 1: Create a MaiAgent Database <a href="#step-1-create-maiagent-database" id="step-1-create-maiagent-database"></a>

1. From the left navigation bar, go to "<mark style="color:blue;">AI Features</mark>" > "<mark style="color:blue;">Database</mark>"
2. Click "<mark style="color:blue;">Add Database</mark>"
3. Select "<mark style="color:blue;">MaiAgent Database</mark>"
4. Enter a database name (for example, "2024 Sales Data") and click Create

{% hint style="info" %}
For the detailed creation process, see: [Create and Configure a Database](/maiagent-user-guide/en/build/database/create-database.md)
{% endhint %}

## Step 2: Upload a Spreadsheet File <a href="#step-2-upload-spreadsheet" id="step-2-upload-spreadsheet"></a>

After it is created, open the database settings page:

1. Switch to the "<mark style="color:blue;">Table Management</mark>" tab
2. Click "<mark style="color:blue;">Upload Table File</mark>"
3. Drag and drop or select your spreadsheet file

You can download the sample file (a food sales file with 100 items, .xlsx) to test with and experience the Agent's data analysis capabilities.

{% file src="/files/fLvf4ywYnhRrpdoPxJGc" %}

After the upload finishes, wait until the processing status shows "<mark style="color:blue;">Success</mark>", which means the table has been created.

{% hint style="warning" %}
Supported formats: `.csv`, `.xlsx`, `.xls`, `.json`, `.jsonl`. Each worksheet in an Excel file creates its own table.
{% endhint %}

#### Table Format Notes <a href="#table-format-notes" id="table-format-notes"></a>

* [x] Each worksheet (Sheet) must contain exactly one table
* [x] The first row must contain the column names
* [x] It is recommended to note the data type after each column name, such as `Price(int)`, `Date(datetime)`
* [x] The data type of each column should be consistent
* [x] If there are special formats (such as currency or percentages), unify the formatting before uploading

{% hint style="info" %}
To improve the accuracy of AI queries, it is recommended to add descriptions to tables and columns. See: [Create and Configure a Database - Edit Column Descriptions](/maiagent-user-guide/en/build/database/create-database.md#edit-column-description)
{% endhint %}

## Step 3: Link the Agent <a href="#step-3-link-ai-agent" id="step-3-link-ai-agent"></a>

Link the database to your Agent so the Agent can query the data:

1. Switch to the "<mark style="color:blue;">Link AI Assistant</mark>" tab
2. Select the Agent to link on the left and move it to the right
3. Click "<mark style="color:blue;">Save</mark>"

{% hint style="warning" %}
Make sure the Agent's reply mode is set to **Agent mode**; otherwise the Text to SQL feature cannot be used.

For detailed reply mode settings, see: [Create an Agent](/maiagent-user-guide/en/build/agent/setup.md)
{% endhint %}

## Step 4: Chat with the Agent <a href="#step-4-chat-with-ai-agent" id="step-4-chat-with-ai-agent"></a>

After completing the steps above, open the Agent's chat page and tell the Agent what you need in natural language.

{% hint style="info" %}
For the Agent chat interface, see: [Choose an Integration Platform](/maiagent-user-guide/en/build/choose-channel.md), and pick the chat platform that best fits your needs.
{% endhint %}

### Data Analysis <a href="#data-analysis" id="data-analysis"></a>

The Text to SQL tool helps you analyze the data in your spreadsheet, for example: "Find the best-selling dairy product 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&amp;token=8c703457-2f5e-4775-86ca-b21545c681f8" alt=""><figcaption></figcaption></figure>

* After you make a request, the Agent automatically calls the Text-to-SQL tool.
* This tool works like a translator: it translates what you say into SQL that a computer understands, so the Agent can retrieve data from the database.

The Agent automatically adds query constraints such as conditions and sort order, turning your request into a more complete query.

* **Agent's thinking Query:** Find the best-selling dairy product last year, sorted by sales quantity in descending order. A descending sort condition is added automatically so the result better fits your needs.
* **Agent's response (click the 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&amp;token=9c3ac9e8-2bb7-4729-bd3d-73783209e1c7" 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&amp;token=85cca60f-39ff-482a-8ba0-5b975449a5b6" alt=""><figcaption></figcaption></figure></div>

**Result**

* The Agent found all sales data for "dairy products" along with the other column data for those items.
* Each row represents one record, including: product ID, product name, product category, sales amount, sales quantity, and so on.
* Based on this data, the Agent determined that the best-selling dairy product is "cheese", with a sales quantity of 110 and a sales amount of 40,150.

### Report Creation (Canvas Mode) <a href="#report-creation-canvas-mode" id="report-creation-canvas-mode"></a>

The Text to SQL tool can also help you create polished reports. This requires turning on Canvas mode:

1. Go to "Agent settings page > under Reply 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&amp;token=7c8796cd-ae7f-4f2f-8ac6-cf15fad7c658" 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&amp;token=16f49598-420a-4c90-9987-13065e57ffbe" alt=""><figcaption></figcaption></figure></div>

2. Change the Agent mode from standard 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&amp;token=821dbd11-c4fd-45e3-8c77-e0104a5cc548" alt=""><figcaption></figcaption></figure>

After saving the settings, you can chat with the Agent, for example: "Please generate a visualized report of the revenue 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&amp;token=c362d2ad-62c4-4b83-b5e1-e3a163a176ee" alt=""><figcaption></figcaption></figure>

* **Agent's thinking Query:** Calculate revenue statistics for each product of the food company, including total revenue, average revenue, revenue standard deviation, revenue distribution ranges, and revenue share by category. The calculation results needed for the report are produced automatically so the result better fits your needs.
* **Agent's response (click the 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 Agent received the results of all the items the tool calculated automatically and returned them.
* The Agent used this data as the basis for visualization and built an interactive report view with Canvas.

> Click the "Use Canvas" box to view the 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&amp;token=8c88a99b-8dec-42c0-8fca-6aa5cf67b25d" alt=""><figcaption></figcaption></figure>

The report view looks like this, and you can:

1. Switch between viewing the source code and the rendered view
2. Switch the report content by the statistical category you want to view (this varies with the content each Agent produces)

<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&amp;token=5cda9c6f-f128-4a34-b5b9-c87e32184b8c" alt=""><figcaption></figcaption></figure>

When you switch to other categories, you can view the pie chart of revenue share by category and the bar chart of distribution analysis:

<div><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&amp;token=33652389-df16-4e57-b661-e69863860bfd" 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-deeec5cd7e0b60180064919150b856db8e3945b6%2Fimage%20(211).png?alt=media" alt=""><figcaption></figcaption></figure></div>

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

* **Data quality matters:** Make sure your spreadsheet data is clean and correct, as this directly affects the accuracy of the Agent's analysis results.
* **Delete data you do not want to give to the AI:** Data hidden in a spreadsheet can still be parsed and provided to the Agent, so data you do not want exposed must be deleted, not merely hidden.
* **Try different questions:** By asking in different ways, you can dig more valuable information out of your data.
* **Make good use of Canvas mode:** Canvas mode lets you easily create all kinds of visual reports and present data analysis results more intuitively.
* **Make good use of column descriptions:** Adding descriptions to table columns significantly improves the accuracy of AI queries.
  {% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/database/text-to-sql-maiagent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.