AppBase 云控制台
浏览全部文档 · 15/37
AppBase 增强已进入 main

Column Comment

Database、Table、Column 与 Row

版本验证信息发布状态与验证 Commit
发布状态
已进入 main
后端验证 Commit
0363062a1c7ea08741975bb5ba0c3361663c9353

功能简介

Column Comment 为技术 key 增加可读说明。它不改变 Row JSON 的字段名，也不执行 rename；更新、清除、SDK 返回和 Schema Version 快照都保留明确语义，适合补充业务含义而不破坏调用方。

当前支持范围

  • Column Comment（APPBASE_ENHANCED）：为 Column 增加不改变技术 key 的可读说明，并在 Console、API、SDK 与 Schema 版本中保持该元数据。

适用场景

  • 为英文技术 key 补充中文业务说明。
  • 在 Console 中降低字段理解成本。
  • 让 Schema Version 历史保留字段说明。

前置条件

  • Database、Table 与目标 Column 已存在。
  • 调用者拥有 tables.write（或兼容 collections.write）管理权限。
  • 明确 Comment 是元数据，不用于程序字段寻址。

Console 操作路径

Console → Project → Databases → Database → Table → Columns。编辑 Column 的显示说明；保存后技术 key 保持不变。空值或清除操作移除 Comment。

SDK 示例

SDK · TypeScript
import { Client, TablesDB } from 'appbase-console-sdk';

const client = new Client()
  .setEndpoint('https://<APPBASE_HOST>/v1')
  .setProject('<PROJECT_ID>')
  .setKey('<API_KEY>');

const tables = new TablesDB(client);
await tables.updateColumnComment({
  databaseId: '<DATABASE_ID>',
  tableId: '<TABLE_ID>',
  key: 'status',
  comment: '业务状态'
});

REST 示例

REST · Bash
curl 'https://<APPBASE_HOST>/v1/tablesdb/<DATABASE_ID>/tables/<TABLE_ID>/columns/status/comment' \
  -X PATCH \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{"comment":"业务状态"}'

权限模型

读取 Column 沿用 Table/Column 读取权限；更新 Comment 需要 tables.write（兼容 collections.write）。Comment 不改变现有 Row Permission，也不会赋予调用者读取数据的能力。

常见错误

现象处理建议
database_column_not_found核对 databaseId、tableId 与技术 key。
403使用具备 Column 管理 Scope 的服务端身份。
并发结构变更冲突等待当前 Schema/Column 变更完成后重试。

当前限制

  • Comment 不是字段别名，不应写入 Query、Row data 或 Index 定义。
  • 清除 Comment 使用 null 或空值语义，具体以 SDK 方法签名为准。
  • 旧 SDK 可能未声明 comment 字段，需升级或直接使用 REST。

Appwrite 兼容说明

上游 Column 概念仍适用；Comment 是 AppBase 独立实现的元数据增强，正文不来自上游文档。

AppBase 增强说明

Comment 贯通 HTTP Action、Console helper、SDK 类型、单元测试与 Schema Version 快照。

发布状态和验证 Commit

origin/main 已核验。验证 Commit：0363062a1c7ea08741975bb5ba0c3361663c9353。

权威来源文件列表

  • backend-candidate:docs/products/v2.3.x/tablesdb/column-comments.md
  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Tables/Columns/Comment/Update.php
  • backend-candidate:tests/unit/Database/ColumnCommentTest.php
  • frontend-candidate:console/src/lib/helpers/column.ts

Appwrite taxonomy 仅作信息架构参考：https://appwrite.io/docs/products/databases。上游页面不是 AppBase 实现证据。

继续阅读