> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据说明

> 讲解 AI 表格的基本数据结构，包括 Base 文档、字段属性以及不同字段类型对应的记录值格式，为接口调用与数据处理提供参考。

## 数据结构

* Base，即一篇AI表格文档

  * `baseId`唯一标识了一篇AI表格文档。`baseId`可以通过以下方法获取。

    | **通过URL获取**  image.png | **通过文档信息面板获取**  imageimage | **通过其它API获取**  - 可通过[获取节点列表](/zh/open/development/get-node-list)接口获取。 **说明**  创建AI表格时，`docType`值为`BASE`。 |
    | ---------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------- |
* Sheet（即数据表），一篇AI表格文档中通常有多个数据表，且至少有一个数据表。

  * 所有需要访问sheet的接口都可以使用`sheetId`或`sheetName`作为入参。
  * sheetId可以通过[获取所有数据表](/zh/open/development/api-notable-getallsheets)接口获取。

### 说明

sheetId仅保证在文档中唯一，不保证全局唯一。

* sheetName为前端可见的sheet名称，如下图中的`任务管理`。
* Field（即字段），数据表中的每一列即是一个字段，一个数据表中通常有多个字段。

  * 所有需要访问field的接口都可以使用`fieldId`或`fieldName`作为入参。
  * fieldId可以通过[获取所有字段](/zh/open/development/api-noatable-getallfields)接口获取。

### 说明

fieldId仅保证在文档中唯一，不保证全局唯一。

* fieldName为前端可见的field名称，如下图中的`重要程度`。
* 每个sheet的第一列为「主字段」，其仅支持特定几种字段类型，且该列不可删除。具体支持的字段类型使用如下方法查看

  * 打开任意AI表格
  * 编辑主字段
  * 查看可设置的字段类型
* Record（即记录），数据表中的每一行即是一个记录，一个数据表中通常有多个记录。

  * 所有需要访问record接口需要使用`recordId`。
  * recordId可以通过[新增记录](/zh/open/development/api-notable-insertrecords)或[列出多行记录](/zh/open/development/api-notable-listrecords)等接口获取。

### 说明

recordId仅保证在文档中唯一，不保证全局唯一。

![数据结构](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/2556362571/p979051.png)

## 字段属性

字段属性区域，如下图所示：

![字段属性](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/9856362571/p979045.png)

不同字段类型所支持的属性请参考下表：

| **字段名** | **类型 (type)**      | **属性 (property)**                                                                                                                                                                                                                                                 |
| ------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 文本      | text               | 无                                                                                                                                                                                                                                                                 |
| 数字      | number             | `formatter` 取值：`INT` / `FLOAT_1` / `FLOAT_2` / `FLOAT_3` / `FLOAT_4`（保留 N 位小数）/ `THOUSAND` / `THOUSAND_FLOAT`（千分位）/ `PERCENT` / `PERCENT_FLOAT`（百分比）                                                                                                              |
| 货币      | currency           | `currencyType`：`CNY` / `HKD` / `USD` / `EUR` / `GBP` / `MOP` / `VND` / `JPY` / `KRW` / `AED` / `AUD` / `BRL` / `CAD` / `CHF` / `INR` / `IDR` / `MXN` / `MYR` / `PHP` / `PLN` / `RUB` / `SGD` / `THB` / `TRY` / `TWD`；`formatter` 取值：`INT` / `FLOAT_1` … `FLOAT_4` |
| 单选      | singleSelect       | `{ choices: [{ name: "optionName1" }, { name: "optionName2" }] }`                                                                                                                                                                                                 |
| 多选      | multipleSelect     | 同「单选」                                                                                                                                                                                                                                                             |
| 日期      | date               | `formatter` 取值：`YYYY-MM-DD` / `YYYY-MM-DD HH:mm` / `YYYY/MM/DD` / `YYYY/MM/DD HH:mm`                                                                                                                                                                              |
| 人员      | user               | `{ multiple: boolean }`（支持多选，默认为 true）                                                                                                                                                                                                                            |
| 部门      | department         | `{ multiple: boolean }`（支持多选，默认为 true）                                                                                                                                                                                                                            |
| 附件      | attachment         | 无                                                                                                                                                                                                                                                                 |
| 单向关联    | unidirectionalLink | `{ multiple: boolean, linkedSheetId: "xxx" }`（`linkedSheetId` 为关联的数据表 ID）                                                                                                                                                                                         |
| 双向关联    | bidirectionalLink  | `{ multiple: boolean, linkedSheetId: "xxx", linkedFieldId: "yyy" }`（创建字段时 `linkedFieldId` 不传）                                                                                                                                                                     |
| 链接      | url                | 无                                                                                                                                                                                                                                                                 |

## 记录值格式

记录值（又称字段值）展示，如下图所示：

![记录值格式](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8956362571/p979046.png)

不同字段类型所使用的格式请参考下表：

| **字段名** | **类型 (type)**      | **设置值（新增/更新记录时使用的格式）**                                   | **返回值（返回记录值时返回的格式）**                                                                                                                                                          |
| ------- | ------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 文本      | text               | `"TextString"`（字符串）                                      | `"TextString"`（字符串）                                                                                                                                                           |
| 数字      | number             | `123`（支持整数 / 浮点数 / 字符串）                                  | `"123"`（数字值，以字符串形式返回）                                                                                                                                                         |
| 货币      | currency           | `123`（支持整数 / 浮点数 / 字符串）                                  | `"123"`（数字值，以字符串形式返回）                                                                                                                                                         |
| 单选      | singleSelect       | `"optionName1"`（单选选项名）                                   | `{ "id": "id", "name": "optionName1" }`（id 为选项 ID，name 为选项名）                                                                                                                  |
| 多选      | multipleSelect     | `["optionName1", "optionName2"]`（多选选项名）                  | `[{ "id": "id1", "name": "optionName1" }, { "id": "id2", "name": "optionName2" }]`                                                                                            |
| 日期      | date               | `1688601600000`（时间戳）或 `"2023-12-20 03:00"`（ISO 8601 字符串） | `1688601600000`（时间戳）                                                                                                                                                          |
| 人员      | user               | `[{ unionId: "xxx" }]`                                   | `[{ unionId: "xxx" }]`                                                                                                                                                        |
| 部门      | department         | `[{ deptId: "xxx" }]`                                    | `[{ deptId: "xxx" }]`                                                                                                                                                         |
| 附件      | attachment         | 具体请参考[上传附件](/zh/open/development/upload-attachment)。     | `[{ "filename": "image.xlsx", "size": 92250, "type": "xls", "url": "xxx" }]`  **说明**  url 是附件访问链接。- 当附件是在线文档时，其是在线文档链接，该链接没有访问时效。- 当附件是其它文件时，是一个有**访问时效**的下载链接，一段时间后该链接将无法访问。 |
| 单向关联    | unidirectionalLink | `{ "linkedRecordIds": ["xxx", "yyy"] }`                  | `{ "linkedRecordIds": ["xxx", "yyy"] }`  **说明**  field property 中包含关联的 sheetId，配合这里返回的 recordId，可以通过调用[获取记录](/zh/open/development/api-getrecord)接口去获取关联记录的值。                  |
| 双向关联    | bidirectionalLink  | `{ "linkedRecordIds": ["xxx", "yyy"] }`                  | `{ "linkedRecordIds": ["xxx", "yyy"] }`                                                                                                                                       |
| 链接      | url                | `{ "text": "Dingtalk", "link": "https://dingtalk.io" }`  | `{ "text": "Dingtalk", "link": "https://dingtalk.io" }`                                                                                                                       |