_all_docs`¶

GET /{db}/_all_docs¶

执行内置的 _all_docs 视图，返回数据库中的所有文档。除了 URL 参数（如下所述）之外，此端点与任何其他视图的工作方式相同。有关可用查询参数和返回数据的格式的完整说明，请参阅视图端点文档。

参数：

db – 数据库名称

请求头：

Content-Type – application/json

响应头：

Content-Type –
- application/json

状态码：

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

请求:

GET /db/_all_docs HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 10 Aug 2013 16:22:56 GMT
ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "16e458537602f5ef2a710089dffd9453",
            "key": "16e458537602f5ef2a710089dffd9453",
            "value": {
                "rev": "1-967a00dff5e02add41819138abb3284d"
            }
        },
        {
            "id": "a4c51cdfa2069f3e905c431114001aff",
            "key": "a4c51cdfa2069f3e905c431114001aff",
            "value": {
                "rev": "1-967a00dff5e02add41819138abb3284d"
            }
        },
        {
            "id": "a4c51cdfa2069f3e905c4311140034aa",
            "key": "a4c51cdfa2069f3e905c4311140034aa",
            "value": {
                "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
            }
        },
        {
            "id": "a4c51cdfa2069f3e905c431114003597",
            "key": "a4c51cdfa2069f3e905c431114003597",
            "value": {
                "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
            }
        },
        {
            "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
            "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
            "value": {
                "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
            }
        }
    ],
    "total_rows": 5
}

POST /{db}/_all_docs¶

POST _all_docs 功能支持与 GET /{db}/_all_docs API 中指定的相同参数和行为，但允许将查询字符串参数作为 JSON 对象中的键提供在 POST 请求的主体中。

请求:

POST /db/_all_docs HTTP/1.1
Accept: application/json
Content-Length: 70
Content-Type: application/json
Host: localhost:5984

{
    "keys" : [
        "Zingylemontart",
        "Yogurtraita"
    ]
}

响应:

{
    "total_rows" : 2666,
    "rows" : [
        {
            "value" : {
                "rev" : "1-a3544d296de19e6f5b932ea77d886942"
            },
            "id" : "Zingylemontart",
            "key" : "Zingylemontart"
        },
        {
            "value" : {
                "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
            },
            "id" : "Yogurtraita",
            "key" : "Yogurtraita"
        }
    ],
    "offset" : 0
}

1.3.3. `/{db}/_design_docs`¶

版本 2.2 中新增。

GET /{db}/_design_docs¶

返回给定数据库中所有设计文档的 JSON 结构。信息以包含有关返回结构的元信息的 JSON 结构的形式返回，包括所有设计文档的列表和基本内容，包括 ID、修订版和键。键是设计文档的 _id。

参数：

db – 数据库名称

请求头：

Accept –
- application/json
- text/plain

查询参数：

conflicts (布尔值) – 在响应中包含 conflicts 信息。如果 include_docs 不是 true，则忽略。默认值为 false。
descending (布尔值) – 按键降序返回设计文档。默认值为 false。
endkey (字符串) – 达到指定键时停止返回记录。可选。
end_key (字符串) – endkey 参数的别名。
endkey_docid (字符串) – 达到指定设计文档 ID 时停止返回记录。可选。
end_key_doc_id (字符串) – endkey_docid 参数的别名。
include_docs (布尔值) – 在返回中包含设计文档的完整内容。默认值为 false。
inclusive_end (布尔值) – 指定是否应将指定的结束键包含在结果中。默认值为 true。
key (字符串) – 仅返回与指定键匹配的设计文档。可选。
keys (字符串) – 仅返回与指定键匹配的设计文档。可选。
limit (数字) – 将返回的设计文档数量限制为指定数量。可选。
skip (数字) – 在开始返回结果之前跳过此数量的记录。默认值为 0。
startkey (字符串) – 从指定键开始返回记录。可选。
start_key (字符串) – startkey 参数的别名。
startkey_docid (字符串) – 从指定设计文档 ID 开始返回记录。可选。
start_key_doc_id (字符串) – startkey_docid 参数的别名。
update_seq (布尔值) – 响应包含一个 update_seq 值，指示底层数据库的哪个序列 ID 反映了视图。默认值为 false。

响应头：

Content-Type –
- application/json
- text/plain; charset=utf-8
ETag – 响应签名

响应 JSON 对象：

offset (数字) – 设计文档列表开始的偏移量
rows (数组) – 视图行对象的数组。默认情况下，返回的信息仅包含设计文档 ID 和修订版。
total_rows (数字) – 数据库中的设计文档数量。请注意，这不是实际查询中返回的行数。
update_seq (数字) – 数据库的当前更新序列

状态码：

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

请求:

GET /db/_design_docs HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 23 Dec 2017 16:22:56 GMT
ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "_design/ddoc01",
            "key": "_design/ddoc01",
            "value": {
                "rev": "1-7407569d54af5bc94c266e70cbf8a180"
            }
        },
        {
            "id": "_design/ddoc02",
            "key": "_design/ddoc02",
            "value": {
                "rev": "1-d942f0ce01647aa0f46518b213b5628e"
            }
        },
        {
            "id": "_design/ddoc03",
            "key": "_design/ddoc03",
            "value": {
                "rev": "1-721fead6e6c8d811a225d5a62d08dfd0"
            }
        },
        {
            "id": "_design/ddoc04",
            "key": "_design/ddoc04",
            "value": {
                "rev": "1-32c76b46ca61351c75a84fbcbceece2f"
            }
        },
        {
            "id": "_design/ddoc05",
            "key": "_design/ddoc05",
            "value": {
                "rev": "1-af856babf9cf746b48ae999645f9541e"
            }
        }
    ],
    "total_rows": 5
}

POST /{db}/_design_docs¶

POST _design_docs 功能支持与 GET /{db}/_design_docs API 中指定的相同参数和行为，但允许将查询字符串参数作为 JSON 对象中的键提供在 POST 请求的主体中。

请求:

POST /db/_design_docs HTTP/1.1
Accept: application/json
Content-Length: 70
Content-Type: application/json
Host: localhost:5984

{
    "keys" : [
        "_design/ddoc02",
        "_design/ddoc05"
    ]
}

返回的 JSON 是所有文档结构，但输出中只有选定的键。

{
    "total_rows" : 5,
    "rows" : [
        {
            "value" : {
                "rev" : "1-d942f0ce01647aa0f46518b213b5628e"
            },
            "id" : "_design/ddoc02",
            "key" : "_design/ddoc02"
        },
        {
            "value" : {
                "rev" : "1-af856babf9cf746b48ae999645f9541e"
            },
            "id" : "_design/ddoc05",
            "key" : "_design/ddoc05"
        }
    ],
    "offset" : 0
}

1.3.3.1. 向数据库发送多个查询¶

版本 2.2 中新增。

POST /{db}/_all_docs/queries¶

执行此数据库中所有文档的多个指定内置视图查询。这使您能够在单个请求中请求多个查询，而不是多个 POST /{db}/_all_docs 请求。

参数：

db – 数据库名称

请求头：

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

请求 JSON 对象：

queries – 一个查询对象的数组，其中包含要执行的每个单独视图查询的参数字段。字段名称及其含义与常规 _all_docs 请求的查询参数相同。

响应头：

Content-Type –
- application/json
- text/plain; charset=utf-8
ETag – 响应签名
Transfer-Encoding – chunked

响应 JSON 对象：

results (数组) – 结果对象数组 - 每个查询一个。每个结果对象包含与对常规 _all_docs 请求的响应相同的字段。

状态码：

200 OK – 请求成功完成
400 错误请求 – 无效请求
401 未授权 – 需要读取权限
404 未找到 – 指定的数据库不存在
500 内部服务器错误 – 查询执行错误

请求:

POST /db/_all_docs/queries HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:5984

{
    "queries": [
        {
            "keys": [
                "meatballs",
                "spaghetti"
            ]
        },
        {
            "limit": 3,
            "skip": 2
        }
    ]
}

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 20 Dec 2017 11:17:07 GMT
ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "results" : [
        {
            "rows": [
                {
                    "id": "meatballs",
                    "key": "meatballs",
                    "value": 1
                },
                {
                    "id": "spaghetti",
                    "key": "spaghetti",
                    "value": 1
                }
            ],
            "total_rows": 3
        },
        {
            "offset" : 2,
            "rows" : [
                {
                    "id" : "Adukiandorangecasserole-microwave",
                    "key" : "Aduki and orange casserole - microwave",
                    "value" : [
                        null,
                        "Aduki and orange casserole - microwave"
                    ]
                },
                {
                    "id" : "Aioli-garlicmayonnaise",
                    "key" : "Aioli - garlic mayonnaise",
                    "value" : [
                        null,
                        "Aioli - garlic mayonnaise"
                    ]
                },
                {
                    "id" : "Alabamapeanutchicken",
                    "key" : "Alabama peanut chicken",
                    "value" : [
                        null,
                        "Alabama peanut chicken"
                    ]
                }
            ],
            "total_rows" : 2667
        }
    ]
}

注意

多个查询也支持在 /db/_local_docs/queries 和 /db/_design_docs/queries 中（类似于 /db/_all_docs/queries）。

1.3.4. `/{db}/_bulk_get`¶

POST /{db}/_bulk_get¶

此方法可以用来批量查询多个文档。它非常适合获取文档的特定版本，例如复制器所做的那样，或者获取版本历史记录。

参数：

db – 数据库名称

请求头：

Accept –
- application/json
- multipart/related
- multipart/mixed
Content-Type – application/json

查询参数：

revs (布尔值) – 给出版本历史记录

请求 JSON 对象：

docs (数组) – 文档对象列表，包含 id，以及可选的 rev 和 atts_since

响应头：

Content-Type –
- application/json

响应 JSON 对象：

results (对象) – 每个请求的文档/版本对的结果数组。 id 键列出请求的文档 ID， docs 包含一个单项数组对象，每个对象都有一个 error 键和描述错误的值，或者 ok 键和请求文档的关联值，以及额外的 _revisions 属性，如果 revs=true，则列出父版本。

状态码：

200 OK – 请求成功完成
400 错误请求 – 请求提供了无效的 JSON 数据或无效的查询参数
401 未授权 – 需要读取权限
404 未找到 – 无效的数据库名称
415 不支持的媒体类型 – 错误的 Content-Type 值

请求:

POST /db/_bulk_get HTTP/1.1
Accept: application/json
Content-Type:application/json
Host: localhost:5984

{
    "docs": [
        {
            "id": "foo"
            "rev": "4-753875d51501a6b1883a9d62b4d33f91",
        },
        {
            "id": "foo"
            "rev": "1-4a7e4ae49c4366eaed8edeaea8f784ad",
        },
        {
            "id": "bar",
        }
        {
            "id": "baz",
        }
    ]
}

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 19 Mar 2018 15:27:34 GMT
Server: CouchDB (Erlang/OTP)

{
  "results": [
    {
      "id": "foo",
      "docs": [
        {
          "ok": {
            "_id": "foo",
            "_rev": "4-753875d51501a6b1883a9d62b4d33f91",
            "value": "this is foo",
            "_revisions": {
              "start": 4,
              "ids": [
                "753875d51501a6b1883a9d62b4d33f91",
                "efc54218773c6acd910e2e97fea2a608",
                "2ee767305024673cfb3f5af037cd2729",
                "4a7e4ae49c4366eaed8edeaea8f784ad"
              ]
            }
          }
        }
      ]
    },
    {
      "id": "foo",
      "docs": [
        {
          "ok": {
            "_id": "foo",
            "_rev": "1-4a7e4ae49c4366eaed8edeaea8f784ad",
            "value": "this is the first revision of foo",
            "_revisions": {
              "start": 1,
              "ids": [
                "4a7e4ae49c4366eaed8edeaea8f784ad"
              ]
            }
          }
        }
      ]
    },
    {
      "id": "bar",
      "docs": [
        {
          "ok": {
            "_id": "bar",
            "_rev": "2-9b71d36dfdd9b4815388eb91cc8fb61d",
            "baz": true,
            "_revisions": {
              "start": 2,
              "ids": [
                "9b71d36dfdd9b4815388eb91cc8fb61d",
                "309651b95df56d52658650fb64257b97"
              ]
            }
          }
        }
      ]
    },
    {
      "id": "baz",
      "docs": [
        {
          "error": {
            "id": "baz",
            "rev": "undefined",
            "error": "not_found",
            "reason": "missing"
          }
        }
      ]
    }
  ]
}

包含冲突文档的示例响应

请求:

POST /db/_bulk_get HTTP/1.1
Accept: application/json
Content-Type:application/json
Host: localhost:5984

{
    "docs": [
        {
            "id": "a"
        }
    ]
}

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 19 Mar 2018 15:27:34 GMT
Server: CouchDB (Erlang/OTP)

{
  "results": [
    {
      "id": "a",
      "docs": [
        {
          "ok": {
            "_id": "a",
            "_rev": "1-23202479633c2b380f79507a776743d5",
            "a": 1
          }
        },
        {
          "ok": {
            "_id": "a",
            "_rev": "1-967a00dff5e02add41819138abb3284d"
          }
        }
      ]
    }
  ]
}

1.3.5. `/{db}/_bulk_docs`¶

POST /{db}/_bulk_docs¶

批量文档 API 允许您在一个请求中同时创建和更新多个文档。基本操作类似于创建或更新单个文档，只是您将文档结构和信息批处理。

创建新文档时，文档 ID (_id) 是可选的。

要更新现有文档，您必须提供文档 ID、版本信息 (_rev) 和新的文档值。

在批量删除文档的情况下，所有字段（如文档 ID、版本信息和删除状态 (_deleted)）都是必需的。

参数：

db – 数据库名称

请求头：

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

请求 JSON 对象：

docs (数组) – 文档对象列表
new_edits (布尔值) – 如果为 false，则阻止数据库为它们分配新的版本 ID。默认值为 true。可选

响应头：

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

响应 JSON 对象数组:

id (字符串) – 文档 ID
rev (字符串) – 新的文档版本令牌。如果文档已保存且没有错误，则可用。可选
error (字符串) – 错误类型。可选
reason (字符串) – 错误原因。可选

状态码：

201 已创建 – 文档已创建或更新
400 错误请求 – 请求提供了无效的 JSON 数据
404 Not Found – 请求的数据库未找到

请求:

POST /db/_bulk_docs HTTP/1.1
Accept: application/json
Content-Length: 109
Content-Type:application/json
Host: localhost:5984

{
    "docs": [
        {
            "_id": "FishStew"
        },
        {
            "_id": "LambStew",
            "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
            "_deleted": true
        }
    ]
}

响应:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 144
Content-Type: application/json
Date: Mon, 12 Aug 2013 00:15:05 GMT
Server: CouchDB (Erlang/OTP)

[
    {
        "ok": true,
        "id": "FishStew",
        "rev":" 1-967a00dff5e02add41819138abb3284d"
    },
    {
        "ok": true,
        "id": "LambStew",
        "rev": "3-f9c62b2169d0999103e9f41949090807"
    }
]

1.3.5.1. 批量插入文档¶

每次在 CouchDB 中存储或更新文档时，内部 B 树都会更新。批量插入通过合并对中间 B 树节点的许多更新，在存储空间和时间方面都提供了效率提升。

它并非旨在作为在 CouchDB 中执行 ACID 类事务的方式，CouchDB 中唯一的事务边界是对单个数据库的单个更新。约束在批量文档事务语义中详细说明。

要将文档批量插入数据库，您需要提供一个 JSON 结构，其中包含要添加到数据库的文档数组。您可以包含文档 ID，也可以允许自动生成文档 ID。

例如，以下更新插入三个新文档，两个带有提供的文档 ID，一个将生成文档 ID

POST /source/_bulk_docs HTTP/1.1
Accept: application/json
Content-Length: 323
Content-Type: application/json
Host: localhost:5984

{
    "docs": [
        {
            "_id": "FishStew",
            "servings": 4,
            "subtitle": "Delicious with freshly baked bread",
            "title": "FishStew"
        },
        {
            "_id": "LambStew",
            "servings": 6,
            "subtitle": "Serve with a whole meal scone topping",
            "title": "LambStew"
        },
        {
            "servings": 8,
            "subtitle": "Hand-made dumplings make a great accompaniment",
            "title": "BeefStew"
        }
    ]
}

批量插入的返回类型将是 201 已创建，返回结构的内容指示每个文档的特定成功或其他消息。

上面示例的返回结构包含已创建的文档列表，这里包含组合及其版本 ID

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 215
Content-Type: application/json
Date: Sat, 26 Oct 2013 00:10:39 GMT
Server: CouchDB (Erlang OTP)

[
    {
        "id": "FishStew",
        "ok": true,
        "rev": "1-6a466d5dfda05e613ba97bd737829d67"
    },
    {
        "id": "LambStew",
        "ok": true,
        "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
    },
    {
        "id": "00a271787f89c0ef2e10e88a0c0003f0",
        "ok": true,
        "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
    }
]

有关返回 JSON 的语义内容和结构的详细信息，请参阅批量文档事务语义。批量更新文档时的冲突和验证错误必须单独处理；请参阅批量文档验证和冲突错误。

1.3.5.2. 批量更新文档¶

批量文档更新过程类似于插入过程，只是您必须为批量更新 JSON 字符串中的每个文档指定文档 ID 和当前版本。

例如，您可以发送以下请求

POST /recipes/_bulk_docs HTTP/1.1
Accept: application/json
Content-Length: 464
Content-Type: application/json
Host: localhost:5984

{
    "docs": [
        {
            "_id": "FishStew",
            "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
            "servings": 4,
            "subtitle": "Delicious with freshly baked bread",
            "title": "FishStew"
        },
        {
            "_id": "LambStew",
            "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
            "servings": 6,
            "subtitle": "Serve with a whole meal scone topping",
            "title": "LambStew"
        },
        {
            "_id": "BeefStew",
            "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
            "servings": 8,
            "subtitle": "Hand-made dumplings make a great accompaniment",
            "title": "BeefStew"
        }
    ]
}

返回结构是更新文档的 JSON，包含新的版本和 ID 信息

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 215
Content-Type: application/json
Date: Sat, 26 Oct 2013 00:10:39 GMT
Server: CouchDB (Erlang OTP)

[
    {
        "id": "FishStew",
        "ok": true,
        "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
    },
    {
        "id": "LambStew",
        "ok": true,
        "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
    },
    {
        "id": "BeefStew",
        "ok": true,
        "rev": "2-9801936a42f06a16f16c30027980d96f"
    }
]

您可以在批量更新期间选择性地删除文档，方法是在提交的 JSON 结构中，将每个文档 ID/版本组合添加 _deleted 字段，其值为 true。

批量插入的返回类型将是 201 已创建，返回结构的内容指示每个文档的特定成功或其他消息。

返回的 JSON 的内容和结构将取决于用于批量更新的事务语义；有关更多信息，请参阅批量文档事务语义。批量更新文档时的冲突和验证错误必须单独处理；请参阅批量文档验证和冲突错误。

1.3.5.3. 批量文档事务语义¶

批量文档操作是非原子的。这意味着 CouchDB 不保证在您发送请求时，批量更新（或插入）中包含的任何单个文档都会被保存。响应将包含在该过程中成功插入或更新的文档列表。如果发生崩溃，一些文档可能已成功保存，而另一些则丢失。

响应结构将指示文档是否已更新，方法是提供新的 _rev 参数，指示已创建新的文档版本。如果更新失败，您将获得一个类型为 conflict 的 error。例如

[
    {
        "id" : "FishStew",
        "error" : "conflict",
        "reason" : "Document update conflict."
    },
    {
        "id" : "LambStew",
        "error" : "conflict",
        "reason" : "Document update conflict."
    },
    {
        "id" : "BeefStew",
        "error" : "conflict",
        "reason" : "Document update conflict."
    }
]

在这种情况下，不会创建新的版本，您需要使用正确的版本标记重新提交文档更新以更新文档。

文档的复制与插入或更新的类型无关。在批量插入或更新期间创建的文档和版本以与任何其他文档相同的方式复制。

1.3.5.4. 批量文档验证和冲突错误¶

由 _bulk_docs 操作返回的 JSON 由一个 JSON 结构数组组成，每个结构对应于原始提交中的每个文档。应检查返回的 JSON 结构，以确保原始请求中提交的所有文档都已成功添加到数据库中。

当文档（或文档版本）由于错误而未正确提交到数据库时，您应该检查 error 字段以确定错误类型和操作步骤。错误将是以下类型之一

conflict

提交的文档存在冲突。不会创建新的版本，您需要将文档重新提交到数据库。

使用批量文档接口添加的文档的冲突解决与在复制期间解决冲突错误时使用的解决过程相同。

forbidden

带有此错误类型的条目表示在提交期间应用于文档的验证例程已返回错误。

例如，如果您的验证例程包含以下内容

throw({forbidden: 'invalid recipe ingredient'});

返回的错误响应将是

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 80
Content-Type: application/json
Date: Sat, 26 Oct 2013 00:05:17 GMT
Server: CouchDB (Erlang OTP)

[
    {
        "id": "LambStew",
        "error": "forbidden",
        "reason": "invalid recipe ingredient"
    }
]

1.3.2. /{db}/_all_docs¶

1.3.3. /{db}/_design_docs¶

1.3.3.1. 向数据库发送多个查询¶

1.3.4. /{db}/_bulk_get¶

1.3.5. /{db}/_bulk_docs¶

1.3.5.1. 批量插入文档¶

1.3.5.2. 批量更新文档¶

1.3.5.3. 批量文档事务语义¶

1.3.5.4. 批量文档验证和冲突错误¶

1.3.2. `/{db}/_all_docs`¶

1.3.3. `/{db}/_design_docs`¶

1.3.4. `/{db}/_bulk_get`¶

1.3.5. `/{db}/_bulk_docs`¶