数据库
这是什么 / 何时用
TablesDB 是 Agentbase 的结构化数据库面:数据库 → 表 → 列 / 索引 → 行,支持事务、批量、聚合与行级权限(权限模型见 permissions.md)。新项目一律优先 TablesDB;DocumentsDB(collection / document 语义)是旧文档面,仅维护旧数据或明确需要 Documents API 时使用。
前置
项目与 Server API Key(
databases.read/write,行操作另需tables.*/rows.*中与代码实际 API 匹配的 scope);表级权限应由服务端 / Console 配置。查询用 SDK 的
Query构造器;ID 用ID.unique()。列类型与索引类型的权威口径:
skills/ob-agentbase/references/tables-schema-types.md(以当前 CE 校验器为准,勿照搬公有云文档)。
使用骨架
建库:
tablesDB.create({ databaseId, name });list/get/update/delete管理生命周期。建表:
createTable({ databaseId, tableId, name, permissions, rowSecurity, enabled, columns, indexes, comment })(permissions、rowSecurity、enabled、columns、indexes、comment均可选)。内联
columns走 Attributes 校验器:type只接受string(配size,可选format: email|enum|ip|url,enum须带elements)、integer、double(注意不是float)、boolean、datetime、point、linestring、polygon。relationship关系列不能内联创建,建表后用createRelationshipColumn。indexes:type取key/unique/fulltext/spatial;attributes只能引用显式业务列,不能引用$id、$createdAt等系统字段。
增量列:表已存在后用
createStringColumn/createVarcharColumn/createTextColumn/createLongtextColumn/createMediumtextColumn/createEmailColumn/createEnumColumn/createUrlColumn/createIpColumn/createIntegerColumn/createFloatColumn/createBooleanColumn/createDatetimeColumn/createPointColumn/createLineColumn/createPolygonColumn/createRelationshipColumn(均有update*Column与getColumn/listColumns/deleteColumn)。增量列多为 202 异步任务,状态从processing到available后才可用于写入。列注释(2.6.0 Node 扩展):
updateColumnComment({ databaseId, tableId, key, comment })(comment可选) 维护列说明。行 CRUD:
createRow/getRow/listRows/updateRow/deleteRow;批量createRows/upsertRows/updateRows/deleteRows;单列原子incrementRowColumn/decrementRowColumn;upsertRow按行 ID 创建或更新。查询:
Query.equal/notEqual/greaterThan/lessThan/between/contains/startsWith/search/in/orderAsc/orderDesc/limit/offset/cursorAfter/cursorBefore/or/and/not等;列表默认分页,total: false可省计数。事务:
createTransaction({ ttl })(ttl可选) →createOperations({ transactionId, operations[] })(action: create/update/upsert/delete/increment/...)→updateTransaction({ commit: true })提交或rollback: true回滚;listTransactions/getTransaction/deleteTransaction管理。行聚合(2.6.0 Node 扩展):
aggregateRows({ databaseId, tableId, select[], queries, groupBy, transactionId })(queries、groupBy、transactionId均可选) 返回聚合行。Schema 版本与回滚(2.6.0 已有):
createSchemaVersion({ databaseId, schema, mode })(mode可选)(mode: 'migration'(默认)/'baseline'——仅在把当前运行结构采纳为第一个生效版本时用 baseline);getSchemaVersion/listSchemaVersions({ databaseId, queries, total })(queries、total均可选)(按版本号倒序);rollbackSchemaVersion({ databaseId, versionId })把生效指针切回历史版本——只更新指针,不执行物理 DDL、不改数据。
关键参数与返回
| 层 | 方法族 | 关键返回 |
|---|---|---|
| 数据库 | create / get / list / update / delete | Models.Database(storageTotal 等元数据) |
| 表 | createTable / getTable / listTables / updateTable / deleteTable | Models.Table(rowSecurity、enabled、$permissions、columns、indexes) |
| 列 | create*Column / update*Column / getColumn / listColumns / deleteColumn / updateColumnComment | 各 ColumnXxx(带 status: processing|available|...) |
| 索引 | createIndex / getIndex / listIndexes / deleteIndex | Models.Index(type: key|unique|fulltext|spatial) |
| 行 | createRow / getRow / listRows / updateRow / upsertRow / deleteRow + 批量/增减 | Models.Row(业务 data + $id、$createdAt、$permissions 等);列表返回 rows/total |
| 事务 | createTransaction / createOperations / updateTransaction / ... | Models.Transaction(状态与操作日志) |
| 聚合 | aggregateRows | Models.RowAggregation |
| Schema 版本 | createSchemaVersion / getSchemaVersion / listSchemaVersions / rollbackSchemaVersion | Models.SchemaVersion(版本号、状态、schemaHash) |
createIndex 的排序参数用 SDK 枚举(如 OrderBy.ASC/DESC),索引用 TablesDBIndexType 等枚举;以各 SDK 导出为准。
错误与边界
400 缺失字段 / 校验失败:内联列用了不支持的顶层
type(如varchar、email)是最常见原因——内联必须string+format;增量列才接受varchar等路径 kind。required: true与default互斥;索引引用系统字段或尚在processing的列会失败。JsonTable 列必填放宽(2.7.0,appbase PR 541):JsonTable 后端的表允许把已有列的
required从true放宽为false,前提是名称、类型、大小、signed、array 均不变——这种「只放宽 required」的更新直达适配层,在单一事务内原子提交 catalog 与元数据,不重建普通/unique/fulltext 索引(字段缺失或为 null 不再产生索引旁表条目,已有非空索引条目继续有效)。混合放宽被拒:放宽的同时改default/format/formatOptions/filters、改名、改类型、缩小大小或改 signed/array 都会以 Conflict 拒绝;required从false收紧回true同样不允许。行级权限下,列表查询只返回调用者有权
read的行(见 permissions.md);updateRows/deleteRows无 queries 时作用于全表,务必带过滤条件。事务中的操作在 commit 前对外不可见;
rollback后操作丢弃。删除事务不回滚已提交操作。大批量写入可使用批量接口并分批,避免单请求超限。事务可将支持的操作作为一个整体提交或回滚,但不自动对重复请求去重;
upsertRow也不保证业务幂等或消除并发冲突。需由应用设计去重和并发控制;提交结果未知时先查询事务状态和数据,再决定是否重试。项目数据库存储 / 表数量超限时返回对应
*_limit_exceeded错误(413 / 创建失败)。
SDK 类别差异
Server SDK(Node / Java / Python 面同构):本页主体;方法名 Node/JS 为驼峰,Python 为 snake_case,Java 为同步方法 + typed model(行
data泛型默认Map,可传Type反序列化为 POJO)。Client SDK(Web):经用户 Session 直接读写行(受行/表权限约束),可建表能力有限——表结构与权限基线由服务端配置;见 client-sdk/web.md。
Console SDK:管理项目 quota / usage 口径(
TablesDB.listUsage/getUsage资源明细),不做业务建表;表结构自动化优先 Server SDK。差异入口:client-sdk/web.md、
console-sdk/nodejs.md、server-sdk/nodejs.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
建库
库是表的上层容器;创建后可 get / list / update / delete 管理生命周期,enabled: false 只挡用户侧访问,API Key 仍可读写。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { TablesDB } from 'agentbase-node-sdk';
const tablesDB = new TablesDB(client);
await tablesDB.create({ databaseId: 'app-db', name: 'App', enabled: true });
await tablesDB.get({ databaseId: 'app-db' });
await tablesDB.list({ queries: [], total: true });
await tablesDB.update({ databaseId: 'app-db', name: 'App2' });
await tablesDB.delete({ databaseId: 'app-db' });// 位置参数形态(可空参数传 null):create / update 为 (databaseId, name, enabled),list 为 (queries, search, total)
tables.create("app-db", "App", true);
tables.get("app-db"); // 元数据(storageTotal 等)
tables.list(null, null, null); // queries / search / total
tables.update("app-db", "App2", true);
tables.delete("app-db");
// enabled: false 只挡用户侧访问,API Key 仍可读写tables_db.create(database_id='app-db', name='App')
tables_db.get(database_id='app-db') # 元数据(storage_total 等)
tables_db.list() # 支持 queries
tables_db.update(database_id='app-db', name='App2')
tables_db.delete(database_id='app-db')
# enabled: false 只挡用户侧访问,API Key 仍可读写;方法名以 agentbase.services.tables_db 源码为准_, err := tables.Create("app-db", "App", tables.WithCreateEnabled(true))
_, err = tables.Get("app-db") // 元数据(StorageTotal 等)
_, err = tables.List() // 支持 queries / search(WithListQueries / WithListSearch)
_, err = tables.Update("app-db", tables.WithUpdateName("App2"), tables.WithUpdateEnabled(true))
_, err = tables.Delete("app-db")
// enabled: false 只挡用户侧访问,API Key 仍可读写curl -X POST "https://<your-endpoint>/v1/tablesdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"databaseId": "app-db", "name": "App", "enabled": true}'
curl -X PUT "https://<your-endpoint>/v1/tablesdb/app-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "App2", "enabled": true}'建表(内联列与索引)
createTable 一次性传入 columns / indexes(同步建表)。内联 columns 走 Attributes 校验器:type 只接受 string(配 size,可选 format: email|enum|ip|url,enum 须带 elements)、integer、double、boolean、datetime、point、linestring、polygon;relationship 关系列不能内联。indexes[].type 取 key / unique / fulltext / spatial,attributes 不能引用系统字段。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
await tablesDB.createTable({
databaseId: 'app-db',
tableId: 'tasks',
name: 'Tasks',
rowSecurity: true,
columns: [
{ key: 'title', type: 'string', size: 256, required: true },
{ key: 'status', type: 'string', size: 64, required: true,
format: 'enum', elements: ['draft', 'published', 'archived'] },
{ key: 'score', type: 'double', required: false },
{ key: 'done', type: 'boolean', required: false },
{ key: 'created_at', type: 'datetime', required: false },
],
indexes: [
{ key: 'idx_title', type: 'unique', attributes: ['title'] },
{ key: 'idx_title_fulltext', type: 'fulltext', attributes: ['title'] },
],
});import io.agentbase.models.DatabaseColumnDefinition;
import io.agentbase.models.DatabaseIndexDefinition;
import io.agentbase.enums.DatabaseSchemaType;
import io.agentbase.enums.DatabaseSchemaIndexType;
import java.util.List;
tables.createTable(
"app-db", "tasks", "Tasks",
null, // permissions
true, // rowSecurity
true, // enabled
List.of(new DatabaseColumnDefinition()
.setKey("title").setType(DatabaseSchemaType.STRING) // 内联列 type 只接受 string(配 size)
.setSize(256L).setRequired(true)),
List.of(new DatabaseIndexDefinition()
.setKey("idx_title").setType(DatabaseSchemaIndexType.UNIQUE)
.setAttributes(List.of("title"))), // attributes 引用显式业务列,不能引用系统字段
null // comment
);tables_db.create_table(
database_id='app-db',
table_id='tasks',
name='Tasks',
row_security=True,
enabled=True,
columns=[
{'key': 'title', 'type': 'string', 'size': 256, 'required': True},
],
indexes=[
{'key': 'idx_title', 'type': 'unique', 'attributes': ['title']},
],
)
# columns / indexes 为 dict 列表;内联列 type 以 tables-schema-types 口径为准_, err := tables.CreateTable("app-db", "tasks", "Tasks",
tables.WithCreateTableRowSecurity(true),
tables.WithCreateTableEnabled(true),
tables.WithCreateTableColumns([]models.DatabaseColumnDefinition{
{Key: "title", Type: "string", Size: 256, Required: true},
}),
tables.WithCreateTableIndexes([]models.DatabaseIndexDefinition{
{Key: "idx_title", Type: "unique", Attributes: []string{"title"}},
}),
)curl -X POST "https://<your-endpoint>/v1/tablesdb/app-db/tables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tableId": "tasks",
"name": "Tasks",
"rowSecurity": true,
"columns": [
{ "key": "title", "type": "string", "size": 256, "required": true },
{ "key": "done", "type": "boolean", "required": false }
],
"indexes": [
{ "key": "idx_title", "type": "unique", "attributes": ["title"] }
]
}'增量列
表已存在后按类型加列,多为 202 异步任务:status 从 processing 到 available 后才可用于写入。每类均有 update*Column,getColumn / listColumns / deleteColumn 管理。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
// 17 种类型各有 create<Type>Column,例如:
await tablesDB.createStringColumn({
databaseId: 'app-db', tableId: 'tasks',
key: 'nickname', size: 64, required: false,
});
await tablesDB.createIntegerColumn({
databaseId: 'app-db', tableId: 'tasks',
key: 'views', required: false, min: 0,
});
await tablesDB.createRelationshipColumn({
databaseId: 'app-db', tableId: 'tasks',
key: 'owner', relatedTableId: 'users', type: 'manyToOne',
});
const col = await tablesDB.getColumn({ databaseId: 'app-db', tableId: 'tasks', key: 'nickname' });
// col.status === 'available' 后才可写入// 17 族增量列均为位置参数,形如 (databaseId, tableId, key, ...);多为 202 异步任务:
// varchar: createVarcharColumn(db, table, key, size, required, default, array, encrypt)
// integer: createIntegerColumn(db, table, key, required, min, max, default, array)
// relationship: createRelationshipColumn(db, table, relatedTableId, type, twoWay, key, twoWayKey, onDelete)
tables.createVarcharColumn("app-db", "tasks", "nickname", 64L, false, null, null, null);
tables.createIntegerColumn("app-db", "tasks", "views", false, 0L, null, null, null);
tables.createRelationshipColumn("app-db", "tasks", "users",
io.agentbase.enums.RelationshipType.MANYTOONE, false, "owner", null, null);
// createStringColumn 自 1.9.0 起废弃,改用 createTextColumn / createVarcharColumn
var col = tables.getColumn("app-db", "tasks", "nickname"); // status == available 后才可写入# 17 种类型各有 create<Type>Column(多为 202 异步任务),例如:
tables_db.create_string_column(database_id='app-db', table_id='tasks',
key='nickname', size=64, required=False)
tables_db.create_relationship_column(database_id='app-db', table_id='tasks', key='owner',
related_table_id='users', type='manyToOne')
col = tables_db.get_column(database_id='app-db', table_id='tasks', key='nickname')
# col.status == 'available' 后才可写入;update_*_column / list_columns / delete_column 对应维护
# 以 agentbase.services.tables_db 源码为准// 17 种类型各有 Create<Type>Column(多为 202 异步任务):
_, err = tables.CreateVarcharColumn("app-db", "tasks", "nickname", 64, false)
_, err = tables.CreateIntegerColumn("app-db", "tasks", "views", false,
tables.WithCreateIntegerColumnMin(0))
_, err = tables.CreateRelationshipColumn("app-db", "tasks", "users", "manyToOne",
tables.WithCreateRelationshipColumnKey("owner")) // RelatedTableId / Type 位置参数;twoWay / key / twoWayKey / onDelete 走 option
col, err := tables.GetColumn("app-db", "tasks", "nickname") // Status == available 后才可写入
_ = col
// UpdateXxxColumn / ListColumns / DeleteColumn 对应维护;CreateStringColumn 已废弃(1.9.0),改用 CreateTextColumn / CreateVarcharColumn# 创建响应 202;GET 轮询至 status=available
curl -X POST "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/columns/varchar" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"key": "nickname", "size": 64, "required": false}'
curl "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/columns/nickname" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"列注释
维护列的展示名(2.6.0 扩展);comment 传空即清除,仅改展示名,通常零 DDL。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
await tablesDB.updateColumnComment({
databaseId: 'app-db', tableId: 'tasks', key: 'title', comment: '任务标题',
});tables.updateColumnComment("app-db", "tasks", "title", "任务标题");tables_db.update_column_comment(database_id='app-db', table_id='tasks',
key='title', comment='任务标题')
# comment 传空即清除;以 agentbase.services.tables_db 源码为准_, err = tables.UpdateColumnComment("app-db", "tasks", "title", "任务标题") // comment 传空即清除curl -X PATCH "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/columns/title/comment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"comment": "任务标题"}'行读写
单条 CRUD、批量(createRows / upsertRows / updateRows / deleteRows)、upsertRow 与单列原子 incrementRowColumn / decrementRowColumn。批量更新/删除无 queries 时作用于全表。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
await tablesDB.createRow('app-db', 'tasks', ID.unique(), { title: '写周报' });
await tablesDB.getRow('app-db', 'tasks', '<rowId>');
await tablesDB.updateRow('app-db', 'tasks', '<rowId>', { done: true });
await tablesDB.upsertRow('app-db', 'tasks', '<rowId>', { title: '写周报', done: false });
await tablesDB.createRows('app-db', 'tasks', [
{ data: { title: 'A' } },
{ data: { title: 'B' } },
]);
await tablesDB.incrementRowColumn('app-db', 'tasks', '<rowId>', 'views', 1); // 越界(max/min)抛错
await tablesDB.deleteRow('app-db', 'tasks', '<rowId>');import { ID, Query } from 'agentbase-web-sdk';
const tablesDB = new TablesDB(client); // 用户 Session;仅行读写面
await tablesDB.createRow({
databaseId: 'app-db', tableId: 'tasks',
rowId: ID.unique(), data: { title: '写周报' },
});
const one = await tablesDB.getRow({ databaseId: 'app-db', tableId: 'tasks', rowId: '<rowId>' });
await tablesDB.updateRow({
databaseId: 'app-db', tableId: 'tasks', rowId: '<rowId>', data: { done: true },
});
const page = await tablesDB.listRows({
databaseId: 'app-db', tableId: 'tasks', queries: [Query.limit(25)],
});
await tablesDB.deleteRow({ databaseId: 'app-db', tableId: 'tasks', rowId: '<rowId>' });
// 受行/表权限约束;无建库建表面Row<Map<String, Object>> row = tables.createRow(
"app-db", "tasks", ID.unique(),
Map.of("title", "写周报", "done", false),
null, // permissions:省略则用表默认
null // transactionId
);
RowList<Map<String, Object>> open = tables.listRows(
"app-db", "tasks",
List.of(Query.equal("done", false), Query.limit(25)),
null, true, null
);
tables.updateRow("app-db", "tasks", row.getId(), Map.of("done", true), null, null);
tables.deleteRow("app-db", "tasks", row.getId(), null);
// 批量:createRows(db, table, transactionId);updateRows(db, table, data, queries, transactionId);
// deleteRows(db, table, queries, transactionId);updateRows / deleteRows 无 queries 时作用于全表tables_db.create_row(
database_id='app-db', table_id='tasks', row_id=ID.unique(),
data={'title': '写周报'},
)
one = tables_db.get_row(database_id='app-db', table_id='tasks', row_id='<row_id>')
tables_db.update_row(database_id='app-db', table_id='tasks', row_id='<row_id>',
data={'done': True})
tables_db.upsert_row(database_id='app-db', table_id='tasks', row_id='<row_id>',
data={'title': '写周报', 'done': False}) # 创建或更新该行
rows = tables_db.list_rows(
database_id='app-db', table_id='tasks',
queries=[Query.order_desc('$createdAt'), Query.limit(25)],
total=False,
)
tables_db.increment_row_column(database_id='app-db', table_id='tasks',
row_id='<row_id>', column='views', value=1) # 越界(max/min)抛错
tables_db.delete_row(database_id='app-db', table_id='tasks', row_id='<row_id>')
# 批量 create_rows / upsert_rows / update_rows / delete_rows;
# update_rows / delete_rows 无 queries 时作用全表_, err := tables.CreateRow("app-db", "tasks", id.Unique(),
map[string]interface{}{"title": "写周报"}) // Data 为位置参数
one, err := tables.GetRow("app-db", "tasks", "<rowId>")
payload := map[string]interface{}{}
_ = one.Decode(&payload) // 业务字段经 Decode 取原始 JSON
_, err = tables.UpdateRow("app-db", "tasks", "<rowId>",
tables.WithUpdateRowData(map[string]interface{}{"done": true}))
_, err = tables.UpsertRow("app-db", "tasks", "<rowId>",
tables.WithUpsertRowData(map[string]interface{}{"title": "写周报", "done": false})) // 创建或更新该行
rows, err := tables.ListRows("app-db", "tasks",
tables.WithListRowsQueries([]string{query.OrderDesc("$createdAt"), query.Limit(25)}))
_, err = tables.IncrementRowColumn("app-db", "tasks", "<rowId>", "views",
tables.WithIncrementRowColumnValue(1)) // 越界(max/min)抛错
_, err = tables.DeleteRow("app-db", "tasks", "<rowId>")
// CreateRows / UpsertRows / UpdateRows / DeleteRows 同构;UpdateRows / DeleteRows 无 queries 作用全表curl -X POST "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rowId": "r1", "data": {"title": "写周报"}}'
curl -X PUT "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/rows/r1" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "写周报", "done": false}}' # upsert
curl -X PATCH "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/rows/r1/views/increment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"value": 1}'
curl -X PATCH "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"data": {"done": true}, "queries": ["equal(\"done\", false)"]}'查询与分页
Query 构造器组合过滤、排序、分页与游标;列表默认返回 total,total: false 可省计数。REST 侧查询是可重复的 queries[] 参数。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Query } from 'agentbase-node-sdk';
const rows = await tablesDB.listRows('app-db', 'tasks', [
Query.equal('done', false),
Query.greaterThan('score', 60),
Query.orderDesc('$createdAt'),
Query.limit(25),
Query.cursorAfter('<lastId>'),
]);const rows = await tablesDB.listRows({
databaseId: 'app-db', tableId: 'tasks',
queries: [Query.equal('done', false), Query.orderDesc('$createdAt'), Query.limit(25)],
});RowList<Map<String, Object>> rows = tables.listRows(
"app-db", "tasks",
List.of(
Query.equal("done", false),
Query.orderDesc("$createdAt"),
Query.limit(25)
),
null, true, null
);rows = tables_db.list_rows(
database_id='app-db', table_id='tasks',
queries=[
Query.equal('done', False),
Query.order_desc('$createdAt'),
Query.limit(25),
],
total=False,
)rows, err := tables.ListRows("app-db", "tasks",
tables.WithListRowsQueries([]string{
query.Equal("done", false),
query.OrderDesc("$createdAt"),
query.Limit(25),
}))curl -G "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
--data-urlencode 'queries[]=equal("done", false)' \
--data-urlencode 'queries[]=orderDesc("$createdAt")' \
--data-urlencode 'queries[]=limit(25)' \
--data-urlencode 'total=false'事务
事务是项目级对象:创建 → 暂存操作(可分多次追加)→ 提交或回滚。commit 前操作对外不可见;行读写端点也可传 transactionId 挂到事务。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const tx = await tablesDB.createTransaction({ ttl: 60 });
await tablesDB.createOperations({
transactionId: tx.$id,
operations: [
{ databaseId: 'app-db', tableId: 'tasks', action: 'create', rowId: ID.unique(), data: { title: 'A' } },
{ databaseId: 'app-db', tableId: 'tasks', action: 'update', rowId: '<rowId>', data: { done: true } },
],
});
await tablesDB.updateTransaction({ transactionId: tx.$id, commit: true });
// 或 rollback: true 丢弃import io.agentbase.ID;
import io.agentbase.enums.TransactionAction;
import io.agentbase.models.TablesDBTransactionOperation;
var tx = tables.createTransaction(null); // ttl 可传秒数
tables.createOperations(tx.getId(), List.of(
new TablesDBTransactionOperation("app-db", "tasks", TransactionAction.CREATE)
.setRowId(ID.unique())
.setData(Map.of("title", "A"))));
tables.updateTransaction(tx.getId(), true, null); // commit 提交;rollback 传 true 丢弃
// 方法族还有 listTransactions / getTransaction / deleteTransaction;
// action 取值见 TransactionAction(create/update/upsert/delete/increment/decrement 等)tx = tables_db.create_transaction(ttl=60)
tables_db.create_operations(
transaction_id=tx['$id'],
operations=[{
'databaseId': 'app-db',
'tableId': 'tasks',
'action': 'create',
'rowId': 'r1',
'data': {'title': 'A'},
}],
)
tables_db.update_transaction(transaction_id=tx['$id'], commit=True) # 或 rollback=Truetx, err := tables.CreateTransaction()
_, err = tables.CreateOperations(tx.Id,
tables.WithCreateOperationsOperations([]models.TablesDBTransactionOperation{{
DatabaseId: "app-db",
TableId: "tasks",
Action: "create",
RowId: "r1",
Data: map[string]interface{}{"title": "A"},
}}))
_, err = tables.UpdateTransaction(tx.Id, tables.WithUpdateTransactionCommit(true))curl -X POST "https://<your-endpoint>/v1/tablesdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl": 60}'
curl -X POST "https://<your-endpoint>/v1/tablesdb/transactions/<transactionId>/operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operations": [{"databaseId": "app-db", "tableId": "tasks", "action": "create", "rowId": "r1", "data": {"title": "A"}}]}'
curl -X PATCH "https://<your-endpoint>/v1/tablesdb/transactions/<transactionId>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"commit": true}'行聚合
服务端聚合(count / sum / avg / min / max,可分组),不拉全表;普通列必须出现在 groupBy,queries 仅接受过滤条件。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const stats = await tablesDB.aggregateRows({
databaseId: 'app-db',
tableId: 'tasks',
select: ['count'],
queries: [Query.equal('done', false)],
groupBy: ['done'],
});var agg = tables.aggregateRows(
"app-db", "tasks",
List.of("count"), // select:聚合函数
List.of(Query.equal("done", false)), // 过滤
List.of("done"), // groupBy
null // transactionId
);stats = tables_db.aggregate_rows(
database_id='app-db', table_id='tasks',
select=['count'], # 聚合函数
queries=[Query.equal('done', False)], # 仅接受过滤条件
group_by=['done']) # 普通列必须出现在 group_bystats, err := tables.AggregateRows("app-db", "tasks", []string{"count"}, // Select 为位置参数
tables.WithAggregateRowsQueries([]string{query.Equal("done", false)}),
tables.WithAggregateRowsGroupBy([]string{"done"}))
_ = statscurl -G "https://<your-endpoint>/v1/tablesdb/app-db/tables/tasks/aggregation" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
--data-urlencode 'select[]=count(*) AS totalRows' \
--data-urlencode 'select[]=done' \
--data-urlencode 'groupBy[]=done' \
--data-urlencode 'queries[]=equal("done", false)'Schema 版本与回滚
提交完整结构 JSON(不是 diff patch)生成版本并自动迁移,轮询版本终态;mode 缺省 migration,baseline 仅在把当前物理结构采纳为首活跃版本时用。回滚只切换生效指针(重算列可见性),不执行物理 DDL、不改数据。同一数据库同时只允许一个 in-flight 版本(重复提交 409)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const before = await tablesDB.listSchemaVersions({ databaseId: 'app-db', queries: [], total: true });
// 保存当前 active 版本 id 作为回滚锚点
const submitted = await tablesDB.createSchemaVersion({
databaseId: 'app-db',
schema: { tables: [/* 已 review 的完整结构 JSON */] },
});
const v = await tablesDB.getSchemaVersion({ databaseId: 'app-db', versionId: submitted.$id });
// 轮询至 status: active / failed(stepsCompleted / stepsTotal / errorMessage 可观测)
// 仅当完成兼容性评审后回滚:
// await tablesDB.rollbackSchemaVersion({ databaseId: 'app-db', versionId: '<activeVersionId>' });tables.listSchemaVersions("app-db", null, null);
var v2 = tables.createSchemaVersion("app-db", schema, io.agentbase.enums.Mode.MIGRATION); // mode:MIGRATION(缺省)/ BASELINE
tables.getSchemaVersion("app-db", v2.getId());
tables.rollbackSchemaVersion("app-db", v2.getId()); // 只切指针,不执行物理 DDLversions = tables_db.list_schema_versions(database_id='app-db', total=True)
# 保存当前 active 版本 id 作为回滚锚点
submitted = tables_db.create_schema_version(
database_id='app-db', schema={'tables': []}) # schema 传完整结构 JSON;mode 缺省 migration
v = tables_db.get_schema_version(database_id='app-db', version_id=submitted['$id'])
# 轮询至 status: active / failed(stepsCompleted / stepsTotal / errorMessage 可观测)
# 仅当完成兼容性评审后回滚(只更新指针,不执行物理 DDL、不改数据):
# tables_db.rollback_schema_version(database_id='app-db', version_id='<active_version_id>')versions, err := tables.ListSchemaVersions("app-db")
_ = versions // 保存当前 active 版本 id 作为回滚锚点
submitted, err := tables.CreateSchemaVersion("app-db",
map[string]interface{}{"tables": []interface{}{}}) // schema 为位置参数,传完整结构 JSON;mode 缺省 migration
v, err := tables.GetSchemaVersion("app-db", submitted.Id) // 轮询至 status: active / failed
_ = v
// 仅当完成兼容性评审后回滚(只更新指针,不执行物理 DDL、不改数据):
// tables.RollbackSchemaVersion("app-db", "<activeVersionId>")操作 1(单独执行)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/tablesdb/app-db/schema/versions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "Content-Type: application/json" \
-d '{"schema": {"tables": []}, "mode": "migration"}'
)操作 2(单独执行)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- "https://<your-endpoint>/v1/tablesdb/app-db/schema/versions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>"
)操作 3(单独执行)。仅在确认目标与影响后单独执行。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/tablesdb/app-db/schema/rollback/1" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>"
)示例指引
各语言写法集中在语言树
examples/;建库→建表(内联列/索引)→事务→聚合的完整序列与列类型对照见skills/ob-agentbase/references/tables-schema-types.md、skills/ob-agentbase/references/server-sdks/nodejs.md。