数据

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

list()

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)

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)

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

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

读取结构

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

{
  "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 内，与读取接口不同。请参阅写入与删除。

数据模型与边界

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

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

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

同一实例里的读取复用

list() 和 get() 会在当前应用实例里短暂记住结果，并把同时发出的相同请求合并成一次。缓存只活在这一次打开的页面里，关闭应用、撤销授权或切换账号后不会继续使用。它不是权限判断，也不是数据已经保存成功的证明。

插入、更新或删除记录后，只会放弃这次操作对应的数据集元数据。其他数据集的 get() 结果可以继续复用。记录分页不进入这个缓存；需要最新记录时调用 query()。

同一页要读取多个数据集时，用 Promise.all() 同时发起，每个调用仍然只访问自己已授权的数据集：

const [memos, tags, total] = await Promise.all([
  platform.data.query(memoTable.id, { limit: 30, orderBy: { field: "created_at", dir: "desc" } }),
  platform.data.query(tagTable.id, { limit: 30 }),
  platform.data.count(memoTable.id),
]);
const more = await platform.data.query(memoTable.id, {
  limit: 30,
  offset: memos.length,
  orderBy: { field: "created_at", dir: "desc" },
});

打开页面时读取第一页和总数。用户继续浏览时再请求下一页。不要在入口里循环读完整张表。

先画出可交互的页面骨架，再异步读取数据。读取失败时保留骨架，并提供重试；不要在入口函数里串行等待用户、全部数据集和全部记录之后才第一次渲染。

兼容接口

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