数据库 API
表格数据库全生命周期接口:库、表/集合、列/属性、索引、行/文档的 CRUD 与批量操作、事务、行聚合,以及 Schema 版本与回滚。本域覆盖三个并存的 service 面:
- **
TablesDB**(/tablesdb):TablesDB 主面,强 schema(表 → 列 → 行)。 - **
DocumentsDB**(/documentsdb):文档型面,集合下直接存文档,列定义可选。 - **
Databases**(/databases):旧版兼容面(collection / attribute / document 术语),语义与 TablesDB 同构。
DocumentsDB 与旧版 Databases 没有 /aggregation(行聚合)与 /schema/versions(Schema 版本)端点——这两个能力只在 TablesDB 面。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1;三个前缀:/tablesdb、/documentsdb、/databases。 - 层级:数据库
{databaseId}→ 表{tableId}(集合{collectionId})→ 行{rowId}(文档{documentId})。 - ID 约束统一:自定义 ID 用 a-z、A-Z、0-9、
.、-、_,不能以特殊字符开头,最长 36 字符。
认证与权限
认证与请求头约定见 通用约定。本域 scope:
| scope | 覆盖 |
|---|---|
databases.read / databases.write | 库级与 Schema 版本操作 |
tables.read / tables.write(兼容 collections.read / collections.write) | 表/集合、列/属性、索引操作 |
rows.read / rows.write(兼容 documents.read / documents.write) | 行/文档读写与事务 |
scope 数组为新旧命名兼容别名,Key 持有其一即可。资源级权限(rowSecurity / documentSecurity 与行/文档 $permissions)的语义见 permissions;API Key 访问不受资源级权限约束。
端点清单
TablesDB(/tablesdb,74 个端点)
| 方法 + 路径 | 用途 |
|---|---|
GET /tablesdb | 列出库 |
POST /tablesdb | 创建库 |
GET /tablesdb/{databaseId} | 获取库 |
PUT /tablesdb/{databaseId} | 更新库名称/启用态 |
DELETE /tablesdb/{databaseId} | 删除库 |
GET /tablesdb/{databaseId}/tables | 列出表 |
POST /tablesdb/{databaseId}/tables | 创建表(可携完整 columns/indexes 定义) |
GET /tablesdb/{databaseId}/tables/{tableId} | 获取表 |
PUT /tablesdb/{databaseId}/tables/{tableId} | 更新表(含整表结构提交) |
DELETE /tablesdb/{databaseId}/tables/{tableId} | 删除表 |
GET /tablesdb/{databaseId}/tables/{tableId}/columns | 列出列 |
POST /tablesdb/{databaseId}/tables/{tableId}/columns/{type} | 创建列(type ∈ 17 种,见下) |
GET /tablesdb/{databaseId}/tables/{tableId}/columns/{key} | 获取列 |
PATCH /tablesdb/{databaseId}/tables/{tableId}/columns/{type}/{key} | 更新列 |
PATCH /tablesdb/{databaseId}/tables/{tableId}/columns/{key}/comment | 更新列注释(展示名) |
PATCH /tablesdb/{databaseId}/tables/{tableId}/columns/{key}/relationship | 更新关系列 |
DELETE /tablesdb/{databaseId}/tables/{tableId}/columns/{key} | 删除列 |
GET /tablesdb/{databaseId}/tables/{tableId}/indexes | 列出索引 |
POST /tablesdb/{databaseId}/tables/{tableId}/indexes | 创建索引 |
GET /tablesdb/{databaseId}/tables/{tableId}/indexes/{key} | 获取索引 |
DELETE /tablesdb/{databaseId}/tables/{tableId}/indexes/{key} | 删除索引 |
GET /tablesdb/{databaseId}/tables/{tableId}/rows | 列出行(查询/分页/缓存 TTL) |
POST /tablesdb/{databaseId}/tables/{tableId}/rows | 创建行(单条 body)或批量建行(createRows) |
GET /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | 获取行 |
PUT /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | upsert 行 |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | 更新行 |
DELETE /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | 删除行 |
PUT /tablesdb/{databaseId}/tables/{tableId}/rows | 批量 upsert 行 |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows | 按查询批量更新行 |
DELETE /tablesdb/{databaseId}/tables/{tableId}/rows | 按查询批量删除行 |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/increment | 列值自增 |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/decrement | 列值自减 |
GET /tablesdb/{databaseId}/tables/{tableId}/aggregation | 行聚合(count/sum/avg/min/max) |
GET /tablesdb/transactions | 列出事务 |
POST /tablesdb/transactions | 创建事务 |
GET /tablesdb/transactions/{transactionId} | 获取事务 |
PATCH /tablesdb/transactions/{transactionId} | 提交/回滚事务 |
POST /tablesdb/transactions/{transactionId}/operations | 批量暂存事务操作 |
DELETE /tablesdb/transactions/{transactionId} | 删除事务 |
GET /tablesdb/{databaseId}/schema/versions | 列出 Schema 版本 |
POST /tablesdb/{databaseId}/schema/versions | 提交 Schema 版本 |
GET /tablesdb/{databaseId}/schema/versions/{versionId} | 获取 Schema 版本 |
POST /tablesdb/{databaseId}/schema/rollback/{versionId} | 回滚到指定 Schema 版本 |
DocumentsDB(/documentsdb,31 个端点)与旧版 Databases(/databases,68 个端点)
- DocumentsDB:库(5 + 事务 6 + 单库读改删)与集合面(20:集合 5、文档单条/批量 CRUD 11、索引 4)。
- 旧版 Databases:库与事务同构(5 + 6 + 单库读改删);集合面 57 端点:集合 CRUD(5)、
/attributes/*属性端点组(37:17 种类型各自的创建与更新端点 + 属性列表与单项读删)、索引(4)、文档单条/批量 CRUD 与increment/decrement(11)。
两个面的端点形态与 TablesDB 完全同构,术语对照:table ↔ collection、row ↔ document、column ↔ attribute。差异只有两处:无 /aggregation 与 /schema/*;旧版属性与索引是独立端点组(POST .../attributes/{type}、POST .../indexes),DocumentsDB 的集合级 attributes 数组在创建/更新集合时一并提交。逐端点完整规格见下方三节。
示例约定
本节起的逐端点示例共用以下约定,替换占位值即可直接复制执行:
- Base URL:
https://<your-endpoint>/v1;认证用两枚请求头:X-Appwrite-Project: <YOUR_PROJECT_ID>、X-Appwrite-Key: <YOUR_API_KEY>;写请求另加Content-Type: application/json。 - 演示值:TablesDB 用库
movie-db+ 表films,DocumentsDB 用notes-db+notes,旧版 Databases 用shop-db+orders;均为演示数据,非真实业务值。 - 列表端点的
queries是可重复的 query 参数,元素为 Query 方法字符串。GET 请求用curl -G+--data-urlencode传递:
# Query.equal('genre','animation') →
--data-urlencode 'queries[]=equal("genre","animation")'
# Query.limit(25) →
--data-urlencode 'queries[]=limit(25)'其余如 orderDesc("$createdAt")、cursorAfter("…") 同理;单端点最多 100 条。
- 行/文档 CRUD 示例中的
data键与各面演示表的列/属性对应(如films的title/year/genre/rating/watched)。
请求与响应
库(database)
POST /tablesdb:bodydatabaseId(必填)、name(必填,最长 128)、enabled(可选,默认 true)。enabled=false时用户侧不可访问,但持 API Key 的服务端仍可读写,数据不丢失。返回201+database($id、name、enabled、type、$createdAt、$updatedAt)。GET /tablesdb:queries(可过滤name)、search、total;返回databaseList。PUT /tablesdb/{databaseId}:name、enabled均可选;返回database。DELETE /tablesdb/{databaseId}:返回204。
表与集合
POST /tablesdb/{databaseId}/tables:tableId+name必填;可选permissions(权限字符串数组,默认不授予任何用户角色)、rowSecurity(默认 false)、enabled、columns(建表即建列的完整定义数组)、indexes、comment(展示名,最长 256 Unicode)。返回201+table($id、databaseId、name、rowSecurity、enabled、columns、indexes、bytesMax、bytesUsed等)。PUT .../tables/{tableId}:name、permissions、rowSecurity、enabled、columns、indexes、skipOnEmpty、comment。columns为整表结构提交:含previousKey可实现改名不删列;空数组配合skipOnEmpty=false表示清空全部用户定义结构。返回table。- 集合(documentsdb / databases 两面):
collectionId+name必填,其余同构(documentSecurity对应rowSecurity)。返回collection。 - 列出表/集合:
queries(可过滤name)、search、total;返回tableList/collectionList。
列(17 种类型)
POST .../columns/{type} 创建;PATCH .../columns/{type}/{key} 更新;GET .../columns/{key}、DELETE .../columns/{key} 读取/删除。创建响应为 202(异步建列),更新响应为 200。列类型与专有参数:
| type | 专有参数(除 key、required 外) |
|---|---|
string | size(必填,字符数)、default、array、encrypt(加密后不可查询) |
varchar | size(必填,最大 16381)、default、array、encrypt |
text / mediumtext / longtext | default、array、encrypt |
email / url / ip | default、array |
integer | min、max、default、array |
float | min、max、default、array |
boolean | default、array |
datetime | default(ISO 8601)、array |
enum | elements(必填,枚举值数组)、default、array |
point | default([longitude, latitude]) |
line | default(二维坐标对数组) |
polygon | default(三维环数组,首环为外边界) |
relationship | type(必填:oneToOne/manyToOne/manyToMany/oneToMany)、twoWay、twoWayKey、onDelete(cascade/restrict/setNull);无 required |
通用可选 array 表示数组列。更新端点公共参数:required(必填)、default(必填)、newKey(改名)。关系列的更新走独立端点(onDelete、newKey)。PATCH .../columns/{key}/comment:body comment(必填;null 或空白清除),仅改展示名,通常零 DDL。
2.7.0 起 JsonTable 后端允许孤立的必填放宽(appbase PR 541):仅把 required 从 true 改为 false 且名称/类型/大小/signed/array 均不变时,更新直达适配层并在单一事务内原子生效,不重建索引;放宽若与 default、format、formatOptions、filters 或改名/类型/大小变化混合提交则会被拒绝(Conflict),required 由 false 收紧为 true 也不支持。REST 端点与参数面无变化,变化的是服务端对这类更新的接受边界。
旧版属性端点(/databases/.../attributes/{type})参数与列完全同构;返回模型名为 attribute*。
索引
POST .../indexes:key(必填)、type(必填:key/fulltext/unique/spatial)、columns/attributes(必填,最多 100 个、每个 32 字符)、orders(可选,ASC/DESC数组)、lengths(可选)。响应202+ 索引模型(TablesDB 为columnIndex,其余为index)。- 列出:
queries(可过滤key、type、status)、total;GET .../indexes/{key}、DELETE .../indexes/{key}。
行 / 文档
POST .../rows:单条形态 bodyrowId、data、permissions、transactionId(均可选;data为列值对象);同端点批量形态(SDKcreateRows)body 为rows(必填)+transactionId。返回201+row或rowList。GET .../rows:queries(查询/过滤/排序/分页)、transactionId(读事务内未提交变更)、total、ttl(select 查询的缓存 TTL,0–86400 秒,需实例开启缓存);返回rowList(total+rows[])。row含$id、$sequence、$tableId、$databaseId、$createdAt、$updatedAt、$permissions与数据列。GET .../rows/{rowId}:queries、transactionId;返回row。PUT .../rows/{rowId}(upsert):存在则更新、不存在则创建;bodydata(需含全部必填列)、permissions。返回201+row。PATCH .../rows/{rowId}:data只含需更新的列值,permissions可选;返回row。DELETE .../rows/{rowId}:bodytransactionId可选;返回204。- 批量:
PUT .../rows(rows必填,可为部分行)→201+rowList;PATCH .../rows(data+queries)与DELETE .../rows(queries)→rowList(返回受影响行)。 PATCH .../rows/{rowId}/{column}/increment|decrement:value(默认 1)、max/min(越界抛错)、transactionId;返回row。仅数值列。- 文档(documentsdb / databases 两面):同构,
documentId/document/documentList,批量更新按data+queries。
聚合(仅 TablesDB)
GET /tablesdb/{databaseId}/tables/{tableId}/aggregation:
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
select | query | 是 | 聚合表达式与分组列,支持 count/sum/avg/min/max 与 AS 别名;普通列必须出现在 groupBy |
groupBy | query | 否 | 分组列,最多 5 个标量列 |
queries | query | 否 | 仅过滤查询;分页、排序、游标、Query.select 不支持(会被拒绝) |
transactionId | query | 否 | 读事务内未提交变更 |
返回 200 + rowAggregation(total + 聚合结果行)。
事务
POST /tablesdb/transactions:bodyttl(可选,秒);返回201+transaction($id、status、operations、expiresAt)。POST /tablesdb/transactions/{transactionId}/operations:bodyoperations(暂存操作数组:读/建/更/删、upsert、增量),可分多次追加;返回201+transaction。PATCH /tablesdb/transactions/{transactionId}:commit=true提交或rollback=true回滚(二选一);返回transaction。GET .../transactions、GET .../transactions/{transactionId}、DELETE .../transactions/{transactionId}:列表/详情/删除。- 行/文档读写端点均可传
transactionId把操作挂到事务;事务过期(TTL)后未提交操作作废。documentsdb / databases / vectorsdb 各自有同构的事务端点组。
Schema 版本与回滚(仅 TablesDB)
POST /tablesdb/{databaseId}/schema/versions:bodyschema(必填,含tables数组的完整结构 JSON,不是 diff patch)、mode(可选:migration(默认,对 active 版本做 diff 并执行迁移)/baseline(把当前物理结构采纳为首活跃版本,不执行 DDL))。重复提交相同schemaHash复用已有版本。返回201(新版本)或200(复用)+schemaVersion。schemaVersion模型:$id、databaseId、schemaJson、schemaVersion、schemaHash、status、migrationPlanJson、stepsTotal、stepsCompleted、errorMessage、lastHeartbeatAt、deprecatedColumns。status生命周期:处理中(pending/running/applying)→active/failed/deprecated;同一数据库同时只允许一个 in-flight 版本,重复提交返回409。GET .../schema/versions:queries(可过滤/排序schemaVersion、status、databaseId、schemaHash)、total;按版本号降序。POST /tablesdb/{databaseId}/schema/rollback/{versionId}:回滚到历史版本;只切换结构可见性(重算列可见性),不执行物理 DDL、不撤销业务数据。返回200+schemaVersion。- 激活前校验:迁移 Worker 在应用计划后重读实际表/列/索引,物理结构与目标快照一致才激活;materialization 不完整时标记
failed并保留原 active 版本。调用方轮询版本终态即可,不应自行重放 DDL。
TablesDB 逐端点规格(/tablesdb,74 个端点)
库(database)
database 模型字段:
| 字段 | 说明 |
|---|---|
$id | 库 ID |
name | 名称(≤128 字符) |
$createdAt / $updatedAt | 创建/更新时间(ISO 8601) |
enabled | 启用态;停用只挡用户侧访问,API Key 仍可读写,不丢数据 |
type | 库类型:legacy / tablesdb / documentsdb / vectorsdb |
列表响应 databaseList:total(匹配总数)+ databases[]。
GET /v1/tablesdb
分页列出当前项目的库,支持 queries 过滤与 search 搜索。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
search | query | string | 否 | 关键词搜索,最长 256 字符。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/tablesdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Films")' \
--data-urlencode 'queries[]=limit(50)'输出:200 + Models.DatabaseList。
响应示例
{
"total": 1,
"databases": [
{
"$id": "movie-db",
"name": "Movies",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "tablesdb"
}
]
}POST /v1/tablesdb
创建库。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | body | string | 是 | 数据库唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"databaseId": "movie-db", "name": "Movies", "enabled": true}'输出:201 + Models.Database。
响应示例
{
"$id": "movie-db",
"name": "Movies",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "tablesdb"
}GET /v1/tablesdb/{databaseId}
按 ID 获取库详情。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Database。
响应示例:与同组上文已展示的 Models.Database 示例同构。
PUT /v1/tablesdb/{databaseId}
更新库名称与启用态。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
name | body | string | 否 | 名称,最长 128 字符。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Films", "enabled": true}'输出:200 + Models.Database。
响应示例:与同组上文已展示的 Models.Database 示例同构。
DELETE /v1/tablesdb/{databaseId}
按 ID 删除库。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
表(table)
table 模型字段:
| 字段 | 说明 |
|---|---|
$id | 表 ID |
databaseId | 所属库 ID |
name | 名称(≤128 字符) |
comment | 展示名(≤256 Unicode 字符,可空) |
$permissions | 表级权限字符串数组 |
enabled | 启用态;停用只挡用户侧访问 |
rowSecurity | 是否启用行级权限 |
columns[] | 列定义数组(column* 模型,见「列」小节) |
indexes[] | 索引数组(columnIndex 模型,见「索引」小节) |
bytesMax / bytesUsed | 表容量配额与已用字节 |
列表响应 tableList:total + tables[]。
GET /v1/tablesdb/{databaseId}/tables
列出库下的表,支持 queries 过滤与 search 搜索。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
search | query | string | 否 | 关键词搜索,最长 256 字符。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Films")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.TableList。
响应示例
{
"total": 1,
"tables": [
{
"$id": "films",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "movie-db",
"name": "Films",
"comment": "影片库",
"enabled": true,
"rowSecurity": true,
"bytesMax": 52428800,
"bytesUsed": 20480,
"columns": [
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}
],
"indexes": [
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}
]
}POST /v1/tablesdb/{databaseId}/tables
创建表,可在请求体中携带完整的 columns/indexes 定义。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | body | string | 是 | 表唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
rowSecurity | body | boolean | 否 | 是否启用行级权限;启用后访问单行需持有行级或表级权限之一。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 | |
columns | body | object[] | 否 | 建表即建列的列定义数组(key、type 必填;type ∈ string/varchar/text/mediumtext/longtext/integer/double/boolean/datetime/point/linestring/polygon,枚举用 type=string + format=enum + elements)。关系列必须走独立端点;含 previousKey 可改名不删列。 | |
indexes | body | object[] | 否 | 建表/集合即建索引的定义数组(key、type、attributes 必填;orders、lengths 可选)。 | |
comment | body | string | 否 | 展示名/注释,最长 256 Unicode 字符;首尾空白会被裁剪,null 或空白清除注释。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"tableId": "films", "name": "Films", "permissions": ["read(\"any\")"], "rowSecurity": true, "columns": [{"key": "title", "type": "string", "size": 128, "required": true}, {"key": "year", "type": "integer"}, {"key": "genre", "type": "string", "size": 16, "format": "enum", "elements": ["sci-fi", "drama", "animation"]}, {"key": "rating", "type": "double", "required": false}], "indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}], "comment": "影片库"}'输出:201 + Models.Table。
响应示例
{
"$id": "films",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "movie-db",
"name": "Films",
"comment": "影片库",
"enabled": true,
"rowSecurity": true,
"bytesMax": 52428800,
"bytesUsed": 20480,
"columns": [
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}
],
"indexes": [
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/tablesdb/{databaseId}/tables/{tableId}
获取表详情(含列、索引定义与容量信息)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Table。
响应示例:与同组上文已展示的 Models.Table 示例同构。
PUT /v1/tablesdb/{databaseId}/tables/{tableId}
更新表属性,或提交整表结构(columns/indexes 数组)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
name | body | string | 否 | 名称,最长 128 字符。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
rowSecurity | body | boolean | 否 | 是否启用行级权限;启用后访问单行需持有行级或表级权限之一。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 | |
columns | body | object[] | 否 | 建表即建列的列定义数组(key、type 必填;type ∈ string/varchar/text/mediumtext/longtext/integer/double/boolean/datetime/point/linestring/polygon,枚举用 type=string + format=enum + elements)。关系列必须走独立端点;含 previousKey 可改名不删列。 | |
indexes | body | object[] | 否 | 建表/集合即建索引的定义数组(key、type、attributes 必填;orders、lengths 可选)。 | |
skipOnEmpty | body | boolean | 否 | 置 true 时忽略空的 columns/indexes 数组;false(默认)时空数组表示清空全部用户定义结构。 | |
comment | body | string | 否 | 展示名/注释,最长 256 Unicode 字符;首尾空白会被裁剪,null 或空白清除注释。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Films", "enabled": true, "comment": "影片库"}'输出:200 + Models.Table。
响应示例:与同组上文已展示的 Models.Table 示例同构。
DELETE /v1/tablesdb/{databaseId}/tables/{tableId}
删除表。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
列(column,17 种类型)
TablesDB 列模型(Models.ColumnString … Models.ColumnRelationship)公共字段:
| 字段 | 说明 |
|---|---|
key | 列 key |
comment | 展示名/注释 |
type | 类型标识(enum 列的 type 仍为 string,靠 format: "enum" + elements 区分) |
status | available / processing / deleting / stuck / failed |
error | 失败原因(无错误为空串) |
required / array | 必填性 / 是否数组列 |
$createdAt / $updatedAt | 创建/更新时间 |
生命周期要点:
- 创建返回
202(异步 DDL),status从processing→available(或failed);轮询GET …/{key}直到available,再写入依赖该列的数据。 - 更新端点(
PATCH …/{type}/{key})同步返回200;公共参数required、default、newKey(改名),各类型另有专有参数(见各端点表)。 default与required互斥;改required前需保证存量行均有值。
GET /v1/tablesdb/{databaseId}/tables/{tableId}/columns
列出表的全部列(含建列进度 status)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(100)'输出:200 + Models.ColumnList。
响应示例
{
"total": 2,
"columns": [
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/boolean
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | boolean | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/boolean" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "watched", "required": false, "default": false}'输出:202 + Models.ColumnBoolean;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "watched",
"comment": "Watched flag",
"type": "boolean",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/datetime
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/datetime" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "releaseDate", "required": false, "default": "1970-01-01T00:00:00.000+00:00"}'输出:202 + Models.ColumnDatetime;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "releaseDate",
"comment": "Release date",
"type": "datetime",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "datetime",
"default": "1970-01-01T00:00:00.000+00:00"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/email
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/email" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "contactEmail", "required": false}'输出:202 + Models.ColumnEmail;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "contactEmail",
"comment": "Contact email",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"format": "email",
"default": "default@example.com"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/enum
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
elements | body | string[] | 是 | 枚举值数组(非空 string 数组),default 必须取自其中。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/enum" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "genre", "elements": ["sci-fi", "drama", "animation"], "required": false, "default": "drama"}'输出:202 + Models.ColumnEnum;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "genre",
"comment": "Genre",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 16,
"elements": [
"sci-fi",
"drama",
"animation"
],
"format": "enum",
"default": "drama"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/float
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | number | 否 | 最小值下界。 | |
max | body | number | 否 | 最大值上界。 | |
default | body | number | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/float" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "rating", "min": 0, "max": 10, "required": false, "default": 0}'输出:202 + Models.ColumnFloat;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "rating",
"comment": "Rating 0-10",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 10,
"default": 0
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/integer
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | integer | 否 | 最小值下界。 | |
max | body | integer | 否 | 最大值上界。 | |
default | body | integer | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/integer" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "year", "min": 1900, "max": 2100, "required": false, "default": 2000}'输出:202 + Models.ColumnInteger;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/ip
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/ip" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "originIp", "required": false}'输出:202 + Models.ColumnIp;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "originIp",
"comment": "Origin IP",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32,
"format": "ip",
"default": "192.0.2.0"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/line
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/line" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "route", "required": false}'输出:202 + Models.ColumnLine;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "route",
"comment": "Route line",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
116.4,
39.9
],
[
116.5,
40.0
]
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/longtext
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/longtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "plot", "required": false}'输出:202 + Models.ColumnLongtext;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "plot",
"comment": "Full plot",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 2147483647,
"default": "default",
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/mediumtext
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/mediumtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "notes", "required": false}'输出:202 + Models.ColumnMediumtext;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "notes",
"comment": "Internal notes",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 16777215,
"default": "default",
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/point
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/point" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "origin", "required": false}'输出:202 + Models.ColumnPoint;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "origin",
"comment": "Origin coordinate",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
116.4,
39.9
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/polygon
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/polygon" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "area", "required": false}'输出:202 + Models.ColumnPolygon;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "area",
"comment": "Coverage area",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
[
116.4,
39.9
],
[
116.5,
39.9
],
[
116.5,
40.0
],
[
116.4,
39.9
]
]
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/relationship
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
relatedTableId | body | string | 是 | 关联表 ID。关系列创建后不可更改对侧表。 | |
type | body | string | 是 | 枚举 oneToOne / manyToOne / manyToMany / oneToMany | 关系类型:oneToOne / manyToOne / manyToMany / oneToMany。 |
twoWay | body | boolean | 否 | 是否双向关系。双向时需提供 twoWayKey。 | |
key | body | string | 否 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
twoWayKey | body | string | 否 | 双向关系在对侧表/集合上的反向列 key。 | |
onDelete | body | string | 否 | 枚举 cascade / restrict / setNull | 删除关联行时的约束:cascade(级联删除)/ restrict(阻止删除)/ setNull(置空)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/relationship" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "studio", "relatedTableId": "studios", "type": "manyToOne", "onDelete": "restrict"}'输出:202 + Models.ColumnRelationship;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "studio",
"comment": "Studio relation",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"relatedTable": "studios",
"relationType": "manyToOne",
"twoWay": false,
"twoWayKey": "",
"onDelete": "restrict",
"side": "parent|child"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/string
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
size | body | integer | 是 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/string" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "title", "size": 128, "required": true}'输出:202 + Models.ColumnString;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/text
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/text" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "synopsis", "required": false}'输出:202 + Models.ColumnText;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "synopsis",
"comment": "Synopsis",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 65535,
"default": "default",
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/url
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/url" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "trailerUrl", "required": false}'输出:202 + Models.ColumnUrl;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "trailerUrl",
"comment": "Trailer URL",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"format": "url",
"default": "https://example.com"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/varchar
创建列(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
size | body | integer | 是 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/varchar" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "code", "size": 32, "required": false, "default": "NEW"}'输出:202 + Models.ColumnVarchar;异步建列:status 初始为 processing,轮询 GET …/columns/{key} 至 available 后再写入。
响应示例
{
"key": "code",
"comment": "Short code",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32,
"default": "NEW",
"encrypt": false
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/boolean/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | boolean | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/boolean/watched" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": false, "required": false}'输出:200 + Models.ColumnBoolean;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnBoolean 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/datetime/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/datetime/releaseDate" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": "1970-01-01T00:00:00.000+00:00", "required": false}'输出:200 + Models.ColumnDatetime;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnDatetime 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/email/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/email/contactEmail" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.ColumnEmail;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnEmail 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/enum/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
elements | body | string[] | 是 | 枚举值数组(非空 string 数组),default 必须取自其中。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/enum/genre" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"elements": ["sci-fi", "drama", "animation", "documentary"], "default": "drama", "required": false}'输出:200 + Models.ColumnEnum;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnEnum 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/float/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | number | 否 | 最小值下界。 | |
max | body | number | 否 | 最大值上界。 | |
default | body | number | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/float/rating" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 0, "max": 10, "required": false}'输出:200 + Models.ColumnFloat;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnFloat 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/integer/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | integer | 否 | 最小值下界。 | |
max | body | integer | 否 | 最大值上界。 | |
default | body | integer | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/integer/year" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 1900, "max": 2100, "required": false}'输出:200 + Models.ColumnInteger;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnInteger 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/ip/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/ip/originIp" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.ColumnIp;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnIp 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/line/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/line/route" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'输出:200 + Models.ColumnLine;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnLine 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/longtext/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/longtext/plot" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.ColumnLongtext;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnLongtext 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/mediumtext/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/mediumtext/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.ColumnMediumtext;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnMediumtext 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/point/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/point/origin" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'输出:200 + Models.ColumnPoint;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnPoint 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/polygon/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/polygon/area" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'输出:200 + Models.ColumnPolygon;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnPolygon 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/string/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
size | body | integer | 否 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/string/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 256, "required": false}'输出:200 + Models.ColumnString;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnString 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/text/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/text/synopsis" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.ColumnText;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnText 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/url/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/url/trailerUrl" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.ColumnUrl;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnUrl 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/varchar/{key}
更新列(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
size | body | integer | 否 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/varchar/code" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 64, "required": false}'输出:200 + Models.ColumnVarchar;同步更新,返回更新后的列模型。
响应示例:与同组上文已展示的 Models.ColumnVarchar 示例同构。
GET /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}
获取单列定义与状态。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + 任一 Models.Column* 类型模型;响应为任一 column* / attribute* 类型模型(以 string 为例)。
响应示例(以 string 类型为例)
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}/comment
更新列注释(展示名),仅改元数据,通常零 DDL。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
comment | body | string | 是 | 展示名/注释,最长 256 Unicode 字符;首尾空白会被裁剪,null 或空白清除注释。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/title/comment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"comment": "影片库"}'输出:200 + 任一 Models.Column* 类型模型;响应为该列更新后的完整模型(以 string 为例)。
响应示例(以 string 类型为例)
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}/relationship
更新关系列的删除约束(onDelete)或改名(newKey)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
onDelete | body | string | 否 | 枚举 cascade / restrict / setNull | 删除关联行时的约束:cascade(级联删除)/ restrict(阻止删除)/ setNull(置空)。 |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/studio/relationship" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"onDelete": "cascade"}'输出:200 + Models.ColumnRelationship。
响应示例:与同组上文已展示的 Models.ColumnRelationship 示例同构。
DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}
删除列(异步)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;异步删除;无响应体。
索引(index)
`columnIndex` 模型字段:
| 字段 | 说明 |
|---|---|
$id | 索引 ID |
key | 索引 key |
type | key / fulltext / unique / spatial |
status | available / processing / deleting / stuck / failed |
error | 失败原因 |
`columns[]` | 参与索引的 列 key 数组 |
lengths[] | 各列前缀长度(与 列 按位对应) |
orders[] | 各列排序方向 ASC/DESC(与 列 按位对应) |
创建/删除为异步(202),轮询 GET …/indexes/{key} 至 status=available。列表响应 total + indexes[]。
GET /v1/tablesdb/{databaseId}/tables/{tableId}/indexes
列出表索引(可按 key/type/status 过滤)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("type","key")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.ColumnIndexList。
响应示例
{
"total": 1,
"indexes": [
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/tablesdb/{databaseId}/tables/{tableId}/indexes/{key}
获取索引定义与状态。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.ColumnIndex。
响应示例:与同组上文已展示的 Models.ColumnIndex 示例同构。
POST /v1/tablesdb/{databaseId}/tables/{tableId}/indexes
创建索引(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
type | body | string | 是 | 枚举 key / fulltext / unique / spatial | 索引类型:key(普通)/ fulltext(全文)/ unique(唯一)/ spatial(空间)。 |
columns | body | string[] | 是 | 参与索引的列 key 数组;orders/lengths 与之按位对应。 | |
orders | body | string[] | 否 | 各索引列的排序方向:ASC / DESC(与列按位对应)。 | |
lengths | body | integer[] | 否 | 各索引列的前缀长度(整数数组,与列按位对应)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "idx_genre", "type": "key", "columns": ["genre"], "orders": ["ASC"]}'输出:202 + Models.ColumnIndex;异步建索引:轮询 GET …/indexes/{key} 至 available。
响应示例
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/indexes/{key}
删除索引。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
行(row)
行 模型字段:
| 字段 | 说明 |
|---|---|
$id | 行 ID |
$sequence | 行序号(同表内单调递增) |
$tableId | 所属表 ID |
$databaseId | 所属库 ID |
$createdAt / $updatedAt | 创建/更新时间 |
$permissions | 行级权限字符串数组 |
除系统字段外的所有键都是数据列(键 = 列 key,值类型随列定义与 array 而定)。列表响应 rowList:total + rows[];查询参数 total=false 跳过计数,ttl(0–86400 秒)为 select 查询启用响应缓存(需实例开启)。
GET /v1/tablesdb/{databaseId}/tables/{tableId}/rows
查询行:过滤/排序/分页,支持读事务内未提交变更与缓存 TTL。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | query | string | 否 | 事务 ID。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
ttl | query | integer | 否 | 默认 0 | select 查询的响应缓存 TTL(0–86400 秒),需实例开启缓存;0 表示不缓存。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("genre","animation")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.RowList。
响应示例
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/rows
创建行;同一端点承载单条(createRow)与批量(createRows)两个 SDK 方法。(SDK:tablesDB.createRow / tablesDB.createRows)
**输入(createRow,单条)**
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rowId | body | string | 是 | 行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。 | |
data | body | object | 是 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID:把本次写入挂到事务。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}, "rowId": "snow-white"}'输出:201 + Models.Row(字段见本组开头)。
响应示例
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
}**输入(createRows,批量)**
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rows | body | object[] | 是 | 行数据对象数组,可含部分字段(配合批量 upsert)。 | |
transactionId | body | string | 否 | 事务 ID:把批量写入挂到事务。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"rows": [{"rowId": "snow-white", "data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}}, {"rowId": "bambi", "data": {"title": "Bambi", "year": 1942, "genre": "animation", "rating": 7.3, "watched": false}}]}'输出:201 + Models.RowList(total + 数组,分页结构见本组开头)。
响应示例
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows
批量 upsert 行(rows 数组可含部分行)。(SDK:tablesDB.upsertRows)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rows | body | object[] | 是 | 行数据对象数组,可含部分字段(配合批量 upsert)。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"rows": [{"rowId": "snow-white", "data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}}, {"rowId": "bambi", "data": {"title": "Bambi", "year": 1942, "genre": "animation", "rating": 7.3, "watched": false}}]}'输出:201 + Models.RowList。
响应示例
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows
按 queries 批量更新行,返回受影响行。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
queries | body | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"rating": 8.4}, "queries": ["equal(\"watched\",false)"]}'输出:200 + Models.RowList。
响应示例
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/rows
按 queries 批量删除行,返回受影响行。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
queries | body | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"queries": ["lessThan(\"rating\",5)"]}'输出:200 + Models.RowList。
响应示例
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}GET /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
按 ID 获取单行。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rowId | path | string | 是 | 行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | query | string | 否 | 事务 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Row。
响应示例:与同组上文已展示的 Models.Row 示例同构。
PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
upsert 行:存在则更新,不存在则创建。(SDK:tablesDB.upsertRow)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rowId | path | string | 是 | 行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}, "permissions": ["read(\"any\")"]}'输出:201 + Models.Row。
响应示例:与同组上文已展示的 Models.Row 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
部分更新行(data 只含需更新的列)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rowId | path | string | 是 | 行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"rating": 8.4}}'输出:200 + Models.Row。
响应示例:与同组上文已展示的 Models.Row 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/decrement
数值列原子自减(可带下界 min)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rowId | path | string | 是 | 行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。 | |
column | path | string | 是 | 列 key(path 参数)。 | |
value | body | number | 否 | 增量值(数字),默认 1。 | |
min | body | number | 否 | 自减的下界,越界报错不写入。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white/rating/decrement" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1, "min": 0}'输出:200 + Models.Row;返回自减后的完整行。
响应示例:与同组上文已展示的 Models.Row 示例同构。
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/increment
数值列原子自增(可带上界 max)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rowId | path | string | 是 | 行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。 | |
column | path | string | 是 | 列 key(path 参数)。 | |
value | body | number | 否 | 增量值(数字),默认 1。 | |
max | body | number | 否 | 自增的上界,越界报错不写入。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white/rating/increment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1, "max": 10}'输出:200 + Models.Row;返回自增后的完整行。
响应示例:与同组上文已展示的 Models.Row 示例同构。
DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
删除行,可挂到事务。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
rowId | path | string | 是 | 行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
聚合(aggregation,仅 TablesDB)
响应 rowAggregation:total(分组数)+ rows[],元素为 { "group": {分组列值}, "values": {聚合值} },键为 select/groupBy 中的别名。仅支持过滤类 queries;分页、排序、游标与 Query.select 会被拒绝。
GET /v1/tablesdb/{databaseId}/tables/{tableId}/aggregation
行聚合统计(count/sum/avg/min/max,可按列分组)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
tableId | path | string | 是 | 表唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
groupBy | query | string[] | 否 | 分组列,最多 5 个标量列。 | |
select | query | string[] | 是 | 聚合表达式与分组列。支持 count/sum/avg/min/max 与 AS 别名;普通列必须同时出现在 groupBy。 | |
transactionId | query | string | 否 | 事务 ID。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/aggregation" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'select[]=count(*) AS totalRows' \
--data-urlencode 'select[]=genre' \
--data-urlencode 'groupBy[]=genre'输出:200 + Models.RowAggregation。
响应示例
{
"total": 1,
"rows": [
{
"group": {
"genre": "animation"
},
"values": {
"totalRows": 2
}
}
]
}事务(transaction)
transaction 模型字段:
| 字段 | 说明 |
|---|---|
$id | 事务 ID,行/文档端点凭它传 transactionId |
$createdAt / $updatedAt | 创建/更新时间 |
status | pending → committing → committed / rolled_back / failed |
operations | 已暂存的操作数 |
expiresAt | 过期时间;过期后未提交操作作废 |
POST …/operations 的 operations[] 元素结构(databaseId、action、tableId 必填;data 为操作负载):
| action | 额外必填 | 说明 |
|---|---|---|
create / update / upsert / increment / decrement | rowId、data | 单行操作,data 为列值对象 |
delete | rowId | 删除单行 |
bulkCreate / bulkUpdate / bulkUpsert / bulkDelete | data | 批量操作,data 为对象数组 |
操作分多次调用追加,commit 前不生效;行/文档读写端点也可直接传 transactionId 把单次操作挂到事务。
GET /v1/tablesdb/transactions
分页列出事务。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/tablesdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(10)'输出:200 + Models.TransactionList。
响应示例
{
"total": 1,
"transactions": [
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 2,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}
]
}POST /v1/tablesdb/transactions
创建事务,返回事务 ID;可选 ttl 控制有效期。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
ttl | body | integer | 否 | 事务有效期(秒),过期后未提交的暂存操作作废。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"ttl": 60}'输出:201 + Models.Transaction。
响应示例
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 0,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}GET /v1/tablesdb/transactions/{transactionId}
获取事务状态与暂存操作计数。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
POST /v1/tablesdb/transactions/{transactionId}/operations
向事务批量暂存操作,可多次调用追加。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 | |
operations | body | object[] | 否 | 暂存操作数组,元素结构见本组开头;可多次调用追加。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502/operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"operations": [{"databaseId": "movie-db", "tableId": "films", "rowId": "snow-white", "action": "create", "data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}}, {"databaseId": "movie-db", "tableId": "films", "rowId": "bambi", "action": "delete"}]}'输出:201 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
PATCH /v1/tablesdb/transactions/{transactionId}
提交(commit=true)或回滚(rollback=true)事务,二者只能选其一。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 | |
commit | body | boolean | 否 | 置 true 提交事务(与 rollback 互斥)。 | |
rollback | body | boolean | 否 | 置 true 回滚事务(与 commit 互斥)。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"commit": true}'输出:200 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
DELETE /v1/tablesdb/transactions/{transactionId}
删除事务(丢弃其中的暂存操作)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
Schema 版本与回滚(仅 TablesDB)
schemaVersion 模型字段:
| 字段 | 说明 |
|---|---|
$id | 版本记录 ID |
databaseId | 所属库 ID |
schemaVersion | 单调递增版本号 |
schemaJson | 提交的完整结构 JSON(快照) |
schemaHash | 结构规范 JSON 的 SHA-256,用于幂等 |
status | pending / running / applying → active / failed;被新版本取代后为 deprecated |
migrationPlanJson | 迁移计划(additive / compatible / destructive 分组) |
stepsTotal / stepsCompleted | DDL 步骤总数 / 已完成数 |
errorMessage | 失败原因 |
lastHeartbeatAt | 迁移 Worker 最近心跳 |
deprecatedColumns | 本次被弃用的列 |
同一数据库同时只允许一个 in-flight 版本(重复提交返回 409);迁移 Worker 应用计划后会重读实际结构校验,一致才置 active,否则置 failed 并保留原 active 版本。调用方轮询 GET …/schema/versions/{versionId} 至终态即可,不要自行重放 DDL。
GET /v1/tablesdb/{databaseId}/schema/versions
列出 Schema 版本(默认按版本号降序)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/versions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.SchemaVersionList。
响应示例
{
"total": 1,
"schemaVersions": [
{
"$id": "5e5ea5c16897e",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"databaseId": "movie-db",
"schemaJson": "{\"tables\":[{\"id\":\"films\",\"columns\":[{\"key\":\"title\",\"type\":\"string\",\"size\":128,\"required\":true},{\"key\":\"year\",\"type\":\"integer\"}],\"indexes\":[{\"key\":\"idx_title\",\"type\":\"fulltext\",\"attributes\":[\"title\"]}]}]}",
"schemaVersion": 1,
"schemaHash": "a3f1c2d4e5b607189accd3f2b1a04e55",
"status": "active",
"migrationPlanJson": "{\"additive\":[],\"compatible\":[],\"destructive\":[]}",
"stepsTotal": 2,
"stepsCompleted": 2,
"errorMessage": "",
"lastHeartbeatAt": "2026-01-12T08:00:00.000+00:00",
"deprecatedColumns": []
}
]
}GET /v1/tablesdb/{databaseId}/schema/versions/{versionId}
查询 Schema 版本状态与迁移进度。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
versionId | path | string | 是 | 目标 Schema 版本 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/versions/1" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.SchemaVersion。
响应示例:与同组上文已展示的 Models.SchemaVersion 示例同构。
POST /v1/tablesdb/{databaseId}/schema/rollback/{versionId}
回滚到指定 Schema 版本(只切换结构可见性,不执行物理 DDL、不删数据)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
versionId | path | string | 是 | 目标 Schema 版本 ID。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/rollback/1" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.SchemaVersion。
响应示例:与同组上文已展示的 Models.SchemaVersion 示例同构。
POST /v1/tablesdb/{databaseId}/schema/versions
提交完整 Schema:生成迁移计划并执行;schemaHash 相同则幂等复用已有版本。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
schema | body | object | 是 | 完整结构定义 JSON 对象,含 tables 数组(整库快照,不是 diff patch)。 | |
mode | body | string | 否 | 枚举 migration / baseline | migration(默认,对 active 版本做 diff 并执行迁移)或 baseline(把当前物理结构采纳为首活跃版本,不执行 DDL)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/versions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"schema": {"tables": [{"id": "films", "columns": [{"key": "title", "type": "string", "size": 128, "required": true}, {"key": "year", "type": "integer"}], "indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}]}]}, "mode": "migration"}'输出:201(新版本)/ 200(schemaHash 相同幂等复用)+ Models.SchemaVersion。
响应示例
{
"$id": "5e5ea5c16897e",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"databaseId": "movie-db",
"schemaJson": "{\"tables\":[{\"id\":\"films\",\"columns\":[{\"key\":\"title\",\"type\":\"string\",\"size\":128,\"required\":true},{\"key\":\"year\",\"type\":\"integer\"}],\"indexes\":[{\"key\":\"idx_title\",\"type\":\"fulltext\",\"attributes\":[\"title\"]}]}]}",
"schemaVersion": 1,
"schemaHash": "a3f1c2d4e5b607189accd3f2b1a04e55",
"status": "active",
"migrationPlanJson": "{\"additive\":[],\"compatible\":[],\"destructive\":[]}",
"stepsTotal": 2,
"stepsCompleted": 2,
"errorMessage": "",
"lastHeartbeatAt": "2026-01-12T08:00:00.000+00:00",
"deprecatedColumns": []
}DocumentsDB 逐端点规格(/documentsdb,31 个端点)
库(database)
database 模型字段:
| 字段 | 说明 |
|---|---|
$id | 库 ID |
name | 名称(≤128 字符) |
$createdAt / $updatedAt | 创建/更新时间(ISO 8601) |
enabled | 启用态;停用只挡用户侧访问,API Key 仍可读写,不丢数据 |
type | 库类型:legacy / tablesdb / documentsdb / vectorsdb |
列表响应 databaseList:total(匹配总数)+ databases[]。
GET /v1/documentsdb
分页列出当前项目的库,支持 queries 过滤与 search 搜索。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
search | query | string | 否 | 关键词搜索,最长 256 字符。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/documentsdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Notes")' \
--data-urlencode 'queries[]=limit(50)'输出:200 + Models.DatabaseList。
响应示例
{
"total": 1,
"databases": [
{
"$id": "notes-db",
"name": "Notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "documentsdb"
}
]
}POST /v1/documentsdb
创建库。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | body | string | 是 | 数据库唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/documentsdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"databaseId": "notes-db", "name": "Notes", "enabled": true}'输出:201 + Models.Database。
响应示例
{
"$id": "notes-db",
"name": "Notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "documentsdb"
}GET /v1/documentsdb/{databaseId}
按 ID 获取库详情。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Database。
响应示例:与同组上文已展示的 Models.Database 示例同构。
PUT /v1/documentsdb/{databaseId}
更新库名称与启用态。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Notes", "enabled": true}'输出:200 + Models.Database。
响应示例:与同组上文已展示的 Models.Database 示例同构。
DELETE /v1/documentsdb/{databaseId}
按 ID 删除库。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
集合(collection)
collection 模型字段:
| 字段 | 说明 |
|---|---|
$id | 集合 ID |
databaseId | 所属库 ID |
name | 名称(≤128 字符) |
$permissions | 集合级权限字符串数组 |
enabled | 启用态;停用只挡用户侧访问 |
documentSecurity | 是否启用文档级权限 |
attributes[] | 属性定义数组(attribute* 模型,见「属性」小节) |
indexes[] | 索引数组(index 模型,见「索引」小节) |
bytesMax / bytesUsed | 容量配额与已用字节 |
列表响应 collectionList:total + collections[]。
GET /v1/documentsdb/{databaseId}/collections
列出库下的集合,支持 queries 过滤与 search 搜索。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
search | query | string | 否 | 关键词搜索,最长 256 字符。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Notes")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.CollectionList。
响应示例
{
"total": 1,
"collections": [
{
"$id": "notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "notes-db",
"name": "Notes",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 256,
"encrypt": false
},
{
"key": "color",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"amber",
"ivory",
"sage"
],
"format": "enum",
"size": 16
},
{
"key": "labels",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": true,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}
]
}POST /v1/documentsdb/{databaseId}/collections
创建集合,可在请求体中携带完整的 attributes/indexes 定义。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | body | string | 是 | 集合唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
documentSecurity | body | boolean | 否 | 是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 | |
attributes | body | object[] | 否 | 建集合即建属性的定义数组,字段同 TablesDB 的 columns(key、type 必填等)。 | |
indexes | body | object[] | 否 | 建表/集合即建索引的定义数组(key、type、attributes 必填;orders、lengths 可选)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"collectionId": "notes", "name": "Notes", "documentSecurity": false, "attributes": [{"key": "title", "type": "string", "size": 256, "required": true}, {"key": "color", "type": "string", "size": 16, "format": "enum", "elements": ["amber", "ivory", "sage"]}, {"key": "labels", "type": "string", "size": 32, "array": true}], "indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}]}'输出:201 + Models.Collection。
响应示例
{
"$id": "notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "notes-db",
"name": "Notes",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 256,
"encrypt": false
},
{
"key": "color",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"amber",
"ivory",
"sage"
],
"format": "enum",
"size": 16
},
{
"key": "labels",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": true,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/documentsdb/{databaseId}/collections/{collectionId}
获取集合详情(含属性、索引定义)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Collection。
响应示例:与同组上文已展示的 Models.Collection 示例同构。
PUT /v1/documentsdb/{databaseId}/collections/{collectionId}
更新集合属性,或提交整集合结构(attributes/indexes 数组)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
documentSecurity | body | boolean | 否 | 是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Notes", "enabled": true}'输出:200 + Models.Collection。
响应示例:与同组上文已展示的 Models.Collection 示例同构。
DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}
删除集合。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
索引(index)
`index` 模型字段:
| 字段 | 说明 |
|---|---|
$id | 索引 ID |
key | 索引 key |
type | key / fulltext / unique / spatial |
status | available / processing / deleting / stuck / failed |
error | 失败原因 |
`attributes[]` | 参与索引的 属性 key 数组 |
lengths[] | 各列前缀长度(与 属性 按位对应) |
orders[] | 各列排序方向 ASC/DESC(与 属性 按位对应) |
创建/删除为异步(202),轮询 GET …/indexes/{key} 至 status=available。列表响应 total + indexes[]。
GET /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes
列出集合索引(可按 key/type/status 过滤)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("type","key")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.IndexList。
响应示例
{
"total": 1,
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes/{key}
获取索引定义与状态。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Index。
响应示例:与同组上文已展示的 Models.Index 示例同构。
POST /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes
创建索引(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
type | body | string | 是 | 枚举 key / fulltext / unique / spatial | 索引类型:key(普通)/ fulltext(全文)/ unique(唯一)/ spatial(空间)。 |
attributes | body | string[] | 是 | 参与索引的属性 key 数组;orders/lengths 与之按位对应。 | |
orders | body | string[] | 否 | 各索引列的排序方向:ASC / DESC(与列按位对应)。 | |
lengths | body | integer[] | 否 | 各索引列的前缀长度(整数数组,与列按位对应)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "idx_status", "type": "key", "attributes": ["status"], "orders": ["ASC"]}'输出:202 + Models.Index;异步建索引:轮询 GET …/indexes/{key} 至 available。
响应示例
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes/{key}
删除索引。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
文档(document)
文档 模型字段:
| 字段 | 说明 |
|---|---|
$id | 文档 ID |
$sequence | 文档序号(同集合内单调递增) |
$collectionId | 所属集合 ID |
$databaseId | 所属库 ID |
$createdAt / $updatedAt | 创建/更新时间 |
$permissions | 文档级权限字符串数组 |
除系统字段外的所有键都是数据属性(键 = 属性 key)。列表响应 documentList:total + documents[];查询参数 total=false 跳过计数,ttl(0–86400 秒)为 select 查询启用响应缓存(需实例开启)。
GET /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
查询文档:过滤/排序/分页,支持读事务内未提交变更与缓存 TTL。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | query | string | 否 | 事务 ID。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
ttl | query | integer | 否 | 默认 0 | select 查询的响应缓存 TTL(0–86400 秒),需实例开启缓存;0 表示不缓存。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("color","amber")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}POST /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
创建文档;同一端点承载单条(createDocument)与批量(createDocuments)两个 SDK 方法。(SDK:documentsDB.createDocument / documentsDB.createDocuments)
**输入(createDocument,单条)**
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | body | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
data | body | object | 是 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID:把本次写入挂到事务。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}, "documentId": "note-101"}'输出:201 + Models.Document(字段见本组开头)。
响应示例
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
}**输入(createDocuments,批量)**
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documents | body | object[] | 是 | 文档数据对象数组,可含部分字段(配合批量 upsert)。 | |
transactionId | body | string | 否 | 事务 ID:把批量写入挂到事务。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "note-101", "data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}}, {"documentId": "note-102", "data": {"title": "Reading list", "body": "Finish the schema migration runbook.", "color": "sage", "wordCount": 90, "labels": ["work"]}}]}'输出:201 + Models.DocumentList(total + 数组,分页结构见本组开头)。
响应示例
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}PUT /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
批量 upsert 文档(documents 数组可含部分字段)。(SDK:documentsDB.upsertDocuments)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documents | body | object[] | 是 | 文档数据对象数组,可含部分字段(配合批量 upsert)。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "note-101", "data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}}, {"documentId": "note-102", "data": {"title": "Reading list", "body": "Finish the schema migration runbook.", "color": "sage", "wordCount": 90, "labels": ["work"]}}]}'输出:201 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
按 queries 批量更新文档,返回受影响文档。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
queries | body | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"pinned": true}, "queries": ["equal(\"color\",amber)"]}'输出:200 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
按 queries 批量删除文档,返回受影响文档。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
queries | body | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"queries": ["lessThan(\"wordCount\",100)"]}'输出:200 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}GET /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
按 ID 获取单文档。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | query | string | 否 | 事务 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Document。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PUT /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
upsert 文档:存在则更新,不存在则创建。(SDK:documentsDB.upsertDocument)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}, "permissions": ["read(\"any\")"]}'输出:201 + Models.Document。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
部分更新文档(data 只含需更新的属性)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"wordCount": 300}}'输出:200 + Models.Document。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/decrement
数值属性原子自减(可带下界 min)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
attribute | path | string | 是 | 属性 key(path 参数)。 | |
value | body | number | 否 | 增量值(数字),默认 1。 | |
min | body | number | 否 | 自减的下界,越界报错不写入。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101/wordCount/decrement" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 100, "min": 0}'输出:200 + Models.Document;返回自减后的完整文档。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/increment
数值属性原子自增(可带上界 max)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
attribute | path | string | 是 | 属性 key(path 参数)。 | |
value | body | number | 否 | 增量值(数字),默认 1。 | |
max | body | number | 否 | 自增的上界,越界报错不写入。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101/wordCount/increment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 100, "max": 10000}'输出:200 + Models.Document;返回自增后的完整文档。
响应示例:与同组上文已展示的 Models.Document 示例同构。
DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
删除文档,可挂到事务。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
事务(transaction)
transaction 模型字段:
| 字段 | 说明 |
|---|---|
$id | 事务 ID,行/文档端点凭它传 transactionId |
$createdAt / $updatedAt | 创建/更新时间 |
status | pending → committing → committed / rolled_back / failed |
operations | 已暂存的操作数 |
expiresAt | 过期时间;过期后未提交操作作废 |
POST …/operations 的 operations[] 元素结构(databaseId、action、collectionId 必填;data 为操作负载):
| action | 额外必填 | 说明 |
|---|---|---|
create / update / upsert / increment / decrement | documentId、data | 单文档操作,data 为列值对象 |
delete | documentId | 删除单文档 |
bulkCreate / bulkUpdate / bulkUpsert / bulkDelete | data | 批量操作,data 为对象数组 |
操作分多次调用追加,commit 前不生效;行/文档读写端点也可直接传 transactionId 把单次操作挂到事务。
GET /v1/documentsdb/transactions
分页列出事务。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/documentsdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(10)'输出:200 + Models.TransactionList。
响应示例
{
"total": 1,
"transactions": [
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 2,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}
]
}POST /v1/documentsdb/transactions
创建事务,返回事务 ID;可选 ttl 控制有效期。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
ttl | body | integer | 否 | 事务有效期(秒),过期后未提交的暂存操作作废。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"ttl": 60}'输出:201 + Models.Transaction。
响应示例
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 0,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}GET /v1/documentsdb/transactions/{transactionId}
获取事务状态与暂存操作计数。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
POST /v1/documentsdb/transactions/{transactionId}/operations
向事务批量暂存操作,可多次调用追加。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 | |
operations | body | object[] | 否 | 暂存操作数组,元素结构见本组开头;可多次调用追加。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502/operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"operations": [{"databaseId": "notes-db", "collectionId": "notes", "documentId": "note-101", "action": "create", "data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}}, {"databaseId": "notes-db", "collectionId": "notes", "documentId": "note-102", "action": "delete"}]}'输出:201 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
PATCH /v1/documentsdb/transactions/{transactionId}
提交(commit=true)或回滚(rollback=true)事务,二者只能选其一。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 | |
commit | body | boolean | 否 | 置 true 提交事务(与 rollback 互斥)。 | |
rollback | body | boolean | 否 | 置 true 回滚事务(与 commit 互斥)。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"commit": true}'输出:200 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
DELETE /v1/documentsdb/transactions/{transactionId}
删除事务(丢弃其中的暂存操作)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
旧版 Databases 逐端点规格(/databases,68 个端点)
库(database)
database 模型字段:
| 字段 | 说明 |
|---|---|
$id | 库 ID |
name | 名称(≤128 字符) |
$createdAt / $updatedAt | 创建/更新时间(ISO 8601) |
enabled | 启用态;停用只挡用户侧访问,API Key 仍可读写,不丢数据 |
type | 库类型:legacy / tablesdb / documentsdb / vectorsdb |
列表响应 databaseList:total(匹配总数)+ databases[]。
GET /v1/databases
分页列出当前项目的库,支持 queries 过滤与 search 搜索。(SDK:databases.list)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
search | query | string | 否 | 关键词搜索,最长 256 字符。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/databases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Orders")' \
--data-urlencode 'queries[]=limit(50)'输出:200 + Models.DatabaseList。
响应示例
{
"total": 1,
"databases": [
{
"$id": "shop-db",
"name": "Shop",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "legacy"
}
]
}POST /v1/databases
创建库。(SDK:databases.create)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | body | string | 是 | 数据库唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"databaseId": "shop-db", "name": "Shop", "enabled": true}'输出:201 + Models.Database。
响应示例
{
"$id": "shop-db",
"name": "Shop",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "legacy"
}GET /v1/databases/{databaseId}
按 ID 获取库详情。(SDK:databases.get)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/databases/shop-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Database。
响应示例:与同组上文已展示的 Models.Database 示例同构。
PUT /v1/databases/{databaseId}
更新库名称与启用态。(SDK:databases.update)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
name | body | string | 否 | 名称,最长 128 字符。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Orders", "enabled": true}'输出:200 + Models.Database。
响应示例:与同组上文已展示的 Models.Database 示例同构。
DELETE /v1/databases/{databaseId}
按 ID 删除库。(SDK:databases.delete)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
集合(collection)
collection 模型字段:
| 字段 | 说明 |
|---|---|
$id | 集合 ID |
databaseId | 所属库 ID |
name | 名称(≤128 字符) |
$permissions | 集合级权限字符串数组 |
enabled | 启用态;停用只挡用户侧访问 |
documentSecurity | 是否启用文档级权限 |
attributes[] | 属性定义数组(attribute* 模型,见「属性」小节) |
indexes[] | 索引数组(index 模型,见「索引」小节) |
bytesMax / bytesUsed | 容量配额与已用字节 |
列表响应 collectionList:total + collections[]。
GET /v1/databases/{databaseId}/collections
列出库下的集合,支持 queries 过滤与 search 搜索。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
search | query | string | 否 | 关键词搜索,最长 256 字符。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Orders")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.CollectionList。
响应示例
{
"total": 1,
"collections": [
{
"$id": "orders",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "shop-db",
"name": "Orders",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 64,
"encrypt": false
},
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"size": 16
},
{
"key": "total",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 100000
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}
]
}POST /v1/databases/{databaseId}/collections
创建集合,可在请求体中携带完整的 attributes/indexes 定义。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | body | string | 是 | 集合唯一 ID。 | |
name | body | string | 是 | 名称,最长 128 字符。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
documentSecurity | body | boolean | 否 | 是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 | |
attributes | body | object[] | 否 | 建集合即建属性的定义数组,字段同 TablesDB 的 columns(key、type 必填等)。 | |
indexes | body | object[] | 否 | 建表/集合即建索引的定义数组(key、type、attributes 必填;orders、lengths 可选)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"collectionId": "orders", "name": "Orders", "documentSecurity": false, "attributes": [{"key": "customerId", "type": "string", "size": 64, "required": true}, {"key": "status", "type": "string", "size": 16, "format": "enum", "elements": ["pending", "paid", "shipped"], "required": true}, {"key": "total", "type": "double"}], "indexes": [{"key": "idx_status", "type": "key", "attributes": ["status"]}]}'输出:201 + Models.Collection。
响应示例
{
"$id": "orders",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "shop-db",
"name": "Orders",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 64,
"encrypt": false
},
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"size": 16
},
{
"key": "total",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 100000
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/databases/{databaseId}/collections/{collectionId}
获取集合详情(含属性、索引定义)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Collection。
响应示例:与同组上文已展示的 Models.Collection 示例同构。
PUT /v1/databases/{databaseId}/collections/{collectionId}
更新集合属性,或提交整集合结构(attributes/indexes 数组)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
name | body | string | 否 | 名称,最长 128 字符。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
documentSecurity | body | boolean | 否 | 是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。 | |
enabled | body | boolean | 否 | 是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Orders", "enabled": true}'输出:200 + Models.Collection。
响应示例:与同组上文已展示的 Models.Collection 示例同构。
DELETE /v1/databases/{databaseId}/collections/{collectionId}
删除集合。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
属性(attribute,17 种类型)
集合属性模型(Models.AttributeString … Models.AttributeRelationship)公共字段:
| 字段 | 说明 |
|---|---|
key | 属性 key |
type | 类型标识(enum 属性的 type 仍为 string,靠 format: "enum" + elements 区分) |
status | available / processing / deleting / stuck / failed |
error | 失败原因(无错误为空串) |
required / array | 必填性 / 是否数组列 |
$createdAt / $updatedAt | 创建/更新时间 |
生命周期要点:
- 创建返回
202(异步 DDL),status从processing→available(或failed);轮询GET …/{key}直到available,再写入依赖该属性的数据。 - 更新端点(
PATCH …/{type}/{key})同步返回200;公共参数required、default、newKey(改名),各类型另有专有参数(见各端点表)。 default与required互斥;改required前需保证存量行均有值。
GET /v1/databases/{databaseId}/collections/{collectionId}/attributes
列出集合的全部属性(含建属性进度 status)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(100)'输出:200 + Models.AttributeList。
响应示例
{
"total": 2,
"attributes": [
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"default": "paid",
"size": 16
}
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/boolean
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | boolean | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/boolean" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "paid", "required": false, "default": false}'输出:202 + Models.AttributeBoolean;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "paid",
"type": "boolean",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/datetime
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/datetime" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "placedAt", "required": false, "default": "1970-01-01T00:00:00.000+00:00"}'输出:202 + Models.AttributeDatetime;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "placedAt",
"type": "datetime",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "datetime",
"default": "1970-01-01T00:00:00.000+00:00"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/email
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/email" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "buyerEmail", "required": false}'输出:202 + Models.AttributeEmail;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "buyerEmail",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "email",
"default": "default@example.com"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/enum
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
elements | body | string[] | 是 | 枚举值数组(非空 string 数组),default 必须取自其中。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/enum" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "status", "elements": ["pending", "paid", "shipped"], "required": false, "default": "pending"}'输出:202 + Models.AttributeEnum;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"default": "paid",
"size": 16
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/float
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | number | 否 | 最小值下界。 | |
max | body | number | 否 | 最大值上界。 | |
default | body | number | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/float" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "total", "min": 0, "max": 100000, "required": false, "default": 0}'输出:202 + Models.AttributeFloat;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "total",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 10,
"default": 0
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/integer
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | integer | 否 | 最小值下界。 | |
max | body | integer | 否 | 最大值上界。 | |
default | body | integer | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/integer" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "itemCount", "min": 0, "max": 1000, "required": false, "default": 1}'输出:202 + Models.AttributeInteger;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "itemCount",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 1900,
"max": 2100,
"default": 2000
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/ip
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/ip" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "clientIp", "required": false}'输出:202 + Models.AttributeIp;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "clientIp",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "ip",
"default": "192.0.2.0"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/line
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/line" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "route", "required": false}'输出:202 + Models.AttributeLine;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "route",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
116.4,
39.9
],
[
116.5,
40.0
]
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/longtext
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/longtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "payload", "required": false}'输出:202 + Models.AttributeLongtext;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "payload",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": "default",
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/mediumtext
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/mediumtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "log", "required": false}'输出:202 + Models.AttributeMediumtext;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "log",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": "default",
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/point
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/point" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "deliveryPoint", "required": false}'输出:202 + Models.AttributePoint;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "deliveryPoint",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
116.4,
39.9
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/polygon
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/polygon" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "region", "required": false}'输出:202 + Models.AttributePolygon;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "region",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
[
116.4,
39.9
],
[
116.5,
39.9
],
[
116.5,
40.0
],
[
116.4,
39.9
]
]
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/relationship
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
relatedCollectionId | body | string | 是 | 关联集合 ID。关系属性创建后不可更改对侧集合。 | |
type | body | string | 是 | 枚举 oneToOne / manyToOne / manyToMany / oneToMany | 关系类型:oneToOne / manyToOne / manyToMany / oneToMany。 |
twoWay | body | boolean | 否 | 是否双向关系。双向时需提供 twoWayKey。 | |
key | body | string | 否 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
twoWayKey | body | string | 否 | 双向关系在对侧表/集合上的反向列 key。 | |
onDelete | body | string | 否 | 枚举 cascade / restrict / setNull | 删除关联行时的约束:cascade(级联删除)/ restrict(阻止删除)/ setNull(置空)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/relationship" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "customer", "relatedCollectionId": "customers", "type": "manyToOne", "onDelete": "restrict"}'输出:202 + Models.AttributeRelationship;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "customer",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"relatedCollection": "customers",
"relationType": "manyToOne",
"twoWay": false,
"twoWayKey": "",
"onDelete": "restrict",
"side": "parent|child"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/string
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
size | body | integer | 是 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/string" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "customerId", "size": 128, "required": true}'输出:202 + Models.AttributeString;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/text
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/text" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "remark", "required": false}'输出:202 + Models.AttributeText;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "remark",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": "default",
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/url
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/url" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "receiptUrl", "required": false}'输出:202 + Models.AttributeUrl;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "receiptUrl",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "url",
"default": "http://example.com"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/varchar
创建属性(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
size | body | integer | 是 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 否 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
array | body | boolean | 否 | 是否数组列。 | |
encrypt | body | boolean | 否 | 是否加密存储。加密列不可用于查询、排序与索引。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/varchar" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "orderNo", "size": 32, "required": false, "default": "NEW"}'输出:202 + Models.AttributeVarchar;异步建属性:status 初始为 processing,轮询 GET …/attributes/{key} 至 available 后再写入。
响应示例
{
"key": "orderNo",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32,
"default": "NEW",
"encrypt": false
}PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/boolean/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | boolean | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/boolean/paid" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": false, "required": false}'输出:200 + Models.AttributeBoolean;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeBoolean 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/datetime/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/datetime/placedAt" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": "1970-01-01T00:00:00.000+00:00", "required": false}'输出:200 + Models.AttributeDatetime;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeDatetime 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/email/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/email/buyerEmail" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.AttributeEmail;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeEmail 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/enum/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
elements | body | string[] | 是 | 枚举值数组(非空 string 数组),default 必须取自其中。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/enum/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"elements": ["pending", "paid", "shipped", "refunded"], "default": "pending", "required": false}'输出:200 + Models.AttributeEnum;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeEnum 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/float/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | number | 否 | 最小值下界。 | |
max | body | number | 否 | 最大值上界。 | |
default | body | number | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/float/total" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 0, "max": 100000, "required": false}'输出:200 + Models.AttributeFloat;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeFloat 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/integer/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
min | body | integer | 否 | 最小值下界。 | |
max | body | integer | 否 | 最大值上界。 | |
default | body | integer | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/integer/itemCount" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 0, "max": 1000, "required": false}'输出:200 + Models.AttributeInteger;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeInteger 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/ip/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/ip/clientIp" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.AttributeIp;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeIp 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/line/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/line/route" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'输出:200 + Models.AttributeLine;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeLine 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/longtext/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/longtext/payload" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.AttributeLongtext;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeLongtext 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/mediumtext/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/mediumtext/log" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.AttributeMediumtext;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeMediumtext 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/point/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/point/deliveryPoint" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'输出:200 + Models.AttributePoint;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributePoint 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/polygon/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | array | 否 | 默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/polygon/region" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'输出:200 + Models.AttributePolygon;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributePolygon 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/relationship/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
onDelete | body | string | 否 | 枚举 cascade / restrict / setNull | 删除关联行时的约束:cascade(级联删除)/ restrict(阻止删除)/ setNull(置空)。 |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/relationship/customer" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"onDelete": "setNull", "newKey": "customer-x"}'输出:200 + Models.AttributeRelationship;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeRelationship 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/string/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
size | body | integer | 否 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/string/customerId" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 256, "required": false}'输出:200 + Models.AttributeString;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeString 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/text/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/text/remark" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.AttributeText;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeText 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/url/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/url/receiptUrl" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'输出:200 + Models.AttributeUrl;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeUrl 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/varchar/{key}
更新属性(必填性、默认值、边界,可用 newKey 改名)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 | |
required | body | boolean | 是 | 是否必填。改为必填前需保证存量行该列均有值。 | |
default | body | string | 是 | 默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。 | |
size | body | integer | 否 | 字符数上限。string/varchar 创建时必填;varchar 上限 16381。 | |
newKey | body | string | 否 | 新 key。改名保留存量数据,索引/权限引用需同步更新。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/varchar/orderNo" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 64, "required": false}'输出:200 + Models.AttributeVarchar;同步更新,返回更新后的属性模型。
响应示例:与同组上文已展示的 Models.AttributeVarchar 示例同构。
GET /v1/databases/{databaseId}/collections/{collectionId}/attributes/{key}
获取单个属性定义与状态。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + 任一 Models.Attribute* 类型模型;响应为任一 column* / attribute* 类型模型(以 string 为例)。
响应示例(以 string 类型为例)
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}DELETE /v1/databases/{databaseId}/collections/{collectionId}/attributes/{key}
删除属性(异步)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;异步删除;无响应体。
索引(index)
`index` 模型字段:
| 字段 | 说明 |
|---|---|
$id | 索引 ID |
key | 索引 key |
type | key / fulltext / unique / spatial |
status | available / processing / deleting / stuck / failed |
error | 失败原因 |
`attributes[]` | 参与索引的 属性 key 数组 |
lengths[] | 各列前缀长度(与 属性 按位对应) |
orders[] | 各列排序方向 ASC/DESC(与 属性 按位对应) |
创建/删除为异步(202),轮询 GET …/indexes/{key} 至 status=available。列表响应 total + indexes[]。
GET /v1/databases/{databaseId}/collections/{collectionId}/indexes
列出集合索引(可按 key/type/status 过滤)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("type","key")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.IndexList。
响应示例
{
"total": 1,
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/databases/{databaseId}/collections/{collectionId}/indexes/{key}
获取索引定义与状态。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Index。
响应示例:与同组上文已展示的 Models.Index 示例同构。
POST /v1/databases/{databaseId}/collections/{collectionId}/indexes
创建索引(异步,返回 202)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | body | string | 是 | 列/属性 key。字符约束同资源 ID,表/集合内唯一。 | |
type | body | string | 是 | 枚举 key / fulltext / unique / spatial | 索引类型:key(普通)/ fulltext(全文)/ unique(唯一)/ spatial(空间)。 |
attributes | body | string[] | 是 | 参与索引的属性 key 数组;orders/lengths 与之按位对应。 | |
orders | body | string[] | 否 | 各索引列的排序方向:ASC / DESC(与列按位对应)。 | |
lengths | body | integer[] | 否 | 各索引列的前缀长度(整数数组,与列按位对应)。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "idx_status", "type": "key", "attributes": ["status"], "orders": ["ASC"]}'输出:202 + Models.Index;异步建索引:轮询 GET …/indexes/{key} 至 available。
响应示例
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}DELETE /v1/databases/{databaseId}/collections/{collectionId}/indexes/{key}
删除索引。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
key | path | string | 是 | 列/属性 key(path 参数)。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
文档(document)
文档 模型字段:
| 字段 | 说明 |
|---|---|
$id | 文档 ID |
$sequence | 文档序号(同集合内单调递增) |
$collectionId | 所属集合 ID |
$databaseId | 所属库 ID |
$createdAt / $updatedAt | 创建/更新时间 |
$permissions | 文档级权限字符串数组 |
除系统字段外的所有键都是数据属性(键 = 属性 key)。列表响应 documentList:total + documents[];查询参数 total=false 跳过计数,ttl(0–86400 秒)为 select 查询启用响应缓存(需实例开启)。
GET /v1/databases/{databaseId}/collections/{collectionId}/documents
查询文档:过滤/排序/分页,支持读事务内未提交变更与缓存 TTL。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | query | string | 否 | 事务 ID。 | |
total | query | boolean | 否 | 默认 true | 置 false 时跳过计数,响应中的 total 恒为 0。 |
ttl | query | integer | 否 | 默认 0 | select 查询的响应缓存 TTL(0–86400 秒),需实例开启缓存;0 表示不缓存。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("status","pending")' \
--data-urlencode 'queries[]=limit(25)'输出:200 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/documents
创建文档;同一端点承载单条(createDocument)与批量(createDocuments)两个 SDK 方法。(SDK:databases.createDocument / databases.createDocuments)
**输入(createDocument,单条)**
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | body | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
data | body | object | 是 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID:把本次写入挂到事务。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}, "documentId": "order-1001"}'输出:201 + Models.Document(字段见本组开头)。
响应示例
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}**输入(createDocuments,批量)**
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documents | body | object[] | 是 | 文档数据对象数组,可含部分字段(配合批量 upsert)。 | |
transactionId | body | string | 否 | 事务 ID:把批量写入挂到事务。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "order-1001", "data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}, {"documentId": "order-1002", "data": {"customerId": "cust-77", "itemCount": 1, "total": 36.0, "status": "paid", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}]}'输出:201 + Models.DocumentList(total + 数组,分页结构见本组开头)。
响应示例
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}PUT /v1/databases/{databaseId}/collections/{collectionId}/documents
批量 upsert 文档(documents 数组可含部分字段)。(SDK:databases.upsertDocuments)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documents | body | object[] | 是 | 文档数据对象数组,可含部分字段(配合批量 upsert)。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "order-1001", "data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}, {"documentId": "order-1002", "data": {"customerId": "cust-77", "itemCount": 1, "total": 36.0, "status": "paid", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}]}'输出:201 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents
按 queries 批量更新文档,返回受影响文档。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
queries | body | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"status": "paid"}, "queries": ["equal(\"status\",pending)"]}'输出:200 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}DELETE /v1/databases/{databaseId}/collections/{collectionId}/documents
按 queries 批量删除文档,返回受影响文档。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
queries | body | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"queries": ["lessThan(\"total\",50)"]}'输出:200 + Models.DocumentList。
响应示例
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}GET /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
按 ID 获取单文档。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 | |
transactionId | query | string | 否 | 事务 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Document。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PUT /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
upsert 文档:存在则更新,不存在则创建。(SDK:databases.upsertDocument)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}, "permissions": ["read(\"any\")"]}'输出:201 + Models.Document。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
部分更新文档(data 只含需更新的属性)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
data | body | object | 否 | 数据对象,键为列/属性 key。仅含需写入/更新的字段。 | |
permissions | body | string[] | 否 | 权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"total": 130.0}}'输出:200 + Models.Document。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/decrement
数值属性原子自减(可带下界 min)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
attribute | path | string | 是 | 属性 key(path 参数)。 | |
value | body | number | 否 | 增量值(数字),默认 1。 | |
min | body | number | 否 | 自减的下界,越界报错不写入。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001/itemCount/decrement" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1}'输出:200 + Models.Document;返回自减后的完整文档。
响应示例:与同组上文已展示的 Models.Document 示例同构。
PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/increment
数值属性原子自增(可带上界 max)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
attribute | path | string | 是 | 属性 key(path 参数)。 | |
value | body | number | 否 | 增量值(数字),默认 1。 | |
max | body | number | 否 | 自增的上界,越界报错不写入。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001/itemCount/increment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1}'输出:200 + Models.Document;返回自增后的完整文档。
响应示例:与同组上文已展示的 Models.Document 示例同构。
DELETE /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
删除文档,可挂到事务。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
databaseId | path | string | 是 | 数据库唯一 ID。 | |
collectionId | path | string | 是 | 集合唯一 ID。 | |
documentId | path | string | 是 | 文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。 | |
transactionId | body | string | 否 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
事务(transaction)
transaction 模型字段:
| 字段 | 说明 |
|---|---|
$id | 事务 ID,行/文档端点凭它传 transactionId |
$createdAt / $updatedAt | 创建/更新时间 |
status | pending → committing → committed / rolled_back / failed |
operations | 已暂存的操作数 |
expiresAt | 过期时间;过期后未提交操作作废 |
POST …/operations 的 operations[] 元素结构(databaseId、action、collectionId 必填;data 为操作负载):
| action | 额外必填 | 说明 |
|---|---|---|
create / update / upsert / increment / decrement | documentId、data | 单文档操作,data 为列值对象 |
delete | documentId | 删除单文档 |
bulkCreate / bulkUpdate / bulkUpsert / bulkDelete | data | 批量操作,data 为对象数组 |
操作分多次调用追加,commit 前不生效;行/文档读写端点也可直接传 transactionId 把单次操作挂到事务。
GET /v1/databases/transactions
分页列出事务。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。 |
调用示例
curl -G \
"https://<your-endpoint>/v1/databases/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(10)'输出:200 + Models.TransactionList。
响应示例
{
"total": 1,
"transactions": [
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 2,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}
]
}POST /v1/databases/transactions
创建事务,返回事务 ID;可选 ttl 控制有效期。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
ttl | body | integer | 否 | 事务有效期(秒),过期后未提交的暂存操作作废。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"ttl": 60}'输出:201 + Models.Transaction。
响应示例
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 0,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}GET /v1/databases/transactions/{transactionId}
获取事务状态与暂存操作计数。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 |
调用示例
curl \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:200 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
POST /v1/databases/transactions/{transactionId}/operations
向事务批量暂存操作,可多次调用追加。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 | |
operations | body | object[] | 否 | 暂存操作数组,元素结构见本组开头;可多次调用追加。 |
调用示例
curl -X POST \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502/operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"operations": [{"databaseId": "shop-db", "collectionId": "orders", "documentId": "order-1001", "action": "create", "data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}, {"databaseId": "shop-db", "collectionId": "orders", "documentId": "order-1002", "action": "delete"}]}'输出:201 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
PATCH /v1/databases/transactions/{transactionId}
提交(commit=true)或回滚(rollback=true)事务,二者只能选其一。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 | |
commit | body | boolean | 否 | 置 true 提交事务(与 rollback 互斥)。 | |
rollback | body | boolean | 否 | 置 true 回滚事务(与 commit 互斥)。 |
调用示例
curl -X PATCH \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"commit": true}'输出:200 + Models.Transaction。
响应示例:与同组上文已展示的 Models.Transaction 示例同构。
DELETE /v1/databases/transactions/{transactionId}
删除事务(丢弃其中的暂存操作)。
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
transactionId | path | string | 是 | 事务 ID。 |
调用示例
curl -X DELETE \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"输出:204 No Content,无响应体;无响应体。
错误与边界
- 库/表/行不存在:
404+database_not_found/table_not_found/row_not_found(旧版为collection_not_found/document_not_found,DocumentsDB 同旧版)。 - 库/表重复 ID:
409+database_already_exists/table_already_exists。 - 写行时列不匹配:缺必填列
row_invalid(结构 400),未知列会被拒或忽略以 spec 校验为准;列还在processing(202 未完成)时写入会失败。 - 建列/建索引为异步(202):需轮询
GET .../columns/{key}/.../indexes/{key}直到status=available,再执行依赖该列的读写。 - 数量与容量限额:库数、表数超限分别返回
database_limit_exceeded、table_limit_exceeded;库存储超限返回database_storage_limit_exceeded(413)。 - 事务:
commit与rollback不能同时为 true;事务内操作挂到过期事务返回 400;同一行在事务外并发写按后写覆盖,需要原子性时使用transactionId或increment/decrement。 - 批量更新/删除以
queries圈定范围,空queries会匹配全表——调用方必须显式带上过滤条件确认范围。 enabled=false(库/表/集合)只挡用户侧访问;API Key 路径不受影响,且切换不丢数据。- Schema 回滚不是数据回滚:回滚只恢复结构可见范围,期间写入的数据不删除;回滚后新列数据不可见但不丢失,再次前滚可恢复。
与 Server SDK 的对应
| service.method | 端点 | |||
|---|---|---|---|---|
TablesDB.list / create / get / update / delete | `GET | POST /tablesdb、GET | PUT | DELETE /tablesdb/{databaseId}` |
TablesDB.listTables / createTable / getTable / updateTable / deleteTable | /tablesdb/{databaseId}/tables 各 CRUD | |||
TablesDB.listColumns / getColumn / deleteColumn | .../columns、.../columns/{key} | |||
TablesDB.createBooleanColumn … createPolygonColumn(17 个类型方法)、updateBooleanColumn … updatePolygonColumn | `POST | PATCH .../columns/{type}、.../columns/{type}/{key}` | ||
TablesDB.createRelationshipColumn / updateRelationshipColumn | POST .../columns/relationship、PATCH .../columns/{key}/relationship | |||
TablesDB.updateColumnComment | PATCH .../columns/{key}/comment | |||
TablesDB.listIndexes / createIndex / getIndex / deleteIndex | .../indexes CRUD | |||
TablesDB.listRows / createRow / createRows / getRow / updateRow / upsertRow / upsertRows / updateRows / deleteRow / deleteRows | 行单条与批量端点(见上表) | |||
TablesDB.incrementRowColumn / decrementRowColumn | `PATCH .../rows/{rowId}/{column}/increment | decrement` | ||
TablesDB.aggregateRows | GET .../tables/{tableId}/aggregation | |||
TablesDB.listTransactions / createTransaction / getTransaction / updateTransaction / createOperations / deleteTransaction | /tablesdb/transactions* | |||
TablesDB.listSchemaVersions / createSchemaVersion / getSchemaVersion / rollbackSchemaVersion | /tablesdb/{databaseId}/schema/versions*、/schema/rollback/{versionId} | |||
DocumentsDB.list … DocumentsDB.incrementDocumentAttribute / decrementDocumentAttribute | /documentsdb 全部同构端点 | |||
Databases.list … Databases.decrementDocumentAttribute | /databases 全部同构端点(含 17 个 create{Type}Attribute / update{Type}Attribute 方法) |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(/tablesdb74、/documentsdb31、/databases68,三面共 173 个 HTTP 端点,其中POST …/rows|documents单端点承载单条与批量两个 SDK 方法;参数、响应模型database/table/column*/attribute*/row/document/transaction/schemaVersion等)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0TablesDB/DocumentsDB/Databasesservice。 - 2.7.0 行为增量:appbase release-2.7.0 PR 541(JsonTable 必填放宽;spec v2.6.0 → v2.7.0 databases 段无端点/参数变化,实读
git diff确认)。