1.3.1. `/db`¶

HEAD /{db}¶

返回包含有关指定数据库的少量信息的 HTTP 标头。由于响应主体为空，因此使用 HEAD 方法是检查数据库是否已存在的一种轻量级方法。

参数：

db – 数据库名称

状态代码：

200 OK – 数据库存在
404 Not Found – 请求的数据库未找到

请求:

HEAD /test HTTP/1.1
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:27:41 GMT
Server: CouchDB (Erlang/OTP)

GET /{db}¶

获取有关指定数据库的信息。

参数：

db – 数据库名称

请求标头：

Accept –
- application/json
- text/plain

响应标头：

Content-Type –
- application/json
- text/plain; charset=utf-8

响应 JSON 对象：

cluster.n (数字) – 复制品。每个文档的副本数量。
cluster.q (数字) – 分片。范围分区的数量。
cluster.r (数字) – 读取仲裁。在成功回复之前需要读取的文档一致副本数量。
cluster.w (数字) – 写入仲裁。在成功回复之前需要写入的文档副本数量。
compact_running (布尔值) – 如果数据库压缩例程正在对该数据库进行操作，则设置为 true。
db_name (字符串) – 数据库的名称。
disk_format_version (数字) – 数据存储在磁盘上时使用的物理格式的版本。
doc_count (数字) – 指定数据库中文档的数量。
doc_del_count (数字) – 已删除文档的数量
instance_start_time (字符串) – 始终为 "0"。（出于遗留原因返回。）
purge_seq (字符串) – 描述数据库的清除状态的不透明字符串。不要依赖此字符串来计算清除操作的数量。
sizes.active (数字) – 数据库内活动数据的字节大小。
sizes.external (数字) – 数据库内容的未压缩字节大小。
sizes.file (数字) – 数据库文件在磁盘上的字节大小。视图索引不包含在计算中。
update_seq (字符串) – 描述数据库状态的不透明字符串。不要依赖此字符串来计算更新的数量。
props.partitioned (布尔值) – （可选）如果存在且为真，则表示数据库已分区。

状态代码：

200 OK – 请求已成功完成
404 Not Found – 请求的数据库未找到

请求:

GET /receipts HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 258
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:38:57 GMT
Server: CouchDB (Erlang/OTP)

{
    "cluster": {
        "n": 3,
        "q": 8,
        "r": 2,
        "w": 2
    },
    "compact_running": false,
    "db_name": "receipts",
    "disk_format_version": 6,
    "doc_count": 6146,
    "doc_del_count": 64637,
    "instance_start_time": "0",
    "props": {},
    "purge_seq": 0,
    "sizes": {
        "active": 65031503,
        "external": 66982448,
        "file": 137433211
    },
    "update_seq": "292786-g1AAAAF..."
}

PUT /{db}¶

创建一个新的数据库。数据库名称 {db} 必须符合以下规则

名称必须以小写字母开头 (a-z)
小写字母 (a-z)
数字 (0-9)
任何字符 _, $, (, ), +, - 和 /。

如果您熟悉正则表达式，则上述规则可以写成 ^[a-z][a-z0-9_$()+/-]*$。

参数：

db – 数据库名称

查询参数：

q (整数) – 分片，即范围分区的数量。默认值为 8，除非在 cluster config 中被覆盖。
n (整数) – 复制品。集群中数据库副本的数量。默认值为 3，除非在 cluster config 中被覆盖。
partitioned (布尔值) – 是否创建分区数据库。默认值为 false。

请求标头：

Accept –
- application/json
- text/plain

响应标头：

Content-Type –
- application/json
- text/plain; charset=utf-8
Location – 数据库 URI 位置

响应 JSON 对象：

ok (布尔值) – 操作状态。在成功的情况下可用
error (字符串) – 错误类型。如果响应代码为 4xx，则可用
reason (字符串) – 错误描述。如果响应代码为 4xx，则可用

状态代码：

201 Created – 数据库已成功创建（仲裁已满足）
202 Accepted – 已接受（至少由一个节点接受）
400 Bad Request – 无效的数据库名称
401 Unauthorized – 需要 CouchDB 服务器管理员权限
412 Precondition Failed – 数据库已存在

请求:

PUT /db HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:45 GMT
Location: https://127.0.0.1:5984/db
Server: CouchDB (Erlang/OTP)

{
    "ok": true
}

如果我们对 CouchDB 重复相同的请求，它将以 412 响应，因为数据库已存在

请求:

PUT /db HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 412 Precondition Failed
Cache-Control: must-revalidate
Content-Length: 95
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:16 GMT
Server: CouchDB (Erlang/OTP)

{
    "error": "file_exists",
    "reason": "The database could not be created, the file already exists."
}

如果提供无效的数据库名称，CouchDB 将以 400 响应

请求:

PUT /_db HTTP/1.1
Accept: application/json
Host: localhost:5984

请求:

HTTP/1.1 400 Bad Request
Cache-Control: must-revalidate
Content-Length: 194
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:02:10 GMT
Server: CouchDB (Erlang/OTP)

{
    "error": "illegal_database_name",
    "reason": "Name: '_db'. Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
}

DELETE /{db}¶

删除指定数据库及其包含的所有文档和附件。

注意

为了避免删除数据库，当请求 URL 包含 ?rev= 参数时，CouchDB 将以 HTTP 状态代码 400 响应。这表明有人想要删除文档，但忘记将文档 ID 添加到 URL。

参数：

db – 数据库名称

请求标头：

Accept –
- application/json
- text/plain

响应标头：

Content-Type –
- application/json
- text/plain; charset=utf-8

响应 JSON 对象：

ok (布尔值) – 操作状态

状态代码：

200 OK – 数据库已成功删除（仲裁已满足，并且至少一个节点已删除数据库）
202 Accepted – 已接受（至少一个节点已删除，仲裁尚未满足）
400 Bad Request – 无效的数据库名称或意外忘记文档 ID
401 Unauthorized – 需要 CouchDB 服务器管理员权限
404 Not Found – 数据库不存在或无效的数据库名称

请求:

DELETE /db HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:54:00 GMT
Server: CouchDB (Erlang/OTP)

{
    "ok": true
}

POST /{db}¶

使用提供的 JSON 文档结构在指定数据库中创建一个新文档。

如果 JSON 结构包含 _id 字段，则文档将使用指定的文档 ID 创建。

如果未指定 _id 字段，则会生成一个新的唯一 ID，遵循该服务器为其配置的任何 UUID 算法。

参数：

db – 数据库名称

请求标头：

Accept –
- application/json
- text/plain
Content-Type – application/json

查询参数：

batch (字符串) – 将文档存储在批量模式中。可能的值：ok。可选

响应标头：

Content-Type –
- application/json
- text/plain; charset=utf-8
位置 – 文档的 URI

响应 JSON 对象：

id (字符串) – 文档 ID
ok (布尔值) – 操作状态
rev (字符串) – 修订信息

状态代码：

201 已创建 – 文档已创建并存储在磁盘上
202 已接受 – 文档数据已接受，但尚未存储在磁盘上
400 Bad Request – 无效的数据库名称
401 未授权 – 需要写入权限
404 未找到 – 数据库不存在
409 冲突 – 具有相同 ID 的冲突文档已存在

请求:

POST /db HTTP/1.1
Accept: application/json
Content-Length: 81
Content-Type: application/json

{
    "servings": 4,
    "subtitle": "Delicious with fresh bread",
    "title": "Fish Stew"
}

响应:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 95
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
Location: https://127.0.0.1:5984/db/ab39fe0993049b84cfa81acd6ebad09d
Server: CouchDB (Erlang/OTP)

{
    "id": "ab39fe0993049b84cfa81acd6ebad09d",
    "ok": true,
    "rev": "1-9c65296036141e575d32ba9c034dd3ee"
}

1.3.1.1. 指定文档 ID¶

可以通过在提交记录的 JSON 中包含 _id 字段来指定文档 ID。以下请求将使用 ID FishStew 创建相同的文档。

请求:

POST /db HTTP/1.1
Accept: application/json
Content-Length: 98
Content-Type: application/json

{
    "_id": "FishStew",
    "servings": 4,
    "subtitle": "Delicious with fresh bread",
    "title": "Fish Stew"
}

响应:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 71
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
ETag: "1-9c65296036141e575d32ba9c034dd3ee"
Location: https://127.0.0.1:5984/db/FishStew
Server: CouchDB (Erlang/OTP)

{
    "id": "FishStew",
    "ok": true,
    "rev": "1-9c65296036141e575d32ba9c034dd3ee"
}

1.3.1.2. 批量模式写入¶

您可以通过使用批量选项以更高的速率将文档写入数据库。这会将文档写入收集在一起，存储在内存中（按用户为单位），然后才能提交到磁盘。这会增加在发生故障时文档无法存储的风险，因为文档不会立即写入磁盘。

批量模式不适合关键数据，但可能非常适合日志数据等应用程序，在这种情况下，由于崩溃导致部分数据丢失的风险是可以接受的。

要使用批量模式，请将 batch=ok 查询参数附加到 POST /{db}、PUT /{db}/{docid} 或 DELETE /{db}/{docid} 请求的 URL。CouchDB 服务器将立即以 HTTP 202 已接受响应代码进行响应。

注意

使用批量模式创建或更新文档不能保证所有文档都将成功存储在磁盘上。例如，即使总体上批量提交成功，单个文档也可能由于冲突、被验证函数拒绝或其他原因而无法保存。

请求:

POST /db?batch=ok HTTP/1.1
Accept: application/json
Content-Length: 98
Content-Type: application/json

{
    "_id": "FishStew",
    "servings": 4,
    "subtitle": "Delicious with fresh bread",
    "title": "Fish Stew"
}

响应:

HTTP/1.1 202 Accepted
Cache-Control: must-revalidate
Content-Length: 28
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
Location: https://127.0.0.1:5984/db/FishStew
Server: CouchDB (Erlang/OTP)

{
    "id": "FishStew",
    "ok": true
}

1.3.1. /db¶

1.3.1.1. 指定文档 ID¶

1.3.1.2. 批量模式写入¶

1.3.1. `/db`¶