Create & Configure a Database

This guide explains how to create and configure databases in MaiAgent, including uploading files to create data tables, connecting external databases, and setting column descriptions

MaiAgent's Database Management feature lets you centrally manage the database connections used by your AI Assistants on the platform. Combined with the Text to SQL feature, AI Assistants can query database data directly using natural language.

For a conceptual introduction to Text to SQL, see: Text to SQL Feature

MaiAgent supports two database types:

• MaiAgent Database: Upload Excel / CSV / JSON files and the system automatically creates data tables. Ideal for users without their own database

• External Database: Connect to an existing PostgreSQL, MySQL, MSSQL, or Oracle database

Create a Database

1. Go to the Database Management Page

Navigate to the "AI Features" section from the left sidebar and click "Database." The page has two tabs: MaiAgent Database and External Database.

Click the "Add Database" button in the upper right corner to begin.

If the button is grayed out and unclickable, your role has not been granted permission to create databases. Contact your organization administrator to set up permissions.

2. Select the Database Type

Choose the type of database you want to create by clicking the corresponding card:

• MaiAgent: Suitable for uploading spreadsheet files; no connection string required

• PostgreSQL / MySQL / MSSQL / Oracle: Connect to an existing external enterprise database

3. Fill In Basic Information

MaiAgent Database

Field	Required	Description
Database Name	Yes	e.g., "2024 Annual Sales Data"
Description	No	Additional notes about the database's purpose or content

MaiAgent databases do not require a connection string — the system handles data storage automatically. After creation, upload your spreadsheet files.

External Database

Field	Required	Description
Database Name	Yes	e.g., "Enterprise ERP Database"
Description	No	Additional notes about the database's purpose or content
Connection String	Yes	The database connection URL
Specified Tables	No	Restrict which tables the AI Assistant can query, separated by commas

Connection string formats are as follows:

PostgreSQL:   postgresql://username:password@host:port/database_name
MySQL:        mysql://username:password@host:port/database_name
MSSQL:        mssql+pymssql://username:password@host:port/database_name
Oracle:       oracle+cx_oracle://username:password@host:port/database_name

Make sure the connection string format is correct and includes all required connection information. The database URL must be accessible by the MaiAgent service.

After entering the connection string, click the "Test Connection" button to verify the connection:

• Connection successful: MaiAgent can access your database normally

• Connection failed: Check the connection string format, network connectivity, and whether the database allows external connections

If your database contains a large number of tables, enter the table names you want to expose in the "Specified Tables" field (e.g., customers, orders, products) to improve query efficiency and security.

4. Set Group Permissions

The final step is to set which groups can access this database. Use the transfer widget to move the groups that need authorization from the left panel to the right panel.

If you don't need to set group permissions right now, you can skip this step and adjust it later from the database settings page.

5. Complete Creation

After confirming all settings, click the "Create" button. Upon successful creation, you will be taken to the database settings page for further configuration.

After creation, don't forget to associate the database with an AI Assistant so the AI Assistant can use this database for queries. See: Associate AI Assistants and Group Permissions

Upload Files to Create Data Tables (MaiAgent Database)

After creating a MaiAgent database, go to the settings page, switch to the "Table Management" tab, and click the "Upload Table File" button.

Supported File Formats

Format	Extensions	Description
Excel	.xlsx, .xls	Each worksheet (Sheet) creates a separate data table
CSV	.csv	Comma-separated values file
JSON	.json, .jsonl	JSON format data file

After uploading, the system automatically parses the file structure and creates data tables in the background. Each data table displays a processing status:

Status	Description
Pending	File has been uploaded, waiting for system processing
Processing	System is parsing the file and creating the data table
Completed	Data table created successfully; the AI Assistant can query it
Failed	An error occurred during creation; hover over the error icon to see the reason

File Format Guidelines

• The first row must contain column names

• Data types within each column should be consistent (e.g., the price column should contain only numbers)

• Avoid merged cells

• Avoid duplicate column names

• Each worksheet (Sheet) in an Excel file should contain only one table

• It is recommended to annotate data formats after column names, e.g., price(int), date(datetime)

If a data table fails to create, common causes include: incorrect or corrupted file format, special characters in column names, duplicate column names, or inconsistent data types within the same column.

Edit Column Descriptions

Column descriptions are a critical setting for improving Text to SQL query accuracy. The AI Assistant references column descriptions to understand the meaning of the data, enabling it to generate more precise SQL queries.

For example, if your data table has a column called status, the AI Assistant may not know what it represents. But if you add a description like "Order status, possible values: pending, completed, cancelled," the AI Assistant can correctly understand the column's meaning.

How to Edit

MaiAgent Database: In the "Table Management" tab, click "Edit" on a data table to edit the table description and column descriptions. The dialog shows completion progress (e.g., "3/10 columns have descriptions").

External Database: Under the "Basic Information" tab, in the data table list below, click to expand a table and enter descriptions directly in the column description field.

Writing Tips

Good column descriptions can significantly improve AI query accuracy:

Column Name	Poor Description	Better Description
amt	Amount	Total order amount (NTD), including tax and shipping
cust_lvl	Level	Customer level. A = VIP customers with annual spending over 1 million, B = annual spending 100K-1M, C = others
reg	Region	Customer geographic region. Possible values: North, Central, South, East, Offshore Islands

Manage Existing Databases

Edit a Database

In the database list, click "Edit" in the action menu to enter the settings page.

The settings page contains the following tabs:

Tab	Description	Applicable Type
Basic Information	Edit name, description, enabled status, connection string	All
Table Management	Upload files, manage data tables and column descriptions	MaiAgent only
Associated AI Assistants	Specify which AI Assistants can use this database	All
Role Permissions	Set group access permissions	All

Enable / Disable

In the database list, use the "Enable" toggle to quickly switch the status. When disabled, AI Assistants temporarily cannot query this database, but settings and data are preserved.

Delete a Database

Deleting a database is an irreversible operation.

• MaiAgent Database: After deletion, all data tables created by uploading files will also be removed

• External Database: Only the connection configuration in MaiAgent is removed; the original database and its data are not affected