Docs
文档目录

数据库 API

表格数据库全生命周期接口:库、表/集合、列/属性、索引、行/文档的 CRUD 与批量操作、事务、行聚合,以及 Schema 版本与回滚。本域覆盖三个并存的 service 面:

DocumentsDB 与旧版 Databases 没有 /aggregation(行聚合)与 /schema/versions(Schema 版本)端点——这两个能力只在 TablesDB 面。

服务与资源边界

数据库 API 基于底层 OceanBase 分布式存储引擎(如展示项目 enterprise-ai-hub-210 的 Shared V2 表池模式与业务库 enterprise_biz_db),统一暴露强 Schema 表格模型(TablesDB)、无固定列约束文档模型(DocumentsDB)与旧版兼容模型(Databases)三大访问面,支持单条/批量 CRUD、原子列增减、行级聚合统计、跨表 ACID 事务以及在线 Schema 版本提交与一键回滚。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 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 访问不受资源级权限约束。

端点总览

数据库模块共包含 173 个 HTTP 端点:其中 TablesDB(/v1/tablesdb/*)提供 74 个端点(涵盖库、表、17 种列类型、索引、行 CRUD、聚合、事务与 Schema 版本),DocumentsDB(/v1/documentsdb/*)提供 31 个端点,旧版 Databases(/v1/databases/*)提供 68 个端点。

端点清单

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 个端点)

两个面的端点形态与 TablesDB 完全同构,术语对照:table ↔ collection、row ↔ document、column ↔ attribute。差异只有两处:无 /aggregation 与 /schema/*;旧版属性与索引是独立端点组(POST .../attributes/{type}、POST .../indexes),DocumentsDB 的集合级 attributes 数组在创建/更新集合时一并提交。逐端点完整规格见下方三节。

端点详解

示例约定

本节起的逐端点示例共用以下约定,替换示例变量值即可直接复制执行:

请求与响应

库(database)

表与集合

列(17 种类型)

POST .../columns/{type} 创建;PATCH .../columns/{type}/{key} 更新;GET .../columns/{key}、DELETE .../columns/{key} 读取/删除。创建响应为 202(异步建列),更新响应为 200。列类型与专有参数:

type专有参数(除 key、required 外)
stringsize(必填,字符数)、default、array、encrypt(加密后不可查询)
varcharsize(必填,最大 16381)、default、array、encrypt
text / mediumtext / longtextdefault、array、encrypt
email / url / ipdefault、array
integermin、max、default、array
floatmin、max、default、array
booleandefault、array
datetimedefault(ISO 8601)、array
enumelements(必填,枚举值数组)、default、array
pointdefault([longitude, latitude])
linedefault(二维坐标对数组)
polygondefault(三维环数组,首环为外边界)
relationshiptype(必填: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*。

索引

行 / 文档

聚合(仅 TablesDB)

GET /tablesdb/{databaseId}/tables/{tableId}/aggregation:

参数位置必填说明
selectquery是聚合表达式与分组列,支持 count/sum/avg/min/max 与 AS 别名;普通列必须出现在 groupBy
groupByquery否分组列,最多 5 个标量列
queriesquery否仅过滤查询;分页、排序、游标、Query.select 不支持(会被拒绝)
transactionIdquery否读事务内未提交变更

返回 200 + rowAggregation(total + 聚合结果行)。

事务

Schema 版本与回滚(仅 TablesDB)

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 搜索。

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
searchquerystring否关键词搜索,最长 256 字符。
totalqueryboolean否默认 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

创建库。

输入

参数位置类型必填默认/枚举说明
databaseIdbodystring是数据库唯一 ID。
namebodystring是名称,最长 128 字符。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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 获取库详情。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 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}

更新库名称与启用态。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
namebodystring否名称,最长 128 字符。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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 删除库。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 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 搜索。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
searchquerystring否关键词搜索,最长 256 字符。
totalqueryboolean否默认 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 定义。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdbodystring是表唯一 ID。
namebodystring是名称,最长 128 字符。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
rowSecuritybodyboolean否是否启用行级权限;启用后访问单行需持有行级或表级权限之一。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。
columnsbodyobject[]否建表即建列的列定义数组(key、type 必填;type ∈ string/varchar/text/mediumtext/longtext/integer/double/boolean/datetime/point/linestring/polygon,枚举用 type=string + format=enum + elements)。关系列必须走独立端点;含 previousKey 可改名不删列。
indexesbodyobject[]否建表/集合即建索引的定义数组(key、type、attributes 必填;orders、lengths 可选)。
commentbodystring否展示名/注释,最长 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}

获取表详情(含列、索引定义与容量信息)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 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 数组)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
namebodystring否名称,最长 128 字符。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
rowSecuritybodyboolean否是否启用行级权限;启用后访问单行需持有行级或表级权限之一。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。
columnsbodyobject[]否建表即建列的列定义数组(key、type 必填;type ∈ string/varchar/text/mediumtext/longtext/integer/double/boolean/datetime/point/linestring/polygon,枚举用 type=string + format=enum + elements)。关系列必须走独立端点;含 previousKey 可改名不删列。
indexesbodyobject[]否建表/集合即建索引的定义数组(key、type、attributes 必填;orders、lengths 可选)。
skipOnEmptybodyboolean否置 true 时忽略空的 columns/indexes 数组;false(默认)时空数组表示清空全部用户定义结构。
commentbodystring否展示名/注释,最长 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}

删除表。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 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 区分)
statusavailable / processing / deleting / stuck / failed
error失败原因(无错误为空串)
required / array必填性 / 是否数组列
$createdAt / $updatedAt创建/更新时间

生命周期要点:

GET /v1/tablesdb/{databaseId}/tables/{tableId}/columns

列出表的全部列(含建列进度 status)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
totalqueryboolean否默认 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyboolean否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
elementsbodystring[]是枚举值数组(非空 string 数组),default 必须取自其中。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodynumber否最小值下界。
maxbodynumber否最大值上界。
defaultbodynumber否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodyinteger否最小值下界。
maxbodyinteger否最大值上界。
defaultbodyinteger否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
relatedTableIdbodystring是关联表 ID。关系列创建后不可更改对侧表。
typebodystring是枚举 oneToOne / manyToOne / manyToMany / oneToMany关系类型:oneToOne / manyToOne / manyToMany / oneToMany。
twoWaybodyboolean否是否双向关系。双向时需提供 twoWayKey。
keybodystring否列/属性 key。字符约束同资源 ID,表/集合内唯一。
twoWayKeybodystring否双向关系在对侧表/集合上的反向列 key。
onDeletebodystring否枚举 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
sizebodyinteger是字符数上限。string/varchar 创建时必填;varchar 上限 16381。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
sizebodyinteger是字符数上限。string/varchar 创建时必填;varchar 上限 16381。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyboolean是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
elementsbodystring[]是枚举值数组(非空 string 数组),default 必须取自其中。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodynumber否最小值下界。
maxbodynumber否最大值上界。
defaultbodynumber是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodyinteger否最小值下界。
maxbodyinteger否最大值上界。
defaultbodyinteger是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
sizebodyinteger否字符数上限。string/varchar 创建时必填;varchar 上限 16381。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
sizebodyinteger否字符数上限。string/varchar 创建时必填;varchar 上限 16381。
newKeybodystring否新 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}

获取单列定义与状态。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 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。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
commentbodystring是展示名/注释,最长 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 key(path 参数)。
onDeletebodystring否枚举 cascade / restrict / setNull删除关联行时的约束:cascade(级联删除)/ restrict(阻止删除)/ setNull(置空)。
newKeybodystring否新 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}

删除列(异步)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 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
typekey / fulltext / unique / spatial
statusavailable / 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 过滤)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
totalqueryboolean否默认 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}

获取索引定义与状态。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
typebodystring是枚举 key / fulltext / unique / spatial索引类型:key(普通)/ fulltext(全文)/ unique(唯一)/ spatial(空间)。
columnsbodystring[]是参与索引的列 key 数组;orders/lengths 与之按位对应。
ordersbodystring[]否各索引列的排序方向:ASC / DESC(与列按位对应)。
lengthsbodyinteger[]否各索引列的前缀长度(整数数组,与列按位对应)。

调用示例

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}

删除索引。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
keypathstring是列/属性 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。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdquerystring否事务 ID。
totalqueryboolean否默认 true置 false 时跳过计数,响应中的 total 恒为 0。
ttlqueryinteger否默认 0select 查询的响应缓存 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,单条)

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowIdbodystring是行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。
databodyobject是数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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,批量)

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowsbodyobject[]是行数据对象数组,可含部分字段(配合批量 upsert)。
transactionIdbodystring否事务 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowsbodyobject[]是行数据对象数组,可含部分字段(配合批量 upsert)。
transactionIdbodystring否事务 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 批量更新行,返回受影响行。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
queriesbodystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdbodystring否事务 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 批量删除行,返回受影响行。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
queriesbodystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdbodystring否事务 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 获取单行。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowIdpathstring是行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdquerystring否事务 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowIdpathstring是行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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 只含需更新的列)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowIdpathstring是行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowIdpathstring是行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。
columnpathstring是列 key(path 参数)。
valuebodynumber否增量值(数字),默认 1。
minbodynumber否自减的下界,越界报错不写入。
transactionIdbodystring否事务 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowIdpathstring是行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。
columnpathstring是列 key(path 参数)。
valuebodynumber否增量值(数字),默认 1。
maxbodynumber否自增的上界,越界报错不写入。
transactionIdbodystring否事务 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}

删除行,可挂到事务。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
rowIdpathstring是行唯一 ID。自定义或 ID.unique() 生成;字符 a-z、A-Z、0-9、.、-、_,不以特殊字符开头,最长 36 字符。
transactionIdbodystring否事务 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,可按列分组)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
tableIdpathstring是表唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
groupByquerystring[]否分组列,最多 5 个标量列。
selectquerystring[]是聚合表达式与分组列。支持 count/sum/avg/min/max 与 AS 别名;普通列必须同时出现在 groupBy。
transactionIdquerystring否事务 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创建/更新时间
statuspending → committing → committed / rolled_back / failed
operations已暂存的操作数
expiresAt过期时间;过期后未提交操作作废

POST …/operations 的 operations[] 元素结构(databaseId、action、tableId 必填;data 为操作负载):

action额外必填说明
create / update / upsert / increment / decrementrowId、data单行操作,data 为列值对象
deleterowId删除单行
bulkCreate / bulkUpdate / bulkUpsert / bulkDeletedata批量操作,data 为对象数组

操作分多次调用追加,commit 前不生效;行/文档读写端点也可直接传 transactionId 把单次操作挂到事务。

GET /v1/tablesdb/transactions

分页列出事务。

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否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 控制有效期。

输入

参数位置类型必填默认/枚举说明
ttlbodyinteger否事务有效期(秒),过期后未提交的暂存操作作废。

调用示例

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}

获取事务状态与暂存操作计数。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 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

向事务批量暂存操作,可多次调用追加。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 ID。
operationsbodyobject[]否暂存操作数组,元素结构见本组开头;可多次调用追加。

调用示例

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)事务,二者只能选其一。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 ID。
commitbodyboolean否置 true 提交事务(与 rollback 互斥)。
rollbackbodyboolean否置 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}

删除事务(丢弃其中的暂存操作)。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 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,用于幂等
statuspending / running / applying → active / failed;被新版本取代后为 deprecated
migrationPlanJson迁移计划(additive / compatible / destructive 分组)
stepsTotal / stepsCompletedDDL 步骤总数 / 已完成数
errorMessage失败原因
lastHeartbeatAt迁移 Worker 最近心跳
deprecatedColumns本次被弃用的列

同一数据库同时只允许一个 in-flight 版本(重复提交返回 409);迁移 Worker 应用计划后会重读实际结构校验,一致才置 active,否则置 failed 并保留原 active 版本。调用方轮询 GET …/schema/versions/{versionId} 至终态即可,不要自行重放 DDL。

GET /v1/tablesdb/{databaseId}/schema/versions

列出 Schema 版本(默认按版本号降序)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
totalqueryboolean否默认 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 版本状态与迁移进度。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
versionIdpathstring是目标 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、不删数据)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
versionIdpathstring是目标 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 相同则幂等复用已有版本。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
schemabodyobject是完整结构定义 JSON 对象,含 tables 数组(整库快照,不是 diff patch)。
modebodystring否枚举 migration / baselinemigration(默认,对 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 搜索。

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
searchquerystring否关键词搜索,最长 256 字符。
totalqueryboolean否默认 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

创建库。

输入

参数位置类型必填默认/枚举说明
databaseIdbodystring是数据库唯一 ID。
namebodystring是名称,最长 128 字符。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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 获取库详情。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 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}

更新库名称与启用态。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
namebodystring是名称,最长 128 字符。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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 删除库。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 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 搜索。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
searchquerystring否关键词搜索,最长 256 字符。
totalqueryboolean否默认 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 定义。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdbodystring是集合唯一 ID。
namebodystring是名称,最长 128 字符。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
documentSecuritybodyboolean否是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。
attributesbodyobject[]否建集合即建属性的定义数组,字段同 TablesDB 的 columns(key、type 必填等)。
indexesbodyobject[]否建表/集合即建索引的定义数组(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}

获取集合详情(含属性、索引定义)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 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 数组)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
namebodystring是名称,最长 128 字符。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
documentSecuritybodyboolean否是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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}

删除集合。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 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
typekey / fulltext / unique / spatial
statusavailable / 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 过滤)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
totalqueryboolean否默认 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}

获取索引定义与状态。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
typebodystring是枚举 key / fulltext / unique / spatial索引类型:key(普通)/ fulltext(全文)/ unique(唯一)/ spatial(空间)。
attributesbodystring[]是参与索引的属性 key 数组;orders/lengths 与之按位对应。
ordersbodystring[]否各索引列的排序方向:ASC / DESC(与列按位对应)。
lengthsbodyinteger[]否各索引列的前缀长度(整数数组,与列按位对应)。

调用示例

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}

删除索引。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 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。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdquerystring否事务 ID。
totalqueryboolean否默认 true置 false 时跳过计数,响应中的 total 恒为 0。
ttlqueryinteger否默认 0select 查询的响应缓存 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,单条)

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdbodystring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
databodyobject是数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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,批量)

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentsbodyobject[]是文档数据对象数组,可含部分字段(配合批量 upsert)。
transactionIdbodystring否事务 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentsbodyobject[]是文档数据对象数组,可含部分字段(配合批量 upsert)。
transactionIdbodystring否事务 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 批量更新文档,返回受影响文档。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
queriesbodystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdbodystring否事务 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 批量删除文档,返回受影响文档。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
queriesbodystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdbodystring否事务 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 获取单文档。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdquerystring否事务 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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 只含需更新的属性)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
attributepathstring是属性 key(path 参数)。
valuebodynumber否增量值(数字),默认 1。
minbodynumber否自减的下界,越界报错不写入。
transactionIdbodystring否事务 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
attributepathstring是属性 key(path 参数)。
valuebodynumber否增量值(数字),默认 1。
maxbodynumber否自增的上界,越界报错不写入。
transactionIdbodystring否事务 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}

删除文档,可挂到事务。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
transactionIdbodystring否事务 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创建/更新时间
statuspending → committing → committed / rolled_back / failed
operations已暂存的操作数
expiresAt过期时间;过期后未提交操作作废

POST …/operations 的 operations[] 元素结构(databaseId、action、collectionId 必填;data 为操作负载):

action额外必填说明
create / update / upsert / increment / decrementdocumentId、data单文档操作,data 为列值对象
deletedocumentId删除单文档
bulkCreate / bulkUpdate / bulkUpsert / bulkDeletedata批量操作,data 为对象数组

操作分多次调用追加,commit 前不生效;行/文档读写端点也可直接传 transactionId 把单次操作挂到事务。

GET /v1/documentsdb/transactions

分页列出事务。

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否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 控制有效期。

输入

参数位置类型必填默认/枚举说明
ttlbodyinteger否事务有效期(秒),过期后未提交的暂存操作作废。

调用示例

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}

获取事务状态与暂存操作计数。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 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

向事务批量暂存操作,可多次调用追加。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 ID。
operationsbodyobject[]否暂存操作数组,元素结构见本组开头;可多次调用追加。

调用示例

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)事务,二者只能选其一。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 ID。
commitbodyboolean否置 true 提交事务(与 rollback 互斥)。
rollbackbodyboolean否置 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}

删除事务(丢弃其中的暂存操作)。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 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)

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
searchquerystring否关键词搜索,最长 256 字符。
totalqueryboolean否默认 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)

输入

参数位置类型必填默认/枚举说明
databaseIdbodystring是数据库唯一 ID。
namebodystring是名称,最长 128 字符。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
namebodystring否名称,最长 128 字符。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 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 搜索。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
searchquerystring否关键词搜索,最长 256 字符。
totalqueryboolean否默认 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 定义。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdbodystring是集合唯一 ID。
namebodystring是名称,最长 128 字符。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
documentSecuritybodyboolean否是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 API Key 的服务端仍可读写,切换不丢数据。
attributesbodyobject[]否建集合即建属性的定义数组,字段同 TablesDB 的 columns(key、type 必填等)。
indexesbodyobject[]否建表/集合即建索引的定义数组(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}

获取集合详情(含属性、索引定义)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 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 数组)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
namebodystring否名称,最长 128 字符。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
documentSecuritybodyboolean否是否启用文档级权限;启用后访问单文档需持有文档级或集合级权限之一。
enabledbodyboolean否是否启用。停用后用户侧不可访问,但持 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}

删除集合。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 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 区分)
statusavailable / processing / deleting / stuck / failed
error失败原因(无错误为空串)
required / array必填性 / 是否数组列
$createdAt / $updatedAt创建/更新时间

生命周期要点:

GET /v1/databases/{databaseId}/collections/{collectionId}/attributes

列出集合的全部属性(含建属性进度 status)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
totalqueryboolean否默认 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyboolean否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
elementsbodystring[]是枚举值数组(非空 string 数组),default 必须取自其中。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodynumber否最小值下界。
maxbodynumber否最大值上界。
defaultbodynumber否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodyinteger否最小值下界。
maxbodyinteger否最大值上界。
defaultbodyinteger否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
relatedCollectionIdbodystring是关联集合 ID。关系属性创建后不可更改对侧集合。
typebodystring是枚举 oneToOne / manyToOne / manyToMany / oneToMany关系类型:oneToOne / manyToOne / manyToMany / oneToMany。
twoWaybodyboolean否是否双向关系。双向时需提供 twoWayKey。
keybodystring否列/属性 key。字符约束同资源 ID,表/集合内唯一。
twoWayKeybodystring否双向关系在对侧表/集合上的反向列 key。
onDeletebodystring否枚举 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
sizebodyinteger是字符数上限。string/varchar 创建时必填;varchar 上限 16381。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。

调用示例

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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
sizebodyinteger是字符数上限。string/varchar 创建时必填;varchar 上限 16381。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring否默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
arraybodyboolean否是否数组列。
encryptbodyboolean否是否加密存储。加密列不可用于查询、排序与索引。

调用示例

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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyboolean是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
elementsbodystring[]是枚举值数组(非空 string 数组),default 必须取自其中。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodynumber否最小值下界。
maxbodynumber否最大值上界。
defaultbodynumber是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
minbodyinteger否最小值下界。
maxbodyinteger否最大值上界。
defaultbodyinteger是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodyarray否默认坐标。point 为 [经度, 纬度];line 为坐标对数组 [[lon, lat], …];polygon 为环数组 [[[lon, lat], …], …](首环为外边界,每环首尾点相同)。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
onDeletebodystring否枚举 cascade / restrict / setNull删除关联行时的约束:cascade(级联删除)/ restrict(阻止删除)/ setNull(置空)。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
sizebodyinteger否字符数上限。string/varchar 创建时必填;varchar 上限 16381。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
newKeybodystring否新 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 改名)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 key(path 参数)。
requiredbodyboolean是是否必填。改为必填前需保证存量行该列均有值。
defaultbodystring是默认值(写入时未提供该列则填默认值)。必填列不可设置默认值;类型随列类型变化。
sizebodyinteger否字符数上限。string/varchar 创建时必填;varchar 上限 16381。
newKeybodystring否新 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}

获取单个属性定义与状态。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 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}

删除属性(异步)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 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
typekey / fulltext / unique / spatial
statusavailable / 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 过滤)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
totalqueryboolean否默认 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}

获取索引定义与状态。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keybodystring是列/属性 key。字符约束同资源 ID,表/集合内唯一。
typebodystring是枚举 key / fulltext / unique / spatial索引类型:key(普通)/ fulltext(全文)/ unique(唯一)/ spatial(空间)。
attributesbodystring[]是参与索引的属性 key 数组;orders/lengths 与之按位对应。
ordersbodystring[]否各索引列的排序方向:ASC / DESC(与列按位对应)。
lengthsbodyinteger[]否各索引列的前缀长度(整数数组,与列按位对应)。

调用示例

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}

删除索引。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
keypathstring是列/属性 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。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdquerystring否事务 ID。
totalqueryboolean否默认 true置 false 时跳过计数,响应中的 total 恒为 0。
ttlqueryinteger否默认 0select 查询的响应缓存 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,单条)

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdbodystring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
databodyobject是数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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,批量)

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentsbodyobject[]是文档数据对象数组,可含部分字段(配合批量 upsert)。
transactionIdbodystring否事务 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentsbodyobject[]是文档数据对象数组,可含部分字段(配合批量 upsert)。
transactionIdbodystring否事务 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 批量更新文档,返回受影响文档。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
queriesbodystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdbodystring否事务 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 批量删除文档,返回受影响文档。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
queriesbodystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdbodystring否事务 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 获取单文档。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
queriesquerystring[]否Query 查询字符串数组(如 equal("genre","sci-fi")、limit(25)),最多 100 条。
transactionIdquerystring否事务 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)

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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 只含需更新的属性)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
databodyobject否数据对象,键为列/属性 key。仅含需写入/更新的字段。
permissionsbodystring[]否权限字符串数组(如 read("any"))。默认不授予任何用户角色,语义见 permissions。
transactionIdbodystring否事务 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
attributepathstring是属性 key(path 参数)。
valuebodynumber否增量值(数字),默认 1。
minbodynumber否自减的下界,越界报错不写入。
transactionIdbodystring否事务 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)。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
attributepathstring是属性 key(path 参数)。
valuebodynumber否增量值(数字),默认 1。
maxbodynumber否自增的上界,越界报错不写入。
transactionIdbodystring否事务 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}

删除文档,可挂到事务。

输入

参数位置类型必填默认/枚举说明
databaseIdpathstring是数据库唯一 ID。
collectionIdpathstring是集合唯一 ID。
documentIdpathstring是文档唯一 ID。自定义或 ID.unique() 生成;字符约束同资源 ID,最长 36 字符。
transactionIdbodystring否事务 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创建/更新时间
statuspending → committing → committed / rolled_back / failed
operations已暂存的操作数
expiresAt过期时间;过期后未提交操作作废

POST …/operations 的 operations[] 元素结构(databaseId、action、collectionId 必填;data 为操作负载):

action额外必填说明
create / update / upsert / increment / decrementdocumentId、data单文档操作,data 为列值对象
deletedocumentId删除单文档
bulkCreate / bulkUpdate / bulkUpsert / bulkDeletedata批量操作,data 为对象数组

操作分多次调用追加,commit 前不生效;行/文档读写端点也可直接传 transactionId 把单次操作挂到事务。

GET /v1/databases/transactions

分页列出事务。

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否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 控制有效期。

输入

参数位置类型必填默认/枚举说明
ttlbodyinteger否事务有效期(秒),过期后未提交的暂存操作作废。

调用示例

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}

获取事务状态与暂存操作计数。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 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

向事务批量暂存操作,可多次调用追加。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 ID。
operationsbodyobject[]否暂存操作数组,元素结构见本组开头;可多次调用追加。

调用示例

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)事务,二者只能选其一。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 ID。
commitbodyboolean否置 true 提交事务(与 rollback 互斥)。
rollbackbodyboolean否置 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}

删除事务(丢弃其中的暂存操作)。

输入

参数位置类型必填默认/枚举说明
transactionIdpathstring是事务 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,无响应体;无响应体。

错误与边界

与 Server SDK 的对应

service.method端点
TablesDB.list / create / get / update / deleteGET|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 … updatePolygonColumnPOST|PATCH .../columns/{type}、.../columns/{type}/{key}
TablesDB.createRelationshipColumn / updateRelationshipColumnPOST .../columns/relationship、PATCH .../columns/{key}/relationship
TablesDB.updateColumnCommentPATCH .../columns/{key}/comment
TablesDB.listIndexes / createIndex / getIndex / deleteIndex.../indexes CRUD
TablesDB.listRows / createRow / createRows / getRow / updateRow / upsertRow / upsertRows / updateRows / deleteRow / deleteRows行单条与批量端点(见上表)
TablesDB.incrementRowColumn / decrementRowColumnPATCH .../rows/{rowId}/{column}/increment|decrement
TablesDB.aggregateRowsGET .../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 方法)