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 (number) -- 复制品。每份文件的份数。
- cluster.q (number) -- 碎片。范围分区的数目。
- cluster.r (number) -- 阅读法定人数。在成功答复之前需要阅读的文档的一致副本数。
- cluster.w (number) -- 写下法定人数。在成功答复之前需要写入的文档副本数。
- compact_running (boolean) -- 设置为
true
如果数据库压缩例程在此数据库上运行。 - db_name (string) -- 数据库的名称。
- disk_format_version (number) -- 数据存储在磁盘上时所使用的物理格式的版本。
- doc_count (number) -- 指定数据库中文档的计数。
- doc_del_count (number) -- 删除的文档数
- instance_start_time (string) -- 总是
"0"
. (由于遗留原因而返回。) - purge_seq (string) -- 描述数据库清除状态的不透明字符串。不要依赖此字符串来计算清除操作的数量。
- sizes.active (number) -- 数据库中实时数据的大小,以字节为单位。
- sizes.external (number) -- 数据库内容的未压缩大小(字节)。
- sizes.file (number) -- 磁盘上数据库文件的大小(以字节为单位)。计算中不包括视图索引。
- update_seq (string) -- 描述数据库状态的不透明字符串。不要依赖这个字符串来计算更新的数量。
- props.partitioned (boolean) -- (可选)如果存在且为true,则表示数据库已分区。
状态代码: - 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
) - 任何一个角色
_
,$
,(
,)
,+
,-
和/
.
如果你熟悉 Regular Expressions ,上面的规则可以写成
^[a-z][a-z0-9_$()+/-]*$
.参数: - db -- 数据库名称
查询参数: - q (integer) -- 碎片,也就是范围划分的数量。默认值为8,除非在
cluster config
. - n (integer) -- 复制品。群集中数据库的副本数。默认值为3,除非在
cluster config
. - partitioned (boolean) -- 是否创建分区数据库。默认值为false。
请求标头: - Accept --
- application/json
- text/plain
响应头: - Content-Type --
- application/json
- text/plain; charset=utf-8
- Location -- 数据库URI位置
响应JSON对象: - ok (boolean) -- 操作状态。成功时可用
- error (string) -- 类型错误。如果响应代码为
4xx
- reason (string) -- 错误描述。如果响应代码为
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: http://localhost: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=参数。这表明一个人想要删除一个文档,但是忘记了将文档id添加到URL中。
参数: - db -- 数据库名称
请求标头: - Accept --
- application/json
- text/plain
响应头: - Content-Type --
- application/json
- text/plain; charset=utf-8
响应JSON对象: - ok (boolean) -- 运行状态
状态代码: - 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 (string) -- 将文档存储在 batch mode 可能值:
ok
. 可选的
响应头: - Content-Type --
- application/json
- text/plain; charset=utf-8
- Location -- 文档的URI
响应JSON对象: - id (string) -- 文档ID
- ok (boolean) -- 运行状态
- rev (string) -- 修订信息
状态代码: - 201 Created -- 创建并存储在磁盘上的文档
- 202 Accepted -- 已接受文档数据,但尚未存储在磁盘上
- 400 Bad Request -- 数据库名称无效
- 401 Unauthorized -- 需要写入权限
- 404 Not Found -- 数据库不存在
- 409 Conflict -- 已存在具有相同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: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d Server: CouchDB (Erlang/OTP) { "id": "ab39fe0993049b84cfa81acd6ebad09d", "ok": true, "rev": "1-9c65296036141e575d32ba9c034dd3ee" }
1.3.1.1. 指定文档ID¶
可以通过包含 _id
已提交记录的JSON中的字段。下面的请求将使用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: http://localhost:5984/db/FishStew Server: CouchDB (Erlang/OTP) { "id": "FishStew", "ok": true, "rev": "1-9c65296036141e575d32ba9c034dd3ee" }
1.3.1.2. 批量写入模式¶
您可以使用批处理选项以更高的速率将文档写入数据库。这将在文档提交到磁盘之前将文档写入内存中(基于每个用户)。这增加了文档在发生故障时无法存储的风险,因为文档不会立即写入磁盘。
批处理模式不适用于关键数据,但可能是日志数据等应用程序的理想模式,因为崩溃导致某些数据丢失的风险是可接受的。
要使用批处理模式,请附加 batch=ok
的URL的查询参数 :post:`/{{db}}` , :put:`/{{db}}/{{docid}}` 或 :delete:`/{{db}}/{{docid}}` 请求。CouchDB服务器将用HTTP响应 202 Accepted 立即响应代码。
注解
使用批处理模式创建或更新文档不能保证所有文档都能成功存储在磁盘上。例如,个别文件可能因冲突而无法保存 validation function 或者由于其他原因,即使整个批次成功提交。
请求 :
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: http://localhost:5984/db/FishStew
Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
"ok": true
}