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

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

Executes the specified view function from the specified design document.

  • Parameters

    • db – Database name

    • ddoc – Design document name

    • view – View function name

    Request Headers

    • Accept –

      • application/json

      • text/plain

    Query Parameters

    • conflicts (boolean) – Include conflicts information in response. Ignored if include_docs isn’t true. Default is false.

    • descending (boolean) – Return the documents in descending order by key. Default is false.

    • endkey (json) – Stop returning records when the specified key is reached.

    • end_key (json) – Alias for endkey param

    • endkey_docid (string) – Stop returning records when the specified document ID is reached. Ignored if endkey is not set.

    • end_key_doc_id (string) – Alias for endkey_docid.

    • group (boolean) – Group the results using the reduce function to a group or single row. Implies reduce is true and the maximum group_level. Default is false.

    • group_level (number) – Specify the group level to be used. Implies group is true.

    • include_docs (boolean) – Include the associated document with each row. Default is false.

    • attachments (boolean) – Include the Base64-encoded content of attachments in the documents that are included if include_docs is true. Ignored if include_docs isn’t true. Default is false.

    • att_encoding_info (boolean) – Include encoding information in attachment stubs if include_docs is true and the particular attachment is compressed. Ignored if include_docs isn’t true. Default is false.

    • inclusive_end (boolean) – Specifies whether the specified end key should be included in the result. Default is true.

    • key (json) – Return only documents that match the specified key.

    • keys (json-array) – Return only documents where the key matches one of the keys specified in the array.

    • limit (number) – Limit the number of the returned documents to the specified number.

    • reduce (boolean) – Use the reduction function. Default is true when a reduce function is defined.

    • skip (number) – Skip this number of records before starting to return the results. Default is 0.

    • sorted (boolean) – Sort returned rows (see Sorting Returned Rows). Setting this to false offers a performance boost. The total_rows and offset fields are not available when this is set to false. Default is true.

    • stable (boolean) – Whether or not the view results should be returned from a stable set of shards. Default is false.

    • stale (string) – Allow the results from a stale view to be used. Supported values: ok and update_after. ok is equivalent to stable=true&update=false. update_after is equivalent to stable=true&update=lazy. The default behavior is equivalent to stable=false&update=true. Note that this parameter is deprecated. Use stable and update instead. See Views Generation for more details.

    • startkey (json) – Return records starting with the specified key.

    • start_key (json) – Alias for startkey.

    • startkey_docid (string) – Return records starting with the specified document ID. Ignored if startkey is not set.

    • start_key_doc_id (string) – Alias for startkey_docid param

    • update (string) – Whether or not the view in question should be updated prior to responding to the user. Supported values: true, false, lazy. Default is true.

    • update_seq (boolean) – Whether to include in the response an update_seq value indicating the sequence id of the database the view reflects. Default is false.

    Response Headers

    Response JSON Object

    • offset (number) – Offset where the document list started.

    • rows (array) – Array of view row objects. By default the information returned contains only the document ID and revision.

    • total_rows (number) – Number of documents in the database/view.

    • update_seq (object) – Current update sequence for the database.

    Status Codes

Request:

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

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 21 Aug 2013 09:12:06 GMT
  5. ETag: "2FOLSBSW4O6WB798XU4AQYA9B"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  9. {
  10.     "offset": 0,
  11.     "rows": [
  12.         {
  13.             "id": "SpaghettiWithMeatballs",
  14.             "key": "meatballs",
  15.             "value": 1
  16.         },
  17.         {
  18.             "id": "SpaghettiWithMeatballs",
  19.             "key": "spaghetti",
  20.             "value": 1
  21.         },
  22.         {
  23.             "id": "SpaghettiWithMeatballs",
  24.             "key": "tomato sauce",
  25.             "value": 1
  26.         }
  27.     ],
  28.     "total_rows": 3
  29. }

Changed in version 1.6.0: added attachments and att_encoding_info parameters

Changed in version 2.0.0: added sorted parameter

Changed in version 2.1.0: added stable and update parameters

Warning

Using the attachments parameter to include attachments in view results is not recommended for large attachment sizes. Also note that the Base64-encoding that is used leads to a 33% overhead (i.e. one third) in transfer size for attachments.

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

Executes the specified view function from the specified design document. POST view functionality supports identical parameters and behavior as specified in the GET /{db}/_design/{ddoc}/_view/{view} API but allows for the query string parameters to be supplied as keys in a JSON object in the body of the POST request.

Request:

  1. POST /recipes/_design/ingredients/_view/by_name HTTP/1.1
  2. Accept: application/json
  3. Content-Length: 37
  4. Host: localhost:5984
  6. {
  7.     "keys": [
  8.         "meatballs",
  9.         "spaghetti"
  10.     ]
  11. }

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 21 Aug 2013 09:14:13 GMT
  5. ETag: "6R5NM8E872JIJF796VF7WI3FZ"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  9. {
  10.     "offset": 0,
  11.     "rows": [
  12.         {
  13.             "id": "SpaghettiWithMeatballs",
  14.             "key": "meatballs",
  15.             "value": 1
  16.         },
  17.         {
  18.             "id": "SpaghettiWithMeatballs",
  19.             "key": "spaghetti",
  20.             "value": 1
  21.         }
  22.     ],
  23.     "total_rows": 3
  24. }

1.5.4.1. View Options

There are two view indexing options that can be defined in a design document as boolean properties of an options object. Unlike the others querying options, these aren’t URL parameters because they take effect when the view index is generated, not when it’s accessed:

  • local_seq (boolean): Makes documents’ local sequence numbers available to map functions (as a _local_seq document property)

  • include_design (boolean): Allows map functions to be called on design documents as well as regular documents

1.5.4.2. Querying Views and Indexes

The definition of a view within a design document also creates an index based on the key information defined within each view. The production and use of the index significantly increases the speed of access and searching or selecting documents from the view.

However, the index is not updated when new documents are added or modified in the database. Instead, the index is generated or updated, either when the view is first accessed, or when the view is accessed after a document has been updated. In each case, the index is updated before the view query is executed against the database.

View indexes are updated incrementally in the following situations:

  • A new document has been added to the database.

  • A document has been deleted from the database.

  • A document in the database has been updated.

View indexes are rebuilt entirely when the view definition changes. To achieve this, a ‘fingerprint’ of the view definition is created when the design document is updated. If the fingerprint changes, then the view indexes are entirely rebuilt. This ensures that changes to the view definitions are reflected in the view indexes.

Note

View index rebuilds occur when one view from the same the view group (i.e. all the views defined within a single a design document) has been determined as needing a rebuild. For example, if you have a design document with different views, and you update the database, all three view indexes within the design document will be updated.

Because the view is updated when it has been queried, it can result in a delay in returned information when the view is accessed, especially if there are a large number of documents in the database and the view index does not exist. There are a number of ways to mitigate, but not completely eliminate, these issues. These include:

  • Create the view definition (and associated design documents) on your database before allowing insertion or updates to the documents. If this is allowed while the view is being accessed, the index can be updated incrementally.

  • Manually force a view request from the database. You can do this either before users are allowed to use the view, or you can access the view manually after documents are added or updated.

  • Use the changes feed to monitor for changes to the database and then access the view to force the corresponding view index to be updated.

None of these can completely eliminate the need for the indexes to be rebuilt or updated when the view is accessed, but they may lessen the effects on end-users of the index update affecting the user experience.

Another alternative is to allow users to access a ‘stale’ version of the view index, rather than forcing the index to be updated and displaying the updated results. Using a stale view may not return the latest information, but will return the results of the view query using an existing version of the index.

For example, to access the existing stale view by_recipe in the recipes design document:

  1. http://localhost:5984/recipes/_design/recipes/_view/by_recipe?stale=ok

Accessing a stale view:

  • Does not trigger a rebuild of the view indexes, even if there have been changes since the last access.

  • Returns the current version of the view index, if a current version exists.

  • Returns an empty result set if the given view index does not exist.

As an alternative, you use the update_after value to the stale parameter. This causes the view to be returned as a stale view, but for the update process to be triggered after the view information has been returned to the client.

In addition to using stale views, you can also make use of the update_seq query argument. Using this query argument generates the view information including the update sequence of the database from which the view was generated. The returned value can be compared this to the current update sequence exposed in the database information (returned by GET /{db}).

1.5.4.3. Sorting Returned Rows

Each element within the returned array is sorted using native UTF-8 sorting according to the contents of the key portion of the emitted content. The basic order of output is as follows:

  • null

  • false

  • true

  • Numbers

  • Text (case sensitive, lowercase first)

  • Arrays (according to the values of each element, in order)

  • Objects (according to the values of keys, in key order)

Request:

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

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 21 Aug 2013 10:09:25 GMT
  5. ETag: "8LA1LZPQ37B6R9U8BK9BGQH27"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  9. {
  10.     "offset": 0,
  11.     "rows": [
  12.         {
  13.             "id": "dummy-doc",
  14.             "key": null,
  15.             "value": null
  16.         },
  17.         {
  18.             "id": "dummy-doc",
  19.             "key": false,
  20.             "value": null
  21.         },
  22.         {
  23.             "id": "dummy-doc",
  24.             "key": true,
  25.             "value": null
  26.         },
  27.         {
  28.             "id": "dummy-doc",
  29.             "key": 0,
  30.             "value": null
  31.         },
  32.         {
  33.             "id": "dummy-doc",
  34.             "key": 1,
  35.             "value": null
  36.         },
  37.         {
  38.             "id": "dummy-doc",
  39.             "key": 10,
  40.             "value": null
  41.         },
  42.         {
  43.             "id": "dummy-doc",
  44.             "key": 42,
  45.             "value": null
  46.         },
  47.         {
  48.             "id": "dummy-doc",
  49.             "key": "10",
  50.             "value": null
  51.         },
  52.         {
  53.             "id": "dummy-doc",
  54.             "key": "hello",
  55.             "value": null
  56.         },
  57.         {
  58.             "id": "dummy-doc",
  59.             "key": "Hello",
  60.             "value": null
  61.         },
  62.         {
  63.             "id": "dummy-doc",
  64.             "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
  65.             "value": null
  66.         },
  67.         {
  68.             "id": "dummy-doc",
  69.             "key": [],
  70.             "value": null
  71.         },
  72.         {
  73.             "id": "dummy-doc",
  74.             "key": [
  75.                 1,
  76.                 2,
  77.                 3
  78.             ],
  79.             "value": null
  80.         },
  81.         {
  82.             "id": "dummy-doc",
  83.             "key": [
  84.                 2,
  85.                 3
  86.             ],
  87.             "value": null
  88.         },
  89.         {
  90.             "id": "dummy-doc",
  91.             "key": [
  92.                 3
  93.             ],
  94.             "value": null
  95.         },
  96.         {
  97.             "id": "dummy-doc",
  98.             "key": {},
  99.             "value": null
  100.         },
  101.         {
  102.             "id": "dummy-doc",
  103.             "key": {
  104.                 "foo": "bar"
  105.             },
  106.             "value": null
  107.         }
  108.     ],
  109.     "total_rows": 17
  110. }

You can reverse the order of the returned view information by using the descending query value set to true:

Request:

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

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 21 Aug 2013 10:09:25 GMT
  5. ETag: "Z4N468R15JBT98OM0AMNSR8U"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  9. {
  10.     "offset": 0,
  11.     "rows": [
  12.         {
  13.             "id": "dummy-doc",
  14.             "key": {
  15.                 "foo": "bar"
  16.             },
  17.             "value": null
  18.         },
  19.         {
  20.             "id": "dummy-doc",
  21.             "key": {},
  22.             "value": null
  23.         },
  24.         {
  25.             "id": "dummy-doc",
  26.             "key": [
  27.                 3
  28.             ],
  29.             "value": null
  30.         },
  31.         {
  32.             "id": "dummy-doc",
  33.             "key": [
  34.                 2,
  35.                 3
  36.             ],
  37.             "value": null
  38.         },
  39.         {
  40.             "id": "dummy-doc",
  41.             "key": [
  42.                 1,
  43.                 2,
  44.                 3
  45.             ],
  46.             "value": null
  47.         },
  48.         {
  49.             "id": "dummy-doc",
  50.             "key": [],
  51.             "value": null
  52.         },
  53.         {
  54.             "id": "dummy-doc",
  55.             "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
  56.             "value": null
  57.         },
  58.         {
  59.             "id": "dummy-doc",
  60.             "key": "Hello",
  61.             "value": null
  62.         },
  63.         {
  64.             "id": "dummy-doc",
  65.             "key": "hello",
  66.             "value": null
  67.         },
  68.         {
  69.             "id": "dummy-doc",
  70.             "key": "10",
  71.             "value": null
  72.         },
  73.         {
  74.             "id": "dummy-doc",
  75.             "key": 42,
  76.             "value": null
  77.         },
  78.         {
  79.             "id": "dummy-doc",
  80.             "key": 10,
  81.             "value": null
  82.         },
  83.         {
  84.             "id": "dummy-doc",
  85.             "key": 1,
  86.             "value": null
  87.         },
  88.         {
  89.             "id": "dummy-doc",
  90.             "key": 0,
  91.             "value": null
  92.         },
  93.         {
  94.             "id": "dummy-doc",
  95.             "key": true,
  96.             "value": null
  97.         },
  98.         {
  99.             "id": "dummy-doc",
  100.             "key": false,
  101.             "value": null
  102.         },
  103.         {
  104.             "id": "dummy-doc",
  105.             "key": null,
  106.             "value": null
  107.         }
  108.     ],
  109.     "total_rows": 17
  110. }

1.5.4.3.1. Sorting order and startkey/endkey

The sorting direction is applied before the filtering applied using the startkey and endkey query arguments. For example the following query:

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

will operate correctly when listing all the matching entries between carrots and egg. If the order of output is reversed with the descending query argument, the view request will return no entries:

  1. GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22 HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984
  5. {
  6.     "total_rows" : 26453,
  7.     "rows" : [],
  8.     "offset" : 21882
  9. }

The results will be empty because the entries in the view are reversed before the key filter is applied, and therefore the endkey of “egg” will be seen before the startkey of “carrots”, resulting in an empty list.

Instead, you should reverse the values supplied to the startkey and endkey parameters to match the descending sorting applied to the keys. Changing the previous example to:

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

1.5.4.3.2. Raw collation

By default CouchDB uses an ICU driver for sorting view results. It’s possible use binary collation instead for faster view builds where Unicode collation is not important.

To use raw collation add "options":{"collation":"raw"} within the view object of the design document. After that, views will be regenerated and new order applied for the appropriate view.

See also

Views Collation

1.5.4.4. Using Limits and Skipping Rows

By default, views return all results. That’s ok when the number of results is small, but this may lead to problems when there are billions results, since the client may have to read them all and consume all available memory.

But it’s possible to reduce output result rows by specifying limit query parameter. For example, retrieving the list of recipes using the by_title view and limited to 5 returns only 5 records, while there are total 2667 records in view:

Request:

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

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 21 Aug 2013 09:14:13 GMT
  5. ETag: "9Q6Q2GZKPH8D5F8L7PB6DBSS9"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  9. {
  10.     "offset" : 0,
  11.     "rows" : [
  12.         {
  13.             "id" : "3-tiersalmonspinachandavocadoterrine",
  14.             "key" : "3-tier salmon, spinach and avocado terrine",
  15.             "value" : [
  16.                 null,
  17.                 "3-tier salmon, spinach and avocado terrine"
  18.             ]
  19.         },
  20.         {
  21.             "id" : "Aberffrawcake",
  22.             "key" : "Aberffraw cake",
  23.             "value" : [
  24.                 null,
  25.                 "Aberffraw cake"
  26.             ]
  27.         },
  28.         {
  29.             "id" : "Adukiandorangecasserole-microwave",
  30.             "key" : "Aduki and orange casserole - microwave",
  31.             "value" : [
  32.                 null,
  33.                 "Aduki and orange casserole - microwave"
  34.             ]
  35.         },
  36.         {
  37.             "id" : "Aioli-garlicmayonnaise",
  38.             "key" : "Aioli - garlic mayonnaise",
  39.             "value" : [
  40.                 null,
  41.                 "Aioli - garlic mayonnaise"
  42.             ]
  43.         },
  44.         {
  45.             "id" : "Alabamapeanutchicken",
  46.             "key" : "Alabama peanut chicken",
  47.             "value" : [
  48.                 null,
  49.                 "Alabama peanut chicken"
  50.             ]
  51.         }
  52.     ],
  53.     "total_rows" : 2667
  54. }

To omit some records you may use skip query parameter:

Request:

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

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 21 Aug 2013 09:14:13 GMT
  5. ETag: "H3G7YZSNIVRRHO5FXPE16NJHN"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  9. {
  10.     "offset" : 2,
  11.     "rows" : [
  12.         {
  13.             "id" : "Adukiandorangecasserole-microwave",
  14.             "key" : "Aduki and orange casserole - microwave",
  15.             "value" : [
  16.                 null,
  17.                 "Aduki and orange casserole - microwave"
  18.             ]
  19.         },
  20.         {
  21.             "id" : "Aioli-garlicmayonnaise",
  22.             "key" : "Aioli - garlic mayonnaise",
  23.             "value" : [
  24.                 null,
  25.                 "Aioli - garlic mayonnaise"
  26.             ]
  27.         },
  28.         {
  29.             "id" : "Alabamapeanutchicken",
  30.             "key" : "Alabama peanut chicken",
  31.             "value" : [
  32.                 null,
  33.                 "Alabama peanut chicken"
  34.             ]
  35.         }
  36.     ],
  37.     "total_rows" : 2667
  38. }

Warning

Using limit and skip parameters is not recommended for results pagination. Read pagination recipe why it’s so and how to make it better.

1.5.4.5. Sending multiple queries to a view

New in version 2.2.

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

Executes multiple specified view queries against the view function from the specified design document.

  • Parameters

    • db – Database name

    • ddoc – Design document name

    • view – View function name

    Request Headers

    Request JSON Object

    • queries – An array of query objects with fields for the parameters of each individual view query to be executed. The field names and their meaning are the same as the query parameters of a regular view request.

    Response Headers

    Response JSON Object

    • results (array) – An array of result objects - one for each query. Each result object contains the same fields as the response to a regular view request.

    Status Codes

Request:

  1. POST /recipes/_design/recipes/_view/by_title/queries HTTP/1.1
  2. Content-Type: application/json
  3. Accept: application/json
  4. Host: localhost:5984
  6. {
  7.     "queries": [
  8.         {
  9.             "keys": [
  10.                 "meatballs",
  11.                 "spaghetti"
  12.             ]
  13.         },
  14.         {
  15.             "limit": 3,
  16.             "skip": 2
  17.         }
  18.     ]
  19. }

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 20 Dec 2016 11:17:07 GMT
  5. ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  9. {
  10.     "results" : [
  11.         {
  12.             "offset": 0,
  13.             "rows": [
  14.                 {
  15.                     "id": "SpaghettiWithMeatballs",
  16.                     "key": "meatballs",
  17.                     "value": 1
  18.                 },
  19.                 {
  20.                     "id": "SpaghettiWithMeatballs",
  21.                     "key": "spaghetti",
  22.                     "value": 1
  23.                 },
  24.                 {
  25.                     "id": "SpaghettiWithMeatballs",
  26.                     "key": "tomato sauce",
  27.                     "value": 1
  28.                 }
  29.             ],
  30.             "total_rows": 3
  31.         },
  32.         {
  33.             "offset" : 2,
  34.             "rows" : [
  35.                 {
  36.                     "id" : "Adukiandorangecasserole-microwave",
  37.                     "key" : "Aduki and orange casserole - microwave",
  38.                     "value" : [
  39.                         null,
  40.                         "Aduki and orange casserole - microwave"
  41.                     ]
  42.                 },
  43.                 {
  44.                     "id" : "Aioli-garlicmayonnaise",
  45.                     "key" : "Aioli - garlic mayonnaise",
  46.                     "value" : [
  47.                         null,
  48.                         "Aioli - garlic mayonnaise"
  49.                     ]
  50.                 },
  51.                 {
  52.                     "id" : "Alabamapeanutchicken",
  53.                     "key" : "Alabama peanut chicken",
  54.                     "value" : [
  55.                         null,
  56.                         "Alabama peanut chicken"
  57.                     ]
  58.                 }
  59.             ],
  60.             "total_rows" : 2667
  61.         }
  62.     ]
  63. }