_all_docs`¶

GET /{db}/_all_docs¶

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

参数:	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` 但允许将查询字符串参数作为 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、revision和key。关键是设计文件的 _id .

参数:	db -- 数据库名称
请求标头:	Accept -- application/json text/plain
查询参数:	conflicts (boolean) -- 包括 conflicts 回应信息。忽略if include_docs 不是 `true` . 默认是 `false` . descending (boolean) -- 按键降序返回设计文档。默认为 `false` . endkey (string) -- 当达到指定的键时停止返回记录。可选的 . end_key (string) -- Alias endkey 参数。 endkey_docid (string) -- 达到指定的设计文档ID时停止返回记录。可选的 . end_key_doc_id (string) -- Alias endkey_docid 参数。 include_docs (boolean) -- 在报税表中包括设计文件的全部内容。默认为 `false` . inclusive_end (boolean) -- 指定指定的结束键是否应包含在结果中。默认为 `true` . key (string) -- 只返回与指定键匹配的设计文档。可选的 . keys (string) -- 只返回与指定键匹配的设计文档。可选的 . limit (number) -- 将返回的设计文件数量限制在指定数量内。可选的 . skip (number) -- 在开始返回结果之前跳过此数目的记录。默认为 `0` . startkey (string) -- 返回以指定键开头的记录。可选的 . start_key (string) -- Alias startkey 参数。 startkey_docid (string) -- 返回以指定的设计文档ID开头的记录。可选的 . start_key_doc_id (string) -- Alias startkey_docid 参数。 update_seq (boolean) -- 响应包括 `update_seq` 值，该值指示视图反映的基础数据库的序列id。默认为 `false` .
响应头:	Content-Type -- application/json text/plain; charset=utf-8 ETag -- 响应签名
响应JSON对象:	offset (number) -- 设计文档列表开始处的偏移量 rows (array) -- 视图行对象的数组。默认情况下，返回的信息仅包含设计文档ID和修订。 total_rows (number) -- 数据库中的设计文档数。请注意，这不是实际查询中返回的行数。 update_seq (number) -- 数据库的当前更新序列
状态代码:	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` 但允许将查询字符串参数作为 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是all documents结构，但输出中只有选定的键：

{
    "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 request .
响应头:	Content-Type -- application/json text/plain; charset=utf-8 ETag -- 响应签名 Transfer-Encoding -- `chunked`
响应JSON对象:	results (array) -- 结果对象的数组-每个查询一个。每个结果对象包含的字段与对常规 _all_docs request .
状态代码:	200 OK -- 请求已成功完成 400 Bad Request -- 无效请求 401 Unauthorized -- 需要读取权限 404 Not Found -- 缺少指定的数据库 500 Internal Server Error -- 查询执行错误

请求：

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/querys和/db/u design_docs/querys（类似于/db/u all_docs/querys）也支持多个查询。

1.3.4. `/{db}/_bulk_get`¶

POST /{db}/_bulk_get¶

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

参数:	db -- 数据库名称
请求标头:	Accept -- application/json multipart/related multipart/mixed Content-Type -- application/json
查询参数:	revs (boolean) -- 给出修订历史记录
请求JSON对象:	docs (array) -- 对象列表 `id` ，并且可以选择 `rev` 和 `atts_since`
响应头:	Content-Type -- application/json
响应JSON对象:	results (object) -- 每个请求的文档/版本对的结果数组。 `id` 键列出请求的文档ID， `docs` 包含对象的单个项数组，每个对象都有 `error` 描述错误的键和值，或 `ok` 所请求文档的键和关联值，以及 `_revisions` 属性列出父修订，如果 `revs=true` .
状态代码:	200 OK -- 请求已成功完成 400 Bad Request -- 请求提供了无效的JSON数据或无效的查询参数 401 Unauthorized -- 需要读取权限 404 Not Found -- 数据库名称无效 415 Unsupported Media Type -- 坏的 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 (array) -- 文档对象列表 new_edits (boolean) -- 如果 `false` ，阻止数据库为其分配新的修订ID。默认为 `true` . 可选的
响应头:	Content-Type -- application/json text/plain; charset=utf-8
对象的响应JSON数组:	id (string) -- 文档ID rev (string) -- 新建文档修订标记。如果文档保存时没有错误，则可用。可选的 error (string) -- 错误类型。可选的 reason (string) -- 错误原因。可选的
状态代码:	201 Created -- 文档已创建或更新 400 Bad Request -- 请求提供了无效的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树节点，大容量插入在存储空间和时间上都提高了效率。

它不是用来表演的 ACID -与CouchDB中的事务一样，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 Created ，返回结构的内容指示每个文档的特定成功或其他消息。

上述示例中的返回结构包含所创建文档的列表，其中包含组合及其修订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. 批量更新文档¶

批量文档更新过程与插入过程类似，只是必须在bulk update 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"
    }
]

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

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

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

1.3.5.3. 批量文档事务语义¶

批量文档操作是 non-atomic . 这意味着CouchDB不保证在发送请求时批量更新（或插入）中包含的任何单个文档都将被保存。响应将包含在此过程中成功插入或更新的文档列表。在崩溃的情况下，一些文档可能已成功保存，而其他文档则丢失。

响应结构将指示是否通过提供新的 _rev 指示已创建新文档修订的参数。如果更新失败，您将获得 error 类型的 conflict . 例如：

[
    {
        "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. 批量文档验证和冲突错误¶

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

当文档（或文档修订版）由于错误而未正确提交到数据库时，应检查 error 用于确定错误类型和操作过程的字段。错误将是以下类型之一：

conflict

提交的文件有冲突。新修订版尚未创建，您需要将文档重新提交到数据库。

使用“批量文档”界面添加的文档的冲突解决与解决复制过程中的冲突错误时使用的解决过程相同。

forbidden

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

例如，如果 validation routine 包括以下内容：

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¶