# 数据

`platform.data` 提供当前用户的数据访问能力。应用没有独立业务后端，不需要自己处理登录和 HTTP 请求。

## list()

```js
const datasets = await platform.data.list();
```

返回 `Promise<Dataset[]>`。每个数据集包含 `id`、`name`、`slug`、`schema`、`created_at`、`updated_at` 等元数据。`schema.fields` 定义业务字段，字段类型包括 `string`、`number`、`boolean`、`datetime`、`json`，`required: true` 表示必填。

绑定了 `table_ids` 的应用只会列出绑定的数据集；未绑定且获全空间授权时会列出当前用户全部数据集。记录查询、更新和删除也受相同授权范围限制。不要把列表顺序当成固定顺序，也不要随意选择第一个数据集作为业务存储。

## get(idOrSlug)

```js
const todos = await platform.data.get("todo");
const rows = await platform.data.query(todos.id);
```

按数据集 ID 或 slug 查找，返回 `Promise<Dataset>`。不能按显示名称查找；名称和 slug 未必相同。数据集不存在或不在发现范围时会报错。

后续的查询与写入方法使用 `todos.id`，不要把 slug 直接传给 `query` 或 `insert`。

## getRecord(datasetId, recordId)

```js
const row = await platform.data.getRecord(todos.id, recordId);
console.log(row.title, row.done);
```

返回一条字段展开后的记录；不存在时抛出错误，不返回 `null`。

## 读取结构

`query` 和 `getRecord` 将业务数据放在对象顶层：

```json
{
  "id": "RECORD_ID",
  "table_id": "DATASET_ID",
  "title": "取快递",
  "done": false,
  "created_at": "2026-01-01T09:00:00.000Z",
  "updated_at": "2026-01-01T09:00:00.000Z"
}
```

系统字段会覆盖同名的业务字段，不要将 `id`、`table_id`、`created_at`、`updated_at` 用作业务字段名称。

写入返回值保留 `{ id, table_id, data, created_at, updated_at }` 结构，业务字段在 `data` 内，与读取接口不同。请参阅[写入与删除](/doc/api/mutations)。

## 数据模型与边界

应用不能通过 `platform.data` 创建数据集或修改 schema。请在数据库应用或构建会话中完成数据准备。数据库应用支持新增、重命名、删除字段、调整类型、必填与顺序，详见[管理数据表](/doc/database)。逻辑数据集不是物理 SQL 表，不开放 SQL、跨数据集 join 或实时订阅。

推荐为需要筛选、排序的字段使用英文字母或下划线开头的标识符，例如 `title`、`amount`、`created_on`。查询字段支持中英文字母、数字和下划线，不能以数字开头。

数据库仍然位于云端，调用可能失败或产生延迟，应用应显示加载和错误状态。数据不依附应用文件包，替换源码不会清除用户记录。

## 兼容接口

旧应用的 `platform.tables` 仍是 `platform.data` 的别名。`data.list(datasetId)` 仍可作为旧版查询写法使用，但新应用应使用无参数的 `list()` 发现数据集，使用 `query(id, options)` 读取记录。