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 (boolean) -- 包括 conflicts 作为回应的信息。如果出现以下情况，则忽略
include_docs不是吗true。默认值为false。 - descending (boolean) -- 按键按降序返回文档。默认为
false. - endkey (json) -- 当达到指定的键时停止返回记录。
- end_key (json) -- 的别名
endkey参数 - endkey_docid (string) -- 当达到指定的文档ID时停止返回记录。如果出现以下情况，则忽略
endkey未设置。 - end_key_doc_id (string) -- 的别名
endkey_docid。 - group (boolean) -- 使用Reduce函数将结果分组为一组或单行。暗示
reduce是true最大的group_level。默认值为false。 - group_level (number) -- 指定要使用的组级别。暗示
group是true。 - include_docs (boolean) -- 在每行中包含关联的文档。默认为
false. - attachments (boolean) -- 包括的base64编码内容 attachments 在包含以下条件的文档中
include_docs是true。如果出现以下情况，则忽略include_docs不是吗true。默认值为false。 - att_encoding_info (boolean) -- 包括在附件存根中编码信息，如果
include_docs是true并且该特定附件被压缩。如果出现以下情况，则忽略include_docs不是吗true。默认值为false。 - inclusive_end (boolean) -- 指定指定的结束键是否应包含在结果中。默认为
true. - key (json) -- 只返回与指定键匹配的文档。
- keys (json-array) -- 只返回键与数组中指定的键之一匹配的文档。
- limit (number) -- 将返回的文档数限制在指定的数目内。
- reduce (boolean) -- 使用还原功能。默认为
true定义reduce函数时。 - skip (number) -- 在开始返回结果之前跳过此数目的记录。默认为
0. - sorted (boolean) -- 对返回的行进行排序(请参见 Sorting Returned Rows )。将此设置为
false提供性能提升。这个total_rows和offset当此选项设置为时，字段不可用false。默认值为true。 - stable (boolean) -- 是否应该从一组稳定的碎片返回视图结果。默认为
false. - stale (string) -- 允许使用来自过时视图的结果。支持的值：
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 (string) -- 返回以指定文档ID开头的记录。如果
startkey未设置。 - start_key_doc_id (string) -- 的别名
startkey_docid参数 - update (string) -- 是否应在响应用户之前更新相关视图。支持的值：
true，false，lazy. 默认是true. - update_seq (boolean) -- 是否在响应中包含
update_seq值，该值指示视图反映的数据库的序列ID。默认值为false。
响应头: - Content-Type --
- application/json
- text/plain; charset=utf-8
- ETag -- 响应签名
- Transfer-Encoding --
chunked
响应JSON对象: - offset (number) -- 文档列表开始处的偏移量。
- rows (array) -- 视图行对象的数组。默认情况下，返回的信息只包含文档ID和修订。
- total_rows (number) -- 数据库/视图中的文档数。
- update_seq (object) -- 数据库的当前更新序列。
状态代码: - 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}}` 但允许将查询字符串参数作为 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. 查询视图和索引¶
设计文档中的视图定义还基于每个视图中定义的关键信息创建索引。索引的生成和使用大大提高了访问和从视图中搜索或选择文档的速度。
但是，在数据库中添加或修改新文档时，索引不会更新。相反，索引是在第一次访问视图时生成或更新的，也可以是在更新文档后访问视图时生成或更新的。在每种情况下，索引都会在对数据库执行视图查询之前更新。
在以下情况下，视图索引将以增量方式更新：
- 已将新文档添加到数据库中。
- 文档已从数据库中删除。
- 数据库中的文档已更新。
当视图定义更改时，视图索引将完全重建。为此，更新设计文档时会创建视图定义的“指纹”。如果指纹发生变化，则视图索引将完全重建。这样可以确保对视图定义的更改反映在视图索引中。
注解
当同一视图组中的一个视图（即单个设计文档中定义的所有视图）被确定需要重新生成时，会发生视图索引重建。例如，如果设计文档具有不同的视图，并且更新了数据库，则设计文档中的所有三个视图索引都将更新。
因为查询视图时会更新视图，因此在访问视图时可能会导致返回信息的延迟，特别是在数据库中有大量文档且视图索引不存在的情况下。有许多方法可以减轻但不是完全消除这些问题。其中包括：
- 在允许插入或更新文档之前，请先在数据库中创建视图定义（以及关联的设计文档）。如果在访问视图时允许这样做，则可以增量更新索引。
- 手动从数据库强制执行视图请求。可以在允许用户使用视图之前执行此操作，也可以在添加或更新文档后手动访问该视图。
- 使用 changes feed 监视数据库的更改，然后访问视图以强制更新相应的视图索引。
这些都不能完全消除在访问视图时重建或更新索引的需要，但是它们可以减少索引更新对最终用户的影响，从而影响用户体验。
另一种方法是允许用户访问视图索引的“过时”版本，而不是强制更新索引并显示更新的结果。使用过时视图可能不会返回最新信息，但会使用现有版本的索引返回视图查询的结果。
例如，访问现有的过时视图 by_recipe 在 recipes 设计文件：
http://localhost:5984/recipes/_design/recipes/_view/by_recipe?stale=ok
访问过时视图：
- 不会触发视图索引的重建，即使自上次访问后发生了更改。
- 如果存在当前版本，则返回视图索引的当前版本。
- 如果给定的视图索引不存在，则返回空结果集。
作为一种选择，您可以使用 update_after 价值 stale 参数。这会导致视图作为过时视图返回，但会在视图信息返回给客户端后触发更新过程。
除了使用过时的视图之外，还可以使用 update_seq 查询参数。使用此查询参数生成视图信息，包括生成视图的数据库的更新序列。可以将返回的值与数据库信息中公开的当前更新序列（由返回 :get:`/{{db}}` ）
1.5.4.3. 对返回行排序¶
返回数组中的每个元素都使用本机UTF-8排序根据发出内容的键部分的内容进行排序。输出的基本顺序如下：
nullfalsetrue- 数字
- 文本（区分大小写，先小写）
- 数组（根据每个元素的值，按顺序）
- 对象（根据键的值，按键顺序）
请求 ：
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 查询参数。例如以下查询：
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 在“鸡蛋”出现之前 startkey “胡萝卜”，导致一个空列表。
相反，您应该将提供给 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.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 不建议将参数用于结果分页。阅读 pagination recipe 为什么是这样，如何让它变得更好。
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 -- 查询对象的数组，其中包含要执行的每个视图查询的参数字段。字段名及其含义与正则的查询参数相同 view request .
响应头: - Content-Type --
- application/json
- ETag -- 响应签名
- Transfer-Encoding --
chunked
响应JSON对象: - results (array) -- 结果对象的数组-每个查询一个。每个结果对象包含的字段与对常规 view request .
状态代码: - 200 OK -- 请求已成功完成
- 400 Bad Request -- 无效请求
- 401 Unauthorized -- 需要读取权限
- 404 Not Found -- 缺少指定的数据库、设计文档或视图
- 500 Internal Server Error -- 查看函数执行错误
请求 ：
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
}
]
}