# Table and field descriptions

Add business explanations to tables and fields so agents understand what your data means.

使用指南 · 模块: data · 使用者 · 部署形态：资料未说明 · 已确认产品版本：资料未说明 · 来源：现有文档

Table and field descriptions add business meaning: what each record represents, how metrics are calculated, and what codes mean. Agents use this information to select relevant fields and query conditions.

## How descriptions change query results

For example, a people table stores gender in `sex`, where `1` means male and `2` means female. With this mapping in the field description, the agent has a basis for using `sex = 2` when asked “How many female users are there?” rather than guessing. This mapping is only an example; use your actual data conventions.

Similarly, a fund rating column named `star` may store text such as `★★★★` and `★★★★★` rather than numbers. Its description should say that ratings are stored as star-character text. A question about “funds rated four stars or above” should match the actual text:

```sql
-- Incorrect: comparing star-character text as a number
WHERE star >= 4

-- Correct: matching values actually stored in the database
WHERE star IN ('★★★★', '★★★★★')
```

A good description does more than translate a field name into plain language. It explains units, codes, and storage formats so business questions map to correct query conditions.

## Before you start

| Item         | Requirement                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------ |
| Permissions  | Project owner or administrator                                                                               |
| Prerequisite | Source is available, with a database/table tree in the sidebar                                               |
| Entry point  | Main navigation on the left → “More” → “Data sources” → open a source card → select a table in the left tree |

After selecting a table, the right side shows its name and description at the top, with “Field structure” and “Data preview” tabs below. “Field structure” is selected by default.

## Steps

**Write a table description**

The description editor is beside the table name, labeled Description.

When empty, its placeholder indicates the database's default description. Enter content to reveal “Save” below; click it to save. During saving, the button reads “Saving…”.

**Write field descriptions**

The “Field structure” table has four columns: column name, description, semantic type, and hidden.

The description column shows the effective description, with an icon on its left indicating the source:

| Icon     | Source                                               |
| -------- | ---------------------------------------------------- |
| Database | origin: original comment retrieved from the database |
| Robot    | ai: automatically generated by AskTable              |
| Pen      | human: written manually                              |

Click any blank area in a field row to expand its detail panel. At the bottom is an editor for the same description. Its placeholder asks for a field description or indicates the database's default description. Click “Save” after editing.

The information icon beside the Description column heading recommends accurate explanations of column meanings to improve accuracy.

**Refine descriptions with AI**

A star-shaped button at the top right of the editor shows “Automatically improve field description” on hover (“Automatically improve table description” for tables). Clicking it asks the model to rewrite the current content and fills the editor with the result. You can edit it further if needed.

**Set semantic types**

The semantic type column shows each field's current value. In the expanded detail panel, the corresponding dropdown organizes types into six groups:

Relationships, Numeric, Geographic, Text, Time, and Entity.

For example, Quantity, Currency, Revenue, and Gross profit belong to Numeric; City, Country, and Postal code belong to Geographic; Primary key and Foreign key belong to Relationships. Selecting a value saves immediately without confirmation.

The information icon beside the field-row heading explains that these are analytical semantic types following the Metabase convention. Manually set values are not overwritten by automatic inference.

**Use metadata export/import for bulk edits**

For many fields, you do not need to edit them one by one. Open “Settings” in the header, choose “Export” under “Metadata” to download JSON, edit `curr_desc` values in a text editor, then use “Import” to upload it again.

Import overwrites field descriptions and visibility and appends training data. For file sources, note that a database name such as `file_abc1` is a system-generated identifier, not the filename.

## Key constraints

| Item                    | Value or default                                                                                 | Where to change it                            |
| ----------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------- |
| Description length      | Maximum 255 characters; exceeding it turns the count and editor border red and disables “Save”   | The editor                                    |
| Description precedence  | human (manual) > origin (original database) > ai (generated) > empty string                      | —                                             |
| Semantic type overrides | Manual values are not overwritten by inference; automatic classification only fills empty values | Semantic type dropdown in field details       |
| Semantic type groups    | Relationships, Numeric, Geographic, Text, Time, Entity                                           | —                                             |
| Empty table description | Table list shows no description available                                                        | —                                             |
| Empty field description | Editor placeholder shows the database's default description                                      | —                                             |
| Bulk changes            | Overwrite descriptions and visibility; append training data                                      | “Settings” → “Metadata” → “Export” / “Import” |

## Troubleshooting

| Symptom                                                    | How to identify it                                                          | What to do                                                                                                   |
| ---------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Database has comments, but the description column is empty | Column is blank and the editor only shows a default-description placeholder | Database comments are only placeholders, not manual descriptions; add a manual description                   |
| Save has no effect                                         | More than 255 characters; counter and border are red                        | Shorten to no more than 255 characters, then save                                                            |
| AI still chooses the wrong field                           | Tool call details show a different column name                              | Add units, definitions, and enum meanings to the description; set a semantic type if needed                  |
| Description icon is not a pen                              | It is a database or robot icon                                              | The value is original or generated; editing manually changes it to a pen                                     |
| Required semantic type is missing                          | None of the six groups has the desired option                               | Semantic type is optional; explain the field in its description instead                                      |
| Bulk import has no effect                                  | Import completes but some items are not found                               | schema\_name / table\_name / field\_name in the import do not match the target; check the missing-field list |

## Next steps

- Make AI ignore columns entirely or replace sensitive values: [Field hiding and masking](https://docs.asktable.com/en/data/hidden-fields)
- Match abbreviations to actual values: [AI indexes](https://docs.asktable.com/en/data/ai-search)
- Maintain files and training sets: [Manage data sources, files, and training sets](https://docs.asktable.com/en/data/manage)
- Verify with a real question: [Conversations](https://docs.asktable.com/en/conversation)