1.5.4. /db/_design/design-doc/_view/view-name

GET /{db}/_design/{ddoc}/_view/{view}

从指定的设计文档中执行指定的视图函数。

参数：

• db – 数据库名称

• ddoc – 设计文档名称

• view – 视图函数名称

请求头：

• Accept –

  • application/json

  • text/plain

查询参数：

• conflicts (布尔值) – 在响应中包含 conflicts 信息。如果 include_docs 不是 true，则忽略。默认值为 false。

• descending (布尔值) – 按键降序返回文档。默认值为 false。

• endkey (json) – 当达到指定键时停止返回记录。

• end_key (json) – endkey 参数的别名

• endkey_docid (字符串) – 当达到指定文档 ID 时停止返回记录。如果未设置 endkey，则忽略。

• end_key_doc_id (字符串) – endkey_docid 的别名。

• group (布尔值) – 使用 reduce 函数将结果分组到一个组或单行。意味着 reduce 为 true 且最大 group_level。默认值为 false。

• group_level (数字) – 指定要使用的分组级别。意味着 group 为 true。

• include_docs (布尔值) – 在每行中包含关联的文档。默认值为 false。

• attachments (布尔值) – 如果 include_docs 为 true，则在包含的文档中包含 附件 的 Base64 编码内容。如果 include_docs 不是 true，则忽略。默认值为 false。

• att_encoding_info (布尔值) – 如果 include_docs 为 true 且特定附件已压缩，则在附件存根中包含编码信息。如果 include_docs 不是 true，则忽略。默认值为 false。

• inclusive_end (布尔值) – 指定是否应将指定的结束键包含在结果中。默认值为 true。

• key (json) – 仅返回与指定键匹配的文档。

• keys (json 数组) – 仅返回键与数组中指定的键之一匹配的文档。

• limit (数字) – 将返回的文档数量限制为指定数量。

• reduce (布尔值) – 使用 reduce 函数。如果定义了 reduce 函数，则默认值为 true。

• skip (数字) – 在开始返回结果之前跳过此数量的记录。默认值为 0。

• sorted (布尔值) – 对返回的行进行排序（参见 对返回的行进行排序）。将其设置为 false 可以提高性能。如果将其设置为 false，则 total_rows 和 offset 字段不可用。默认值为 true。

• stable (布尔值) – 视图结果是否应从一组稳定的分片中返回。默认值为 false。

• stale (字符串) – 允许使用来自陈旧视图的结果。支持的值：ok 和 update_after。 ok 等效于 stable=true&update=false。 update_after 等效于 stable=true&update=lazy。默认行为等效于 stable=false&update=true。请注意，此参数已弃用。请改用 stable 和 update。有关更多详细信息，请参见 视图生成。

• startkey (json) – 从指定键开始返回记录。

• start_key (json) – startkey 的别名。

• startkey_docid (字符串) – 从指定文档 ID 开始返回记录。如果未设置 startkey，则忽略。

• start_key_doc_id (字符串) – startkey_docid 参数的别名

• update (字符串) – 视图是否应在响应用户之前更新。支持的值：true、false、lazy。默认值为 true。

• update_seq (布尔值) – 是否在响应中包含一个 update_seq 值，该值指示视图反映的数据库的序列 ID。默认值为 false。

响应头：

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

• ETag – 响应签名

• Transfer-Encoding – chunked

响应 JSON 对象：

• offset (数字) – 文档列表开始处的偏移量。

• rows (数组) – 视图行对象的数组。默认情况下，返回的信息仅包含文档 ID 和修订版。

• total_rows (数字) – 数据库/视图中的文档数量。

• update_seq (对象) – 数据库的当前更新序列。

状态码:

• 200 OK – 请求成功完成

• 400 Bad Request – 无效请求

• 401 Unauthorized – 需要读取权限

• 404 Not Found – 指定的数据库、设计文档或视图不存在

请求:

GET /recipes/_design/ingredients/_view/by_name HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:12:06 GMT
ETag: "2FOLSBSW4O6WB798XU4AQYA9B"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "SpaghettiWithMeatballs",
            "key": "meatballs",
            "value": 1
        },
        {
            "id": "SpaghettiWithMeatballs",
            "key": "spaghetti",
            "value": 1
        },
        {
            "id": "SpaghettiWithMeatballs",
            "key": "tomato sauce",
            "value": 1
        }
    ],
    "total_rows": 3
}

版本 1.6.0 中变更: 添加了 attachments 和 att_encoding_info 参数

版本 2.0.0 中变更: 添加了 sorted 参数

版本 2.1.0 中变更: 添加了 stable 和 update 参数

警告

不建议使用 attachments 参数在视图结果中包含附件，特别是对于大型附件。另外请注意，使用的 Base64 编码会导致附件传输大小增加 33%（即三分之一）。

POST /{db}/_design/{ddoc}/_view/{view}

执行指定设计文档中的指定视图函数。 POST 视图功能支持与 GET /{db}/_design/{ddoc}/_view/{view} API 中指定的参数和行为相同的参数，但允许将查询字符串参数作为 JSON 对象中的键提供在 POST 请求的主体中。

请求:

POST /recipes/_design/ingredients/_view/by_name HTTP/1.1
Accept: application/json
Content-Length: 37
Host: localhost:5984

{
    "keys": [
        "meatballs",
        "spaghetti"
    ]
}

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "6R5NM8E872JIJF796VF7WI3FZ"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "SpaghettiWithMeatballs",
            "key": "meatballs",
            "value": 1
        },
        {
            "id": "SpaghettiWithMeatballs",
            "key": "spaghetti",
            "value": 1
        }
    ],
    "total_rows": 3
}

1.5.4.1. 视图选项

在设计文档中，可以将两个视图索引选项定义为 options 对象的布尔属性。与其他查询选项不同，这些选项不是 URL 参数，因为它们在生成视图索引时生效，而不是在访问视图索引时生效。

• local_seq (布尔值): 使文档的本地序列号可用于映射函数（作为 _local_seq 文档属性）

• include_design (布尔值): 允许映射函数调用设计文档以及普通文档

1.5.4.2. 查询视图和索引

设计文档中视图的定义还会创建一个基于每个视图中定义的键信息的索引。索引的生成和使用显著提高了从视图中访问、搜索或选择文档的速度。

但是，当数据库中添加或修改新文档时，索引不会更新。相反，索引是在第一次访问视图时或在访问视图后更新文档时生成或更新的。在每种情况下，索引都会在对数据库执行视图查询之前更新。

在以下情况下，视图索引会增量更新

• 数据库中添加了新文档。

• 数据库中删除了文档。

• 数据库中的文档已更新。

当视图定义更改时，视图索引将完全重建。为此，在更新设计文档时会创建视图定义的“指纹”。如果指纹发生变化，则视图索引将完全重建。这确保了视图定义的更改会反映在视图索引中。

注意

当同一个视图组（即单个设计文档中定义的所有视图）中的一个视图被确定为需要重建时，就会发生视图索引重建。例如，如果您有一个包含不同视图的设计文档，并且您更新了数据库，那么设计文档中的所有三个视图索引都将更新。

由于视图是在查询时更新的，因此在访问视图时可能会导致返回信息的延迟，尤其是在数据库中存在大量文档且视图索引不存在的情况下。有一些方法可以缓解，但不能完全消除这些问题。这些方法包括

• 在允许插入或更新文档之前，在您的数据库上创建视图定义（以及关联的设计文档）。如果在访问视图时允许这样做，则可以增量更新索引。

• 手动强制从数据库请求视图。您可以在用户被允许使用视图之前执行此操作，或者您可以在添加或更新文档后手动访问视图。

• 使用 更改馈送 监控数据库的更改，然后访问视图以强制更新相应的视图索引。

这些方法都不能完全消除在访问视图时重建或更新索引的需要，但它们可能会减少索引更新对最终用户体验的影响。

另一种方法是允许用户访问视图索引的“过时”版本，而不是强制更新索引并显示更新的结果。使用过时视图可能不会返回最新的信息，但会使用现有版本的索引返回视图查询的结果。

例如，要访问 recipes 设计文档中现有的过时视图 by_recipe

https://127.0.0.1:5984/recipes/_design/recipes/_view/by_recipe?stale=ok

访问过时视图

• 不会触发视图索引的重建，即使自上次访问以来发生了更改。

• 如果存在当前版本，则返回视图索引的当前版本。

• 如果给定的视图索引不存在，则返回空结果集。

作为替代方法，您可以将 update_after 值用于 stale 参数。这会导致视图作为过时视图返回，但更新过程将在视图信息返回给客户端后触发。

除了使用过时视图之外，您还可以使用 update_seq 查询参数。使用此查询参数会生成视图信息，包括生成视图的数据库的更新序列。可以将返回的值与数据库信息中公开的当前更新序列（由 GET /{db} 返回）进行比较。

1.5.4.3. 对返回的行进行排序

返回数组中的每个元素都使用本机 UTF-8 排序根据已发出内容的键部分的内容进行排序。输出的基本顺序如下

• null

• false

• true

• 数字

• 文本（区分大小写，小写字母优先）

• 数组（根据每个元素的值，按顺序）

• 对象（根据键的值，按键顺序）

请求:

GET /db/_design/test/_view/sorting HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "8LA1LZPQ37B6R9U8BK9BGQH27"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "dummy-doc",
            "key": null,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": false,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": true,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 0,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 1,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 10,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 42,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "10",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "Hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                1,
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": {},
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": {
                "foo": "bar"
            },
            "value": null
        }
    ],
    "total_rows": 17
}

您可以通过将 descending 查询值设置为 true 来反转返回的视图信息的顺序

请求:

GET /db/_design/test/_view/sorting?descending=true HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "Z4N468R15JBT98OM0AMNSR8U"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "dummy-doc",
            "key": {
                "foo": "bar"
            },
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": {},
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                1,
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "Hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "10",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 42,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 10,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 1,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 0,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": true,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": false,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": null,
            "value": null
        }
    ],
    "total_rows": 17
}

1.5.4.3.1. 排序顺序和 startkey/endkey

排序方向在使用 startkey 和 endkey 查询参数应用的过滤之前应用。例如，以下查询

GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22 HTTP/1.1
Accept: application/json

在列出 carrots 和 egg 之间的所有匹配条目时将正常运行。如果使用 descending 查询参数反转输出顺序，则视图请求将不返回任何条目

GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22 HTTP/1.1
Accept: application/json
Host: localhost:5984

{
    "total_rows" : 26453,
    "rows" : [],
    "offset" : 21882
}

结果将为空，因为在应用键过滤器之前会反转视图中的条目，因此 endkey 的“egg”将在 startkey 的“carrots”之前看到，从而导致空列表。

相反，您应该反转提供给 startkey 和 endkey 参数的值，以匹配应用于键的降序排序。将前面的示例更改为

GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22 HTTP/1.1
Accept: application/json
Host: localhost:5984

1.5.4.3.2. 原始整理

默认情况下，CouchDB 使用 ICU 驱动程序对视图结果进行排序。在 Unicode 整理不重要的情况下，可以使用二进制整理来更快地构建视图。

要使用原始整理，请在设计文档的视图对象中添加 "options":{"collation":"raw"}。之后，视图将重新生成，并对相应的视图应用新的顺序。

另请参阅

视图整理

1.5.4.4. 使用限制和跳过行

默认情况下，视图返回所有结果。当结果数量较少时，这没问题，但当结果数量达到数十亿时，这可能会导致问题，因为客户端可能需要读取所有结果并消耗所有可用内存。

但可以通过指定 limit 查询参数来减少输出结果行。例如，使用 by_title 视图检索食谱列表，并限制为 5，仅返回 5 条记录，而视图中总共有 2667 条记录

请求:

GET /recipes/_design/recipes/_view/by_title?limit=5 HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "9Q6Q2GZKPH8D5F8L7PB6DBSS9"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset" : 0,
    "rows" : [
        {
            "id" : "3-tiersalmonspinachandavocadoterrine",
            "key" : "3-tier salmon, spinach and avocado terrine",
            "value" : [
                null,
                "3-tier salmon, spinach and avocado terrine"
            ]
        },
        {
            "id" : "Aberffrawcake",
            "key" : "Aberffraw cake",
            "value" : [
                null,
                "Aberffraw cake"
            ]
        },
        {
            "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
}

要省略一些记录，您可以使用 skip 查询参数

请求:

GET /recipes/_design/recipes/_view/by_title?limit=3&skip=2 HTTP/1.1
Accept: application/json
Host: localhost:5984

响应:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "H3G7YZSNIVRRHO5FXPE16NJHN"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "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
}

警告

不建议将 limit 和 skip 参数用于结果分页。阅读 分页食谱 了解原因以及如何更好地实现分页。

1.5.4.5. 向视图发送多个查询

版本 2.2 中新增。

POST /{db}/_design/{ddoc}/_view/{view}/queries

对指定设计文档中的视图函数执行多个指定的视图查询。

参数：

• db – 数据库名称

• ddoc – 设计文档名称

• view – 视图函数名称

请求头：

• Content-Type –

  • application/json

• Accept –

  • application/json

请求 JSON 对象:

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

响应头：

• Content-Type –

  • application/json

• ETag – 响应签名

• Transfer-Encoding – chunked

响应 JSON 对象：

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

状态码:

• 200 OK – 请求成功完成

• 400 Bad Request – 无效请求

• 401 Unauthorized – 需要读取权限

• 404 未找到 – 指定的数据库、设计文档或视图缺失

• 500 内部服务器错误 – 视图函数执行错误

请求:

POST /recipes/_design/recipes/_view/by_title/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 2016 11:17:07 GMT
ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "results" : [
        {
            "offset": 0,
            "rows": [
                {
                    "id": "SpaghettiWithMeatballs",
                    "key": "meatballs",
                    "value": 1
                },
                {
                    "id": "SpaghettiWithMeatballs",
                    "key": "spaghetti",
                    "value": 1
                },
                {
                    "id": "SpaghettiWithMeatballs",
                    "key": "tomato sauce",
                    "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
        }
    ]
}