You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2015/02/20 01:26:52 UTC
[19/26] documentation commit: updated refs/heads/master to 5a81ace
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/src/api/ddoc/views.rst b/src/api/ddoc/views.rst
index 8a299cc..dfa4eda 100644
--- a/src/api/ddoc/views.rst
+++ b/src/api/ddoc/views.rst
@@ -10,198 +10,197 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/ddoc/view:
+==========================================
``/db/_design/design-doc/_view/view-name``
==========================================
.. http:get:: /{db}/_design/{ddoc}/_view/{view}
- :synopsis: Returns results for the specified stored view
-
- Executes the specified view function from the specified design document.
-
- :param db: Database name
- :param ddoc: Design document name
- :param view: View function name
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
-
- :query boolean conflicts: Includes `conflicts` information in response.
- Ignored if `include_docs` isn't ``true``. Default is ``false``
- :query boolean descending: Return the documents in descending by key order.
- Default is ``false``
- :query json endkey: Stop returning records when the specified key is
- reached. *Optional*
- :query json end_key: Alias for `endkey` param
- :query string endkey_docid: Stop returning records when the specified
- document ID is reached. *Optional*
- :query string end_key_doc_id: Alias for `endkey_docid` param
- :query boolean group: Group the results using the reduce function to a group
- or single row. Default is ``false``
- :query number group_level: Specify the group level to be used. *Optional*
- :query boolean include_docs: Include the associated document with each row.
- Default is ``false``.
- :query boolean attachments: Include the Base64-encoded content of
- :ref:`attachments <api/doc/attachments>` in the documents that are included
- if `include_docs` is ``true``. Ignored if `include_docs` isn't ``true``.
- Default is ``false``.
- :query boolean att_encoding_info: 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``.
- :query boolean inclusive_end: Specifies whether the specified end key should
- be included in the result. Default is ``true``
- :query json key: Return only documents that match the specified key.
- *Optional*
- :query json-array keys: Return only documents where the key matches one of the
- keys specified in the array. *Optional*
- :query number limit: Limit the number of the returned documents to the
- specified number. *Optional*
- :query boolean reduce: Use the reduction function. Default is ``true``
- :query number skip: Skip this number of records before starting to return
- the results. Default is ``0``
- :query string stale: Allow the results from a stale view to be used.
- Supported values: ``ok`` and ``update_after``. *Optional*
- :query json startkey: Return records starting with the specified key.
- *Optional*
- :query json start_key: Alias for `startkey` param
- :query string startkey_docid: Return records starting with the specified
- document ID. *Optional*
- :query string start_key_doc_id: Alias for `startkey_docid` param
- :query boolean update_seq: Response includes an ``update_seq`` value
- indicating which sequence id of the database the view reflects.
- Default is ``false``
-
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header ETag: Response signature
- :>header Transfer-Encoding: ``chunked``
-
- :>json number offset: Offset where the document list started
- :>json array rows: Array of view row objects. By default the information
- returned contains only the document ID and revision
- :>json number total_rows: Number of documents in the database/view
- :>json number update_seq: Current update sequence for the database
-
- :code 200: Request completed successfully
- :code 400: Invalid request
- :code 401: Read permission required
- :code 404: Specified database, design document or view is missed
- :code 500: View function execution error
-
- **Request**:
-
- .. code-block:: http
-
- GET /recipes/_design/ingredients/_view/by_name HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- 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
+ :synopsis: Returns results for the specified stored view
+
+ Executes the specified view function from the specified design document.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :param view: View function name
+
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+
+ :query boolean conflicts: Includes `conflicts` information in response.
+ Ignored if `include_docs` isn't ``true``. Default is ``false``
+ :query boolean descending: Return the documents in descending by key order.
+ Default is ``false``
+ :query json endkey: Stop returning records when the specified key is
+ reached. *Optional*
+ :query json end_key: Alias for `endkey` param
+ :query string endkey_docid: Stop returning records when the specified
+ document ID is reached. *Optional*
+ :query string end_key_doc_id: Alias for `endkey_docid` param
+ :query boolean group: Group the results using the reduce function to a
+ group or single row. Default is ``false``
+ :query number group_level: Specify the group level to be used. *Optional*
+ :query boolean include_docs: Include the associated document with each row.
+ Default is ``false``.
+ :query boolean attachments: Include the Base64-encoded content of
+ :ref:`attachments <api/doc/attachments>` in the documents that are
+ included if `include_docs` is ``true``. Ignored if `include_docs` isn't
+ ``true``. Default is ``false``.
+ :query boolean att_encoding_info: 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``.
+ :query boolean inclusive_end: Specifies whether the specified end key
+ should be included in the result. Default is ``true``
+ :query json key: Return only documents that match the specified key.
+ *Optional*
+ :query json-array keys: Return only documents where the key matches one of
+ the keys specified in the array. *Optional*
+ :query number limit: Limit the number of the returned documents to the
+ specified number. *Optional*
+ :query boolean reduce: Use the reduction function. Default is ``true``
+ :query number skip: Skip this number of records before starting to return
+ the results. Default is ``0``
+ :query string stale: Allow the results from a stale view to be used.
+ Supported values: ``ok`` and ``update_after``. *Optional*
+ :query json startkey: Return records starting with the specified key.
+ *Optional*
+ :query json start_key: Alias for `startkey` param
+ :query string startkey_docid: Return records starting with the specified
+ document ID. *Optional*
+ :query string start_key_doc_id: Alias for `startkey_docid` param
+ :query boolean update_seq: Response includes an ``update_seq`` value
+ indicating which sequence id of the database the view reflects.
+ Default is ``false``
+
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Response signature
+ :>header Transfer-Encoding: ``chunked``
+
+ :>json number offset: Offset where the document list started
+ :>json array rows: Array of view row objects. By default the information
+ returned contains only the document ID and revision
+ :>json number total_rows: Number of documents in the database/view
+ :>json number update_seq: Current update sequence for the database
+
+ :code 200: Request completed successfully
+ :code 400: Invalid request
+ :code 401: Read permission required
+ :code 404: Specified database, design document or view is missed
+ :code 500: View function execution error
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /recipes/_design/ingredients/_view/by_name HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ 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
- }
+ {
+ "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
+ }
.. versionchanged:: 1.6.0 added ``attachments`` and ``att_encoding_info``
- parameters
+ 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.
-
+ 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.
.. http:post:: /{db}/_design/{ddoc}/_view/{view}
- :synopsis: Returns certain rows for the specified stored view
-
- Executes the specified view function from the specified design document.
- Unlike :get:`/{db}/_design/{ddoc}/_view/{view}` for accessing views, the
- :method:`POST` method supports the specification
- of explicit keys to be retrieved from the view results. The remainder of the
- :method:`POST` view functionality is identical to the
- :get:`/{db}/_design/{ddoc}/_view/{view}` API.
+ :synopsis: Returns certain rows for the specified stored view
- **Request**:
+ Executes the specified view function from the specified design document.
+ Unlike :get:`/{db}/_design/{ddoc}/_view/{view}` for accessing views, the
+ :method:`POST` method supports the specification
+ of explicit keys to be retrieved from the view results. The remainder of
+ the :method:`POST` view functionality is identical to the
+ :get:`/{db}/_design/{ddoc}/_view/{view}` API.
- .. code-block:: http
+ **Request**:
- POST /recipes/_design/ingredients/_view/by_name HTTP/1.1
- Accept: application/json
- Content-Length: 37
- Host: localhost:5984
+ .. code-block:: http
- {
- "keys": [
- "meatballs",
- "spaghetti"
- ]
- }
+ POST /recipes/_design/ingredients/_view/by_name HTTP/1.1
+ Accept: application/json
+ Content-Length: 37
+ Host: localhost:5984
- **Response**:
+ {
+ "keys": [
+ "meatballs",
+ "spaghetti"
+ ]
+ }
- .. code-block:: http
+ **Response**:
- 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
+ .. code-block:: http
- {
- "offset": 0,
- "rows": [
- {
- "id": "SpaghettiWithMeatballs",
- "key": "meatballs",
- "value": 1
- },
- {
- "id": "SpaghettiWithMeatballs",
- "key": "spaghetti",
- "value": 1
- }
- ],
- "total_rows": 3
- }
+ 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
+ }
.. _api/ddoc/view/options:
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
@@ -213,80 +212,77 @@ index is generated, not when it's accessed:
- **include_design** (*boolean*): Allows map functions to be called on design
documents as well as regular documents
-In additional to these options, you may specify :ref:`any other <api/ddoc/view>`
-with their default value. E.g. having option ``"include_docs": true`` will
-automatically includes document body for view results response. You still may
-override such by explicitly defining same query parameter name with other value.
+In additional to these options, you may specify
+:ref:`any other <api/ddoc/view>` with their default value. E.g. having option
+``"include_docs": true`` will automatically includes document body for view
+results response. You still may override such by explicitly defining same query
+parameter name with other value.
.. _api/ddoc/view/indexing:
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.
+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.
+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 new document has been added to the database.
+- A document has been deleted from the database.
+- A document in the database has been updated.
-- 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.
+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 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 :ref:`changes feed <api/db/changes>` to monitor for changes to the
- database and then access the view to force the corresponding view
- index to be updated.
-
-- Use a monitor with the :ref:`update notification <update-notifications>`
- section of the CouchDB configuration file to monitor for changes to your
- database, and trigger a view query to force the view 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.
+ 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 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 :ref:`changes feed <api/db/changes>` to monitor for changes to the
+ database and then access the view to force the corresponding view index to be
+ updated.
+
+- Use a monitor with the :ref:`update notification <update-notifications>`
+ section of the CouchDB configuration file to monitor for changes to your
+ database, and trigger a view query to force the view 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:
@@ -297,174 +293,163 @@ For example, to access the existing stale view ``by_recipe`` in the
Accessing a stale view:
-- Does not trigger a rebuild of the view indexes, even if there have
- been changes since the last access.
+- 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 the current version of the view index, if a current version exists.
-- Returns an empty result set if the given view index does exist.
+- Returns an empty result set if the given view index does 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}`).
+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}`).
.. _api/ddoc/view/sorting:
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:
+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**:
.. code-block:: http
- GET /db/_design/test/_view/sorting HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
+ GET /db/_design/test/_view/sorting HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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
- }
+ 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
+ }
You can reverse the order of the returned view information by using the
``descending`` query value set to true:
@@ -473,133 +458,130 @@ You can reverse the order of the returned view information by using the
.. code-block:: http
- GET /db/_design/test/_view/sorting?descending=true HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
+ GET /db/_design/test/_view/sorting?descending=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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
- }
+ 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
+ }
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:
+``startkey`` and ``endkey`` query arguments. For example the following query:
.. code-block:: http
@@ -612,37 +594,34 @@ will operate correctly when listing all the matching entries between
.. code-block:: http
+ GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- 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
- }
+ {
+ "total_rows" : 26453,
+ "rows" : [],
+ "offset" : 21882
+ }
-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.
+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:
+``endkey`` parameters to match the descending sorting applied to the keys.
+Changing the previous example to:
.. code-block:: http
- GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22 HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
+ GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
.. _api/ddoc/view/sorting/raw:
Raw collation
-^^^^^^^^^^^^^
+-------------
By default CouchDB using `ICU`_ driver for sorting view results. It's possible
use binary collation instead for faster view builds where Unicode collation is
@@ -653,15 +632,14 @@ documents ``options`` object at the root level. After that, views will be
regenerated and new order applied.
.. seealso::
-
- :ref:`views/collation`
+ :ref:`views/collation`
.. _ICU: http://site.icu-project.org/
.. _api/ddoc/view/limiting:
Using Limits and Skipping Rows
-------------------------------
+==============================
By default requestion views result returns all records for it. That's ok when
they are small, but this may lead to problems when there are billions of them
@@ -669,75 +647,75 @@ since the clients might 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:
+view and limited to 5 returns only 5 records, while there are total 2667
+records in view:
**Request**:
.. code-block:: http
- GET /recipes/_design/recipes/_view/by_title?limit=5 HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/_design/recipes/_view/by_title?limit=5 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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
- }
+ 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
+ }
To omit some records you may use ``skip`` query parameter:
@@ -745,55 +723,54 @@ To omit some records you may use ``skip`` query parameter:
.. code-block:: http
- GET /recipes/_design/recipes/_view/by_title?limit=3&skip=2 HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/_design/recipes/_view/by_title?limit=3&skip=2 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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
- }
+ 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
-.. warning::
+ {
+ "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
+ }
- Using ``limit`` and ``skip`` parameters is not recommended for results
- pagination. Read :ref:`pagination recipe <views/pagination>` why it's so
- and how to make it better.
+.. warning::
+ Using ``limit`` and ``skip`` parameters is not recommended for results
+ pagination. Read :ref:`pagination recipe <views/pagination>` why it's so
+ and how to make it better.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/src/api/document/attachments.rst b/src/api/document/attachments.rst
index f2403aa..0215083 100644
--- a/src/api/document/attachments.rst
+++ b/src/api/document/attachments.rst
@@ -10,274 +10,276 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/doc/attachment:
+======================
``/db/doc/attachment``
======================
.. http:head:: /{db}/{docid}/{attname}
- :synopsis: Returns bare information in the HTTP Headers for the attachment
-
- Returns the HTTP headers containing a minimal amount of information
- about the specified attachment. The method supports the same query
- arguments as the :get:`/{db}/{docid}/{attname}` method, but only
- the header information (including attachment size, encoding and the MD5 hash
- as an :header:`ETag`), is returned.
-
- :param db: Database name
- :param docid: Document ID
- :param attname: Attachment name
- :<header If-Match: Document's revision. Alternative to `rev` query parameter
- :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
- *Optional*
- :query string rev: Document's revision. *Optional*
- :>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
- Used for attachments with :mimetype:`application/octet-stream` content type
- :>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :config:option:`list of compressiable types
- <attachments/compressible_types>`
- :>header Content-Length: Attachment size. If compression codec was used,
- this value is about compressed size, not actual
- :>header Content-MD5: Base64 encoded MD5 binary digest
- :>header ETag: Double quoted base64 encoded MD5 binary digest
- :code 200: Attachment exists
- :code 304: Attachment wasn't modified if :header:`ETag` equals specified
- :header:`If-None-Match` header
- :code 401: Read privilege required
- :code 404: Specified database, document or attachment was not found
-
- **Request**:
-
- .. code-block:: http
-
- HEAD /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Accept-Ranges: none
- Cache-Control: must-revalidate
- Content-Encoding: gzip
- Content-Length: 100
- Content-MD5: vVa/YgiE1+Gh0WfoFJAcSg==
- Content-Type: text/plain
- Date: Thu, 15 Aug 2013 12:42:42 GMT
- ETag: "vVa/YgiE1+Gh0WfoFJAcSg=="
- Server: CouchDB (Erlang/OTP)
-
+ :synopsis: Returns bare information in the HTTP Headers for the attachment
+
+ Returns the HTTP headers containing a minimal amount of information about
+ the specified attachment. The method supports the same query arguments as
+ the :get:`/{db}/{docid}/{attname}` method, but only the header information
+ (including attachment size, encoding and the MD5 hash as an
+ :header:`ETag`), is returned.
+
+ :param db: Database name
+ :param docid: Document ID
+ :param attname: Attachment name
+ :<header If-Match: Document's revision. Alternative to `rev` query
+ parameter
+ :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
+ *Optional*
+ :query string rev: Document's revision. *Optional*
+ :>header Accept-Ranges: :ref:`Range request aware
+ <api/doc/attachment/range>`. Used for attachments with
+ :mimetype:`application/octet-stream` content type
+ :>header Content-Encoding: Used compression codec. Available if
+ attachment's ``content_type`` is in :config:option:`list of compressiable
+ types <attachments/compressible_types>`
+ :>header Content-Length: Attachment size. If compression codec was used,
+ this value is about compressed size, not actual
+ :>header Content-MD5: Base64 encoded MD5 binary digest
+ :>header ETag: Double quoted base64 encoded MD5 binary digest
+ :code 200: Attachment exists
+ :code 304: Attachment wasn't modified if :header:`ETag` equals specified
+ :header:`If-None-Match` header
+ :code 401: Read privilege required
+ :code 404: Specified database, document or attachment was not found
+
+ **Request**:
+
+ .. code-block:: http
+
+ HEAD /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Accept-Ranges: none
+ Cache-Control: must-revalidate
+ Content-Encoding: gzip
+ Content-Length: 100
+ Content-MD5: vVa/YgiE1+Gh0WfoFJAcSg==
+ Content-Type: text/plain
+ Date: Thu, 15 Aug 2013 12:42:42 GMT
+ ETag: "vVa/YgiE1+Gh0WfoFJAcSg=="
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}/{docid}/{attname}
- :synopsis: Gets the attachment of a document
-
- Returns the file attachment associated with the document.
- The raw data of the associated attachment is returned (just as if you were
- accessing a static file. The returned :header:`Content-Type`
- will be the same as the content type set when the document attachment
- was submitted into the database.
-
- :param db: Database name
- :param docid: Document ID
- :param attname: Attachment name
- :<header If-Match: Document's revision. Alternative to `rev` query parameter
- :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
- *Optional*
- :query string rev: Document's revision. *Optional*
- :>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
- Used for attachments with :mimetype:`application/octet-stream`
- :>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :config:option:`list of compressiable types
- <attachments/compressible_types>`
- :>header Content-Length: Attachment size. If compression codec is used,
- this value is about compressed size, not actual
- :>header Content-MD5: Base64 encoded MD5 binary digest
- :>header ETag: Double quoted base64 encoded MD5 binary digest
- :response: Stored content
- :code 200: Attachment exists
- :code 304: Attachment wasn't modified if :header:`ETag` equals specified
- :header:`If-None-Match` header
- :code 401: Read privilege required
- :code 404: Specified database, document or attachment was not found
-
+ :synopsis: Gets the attachment of a document
+
+ Returns the file attachment associated with the document. The raw data of
+ the associated attachment is returned (just as if you were accessing a
+ static file. The returned :header:`Content-Type` will be the same as the
+ content type set when the document attachment was submitted into the
+ database.
+
+ :param db: Database name
+ :param docid: Document ID
+ :param attname: Attachment name
+ :<header If-Match: Document's revision. Alternative to `rev` query
+ parameter
+ :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
+ *Optional*
+ :query string rev: Document's revision. *Optional*
+ :>header Accept-Ranges: :ref:`Range request aware
+ <api/doc/attachment/range>`. Used for attachments with
+ :mimetype:`application/octet-stream`
+ :>header Content-Encoding: Used compression codec. Available if
+ attachment's ``content_type`` is in :config:option:`list of compressiable
+ types <attachments/compressible_types>`
+ :>header Content-Length: Attachment size. If compression codec is used,
+ this value is about compressed size, not actual
+ :>header Content-MD5: Base64 encoded MD5 binary digest
+ :>header ETag: Double quoted base64 encoded MD5 binary digest
+ :response: Stored content
+ :code 200: Attachment exists
+ :code 304: Attachment wasn't modified if :header:`ETag` equals specified
+ :header:`If-None-Match` header
+ :code 401: Read privilege required
+ :code 404: Specified database, document or attachment was not found
.. http:put:: /{db}/{docid}/{attname}
- :synopsis: Adds an attachment of a document
-
- Uploads the supplied content as an attachment to the specified document.
- The attachment name provided must be a URL encoded string. You must also
- supply either the ``rev`` query argument or the :header:`If-Match`
- HTTP header for validation, and the HTTP headers (to set the attachment
- content type).
-
- If case when uploading an attachment using an existing attachment name,
- CouchDB will update the corresponding stored content of the database.
- Since you must supply the revision information to add an attachment to
- the document, this serves as validation to update the existing attachment.
-
- .. note::
- Uploading an attachment updates the corresponding document revision.
- Revisions are tracked for the parent document, not individual attachments.
-
- :param db: Database name
- :param docid: Document ID
- :param attname: Attachment name
- :<header Content-Type: Attachment MIME type. *Required*
- :<header If-Match: Document revision. Alternative to `rev` query parameter
- :query string rev: Document revision. *Required*
- :>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
- Used for attachments with :mimetype:`application/octet-stream`
- :>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :config:option:`list of compressiable types
- <attachments/compressible_types>`
- :>header Content-Length: Attachment size. If compression codec is used,
- this value is about compressed size, not actual
- :>header Content-MD5: Base64 encoded MD5 binary digest
- :>header ETag: Double quoted base64 encoded MD5 binary digest
- :>json string id: Document ID
- :>json boolean ok: Operation status
- :>json string rev: Revision MVCC token
- :code 200: Attachment successfully removed
- :code 202: Request was accepted, but changes are not yet stored on disk
- :code 400: Invalid request body or parameters
- :code 401: Write privileges required
- :code 404: Specified database, document or attachment was not found
- :code 409: Document's revision wasn't specified or it's not the latest
-
- **Request**:
-
- .. code-block:: http
-
- PUT /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
- Accept: application/json
- Content-Length: 86
- Content-Type: text/plain
- Host: localhost:5984
- If-Match: 1-917fa2381192822767f010b95b45325b
-
- 1. Cook spaghetti
- 2. Cook meatballs
- 3. Mix them
- 4. Add tomato sauce
- 5. ...
- 6. PROFIT!
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 85
- Content-Type: application/json
- Date: Thu, 15 Aug 2013 12:38:04 GMT
- ETag: "2-ce91aed0129be8f9b0f650a2edcfd0a4"
- Location: http://localhost:5984/recipes/SpaghettiWithMeatballs/recipe.txt
- Server: CouchDB (Erlang/OTP)
-
- {
- "id": "SpaghettiWithMeatballs",
- "ok": true,
- "rev": "2-ce91aed0129be8f9b0f650a2edcfd0a4"
- }
-
+ :synopsis: Adds an attachment of a document
+
+ Uploads the supplied content as an attachment to the specified document.
+ The attachment name provided must be a URL encoded string. You must also
+ supply either the ``rev`` query argument or the :header:`If-Match` HTTP
+ header for validation, and the HTTP headers (to set the attachment content
+ type).
+
+ If case when uploading an attachment using an existing attachment name,
+ CouchDB will update the corresponding stored content of the database. Since
+ you must supply the revision information to add an attachment to the
+ document, this serves as validation to update the existing attachment.
+
+ .. note::
+ Uploading an attachment updates the corresponding document revision.
+ Revisions are tracked for the parent document, not individual
+ attachments.
+
+ :param db: Database name
+ :param docid: Document ID
+ :param attname: Attachment name
+ :<header Content-Type: Attachment MIME type. *Required*
+ :<header If-Match: Document revision. Alternative to `rev` query parameter
+ :query string rev: Document revision. *Required*
+ :>header Accept-Ranges: :ref:`Range request aware
+ <api/doc/attachment/range>`. Used for attachments with
+ :mimetype:`application/octet-stream`
+ :>header Content-Encoding: Used compression codec. Available if
+ attachment's ``content_type`` is in :config:option:`list of compressiable
+ types <attachments/compressible_types>`
+ :>header Content-Length: Attachment size. If compression codec is used,
+ this value is about compressed size, not actual
+ :>header Content-MD5: Base64 encoded MD5 binary digest
+ :>header ETag: Double quoted base64 encoded MD5 binary digest
+ :>json string id: Document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 200: Attachment successfully removed
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database, document or attachment was not found
+ :code 409: Document's revision wasn't specified or it's not the latest
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
+ Accept: application/json
+ Content-Length: 86
+ Content-Type: text/plain
+ Host: localhost:5984
+ If-Match: 1-917fa2381192822767f010b95b45325b
+
+ 1. Cook spaghetti
+ 2. Cook meatballs
+ 3. Mix them
+ 4. Add tomato sauce
+ 5. ...
+ 6. PROFIT!
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Thu, 15 Aug 2013 12:38:04 GMT
+ ETag: "2-ce91aed0129be8f9b0f650a2edcfd0a4"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs/recipe.txt
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "2-ce91aed0129be8f9b0f650a2edcfd0a4"
+ }
.. http:delete:: /{db}/{docid}/{attname}
- :synopsis: Deletes an attachment of a document
-
- Deletes the attachment ``attachment`` of the specified ``doc``. You must
- supply the ``rev`` query parameter or :header:`If-Match` with the current
- revision to delete the attachment.
-
- .. note::
- Deleting an attachment updates the corresponding document revision.
- Revisions are tracked for the parent document, not individual attachments.
-
- :param db: Database name
- :param docid: Document ID
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header If-Match: Document revision. Alternative to `rev` query parameter
- :<header X-Couch-Full-Commit: Overrides server's
- :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
- are: ``false`` and ``true``. *Optional*
- :query string rev: Document revision. *Required*
- :query string batch: Store changes in :ref:`batch mode
- <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header ETag: Double quoted document's new revision
- :>json string id: Document ID
- :>json boolean ok: Operation status
- :>json string rev: Revision MVCC token
- :code 200: Attachment successfully removed
- :code 202: Request was accepted, but changes are not yet stored on disk
- :code 400: Invalid request body or parameters
- :code 401: Write privileges required
- :code 404: Specified database, document or attachment was not found
- :code 409: Document's revision wasn't specified or it's not the latest
-
- **Request**:
-
- .. code-block:: http
-
- DELETE /recipes/SpaghettiWithMeatballs?rev=6-440b2dd39c20413045748b42c6aba6e2 HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- Alternatively, instead of ``rev`` query parameter you may use
- :header:`If-Match` header:
-
- .. code-block:: http
-
- DELETE /recipes/SpaghettiWithMeatballs HTTP/1.1
- Accept: application/json
- If-Match: 6-440b2dd39c20413045748b42c6aba6e2
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 85
- Content-Type: application/json
- Date: Wed, 14 Aug 2013 12:23:13 GMT
- ETag: "7-05185cf5fcdf4b6da360af939431d466"
- Server: CouchDB (Erlang/OTP)
-
- {
- "id": "SpaghettiWithMeatballs",
- "ok": true,
- "rev": "7-05185cf5fcdf4b6da360af939431d466"
- }
-
+ :synopsis: Deletes an attachment of a document
+
+ Deletes the attachment ``attachment`` of the specified ``doc``. You must
+ supply the ``rev`` query parameter or :header:`If-Match` with the current
+ revision to delete the attachment.
+
+ .. note::
+ Deleting an attachment updates the corresponding document revision.
+ Revisions are tracked for the parent document, not individual attachments.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header If-Match: Document revision. Alternative to `rev` query parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string rev: Document revision. *Required*
+ :query string batch: Store changes in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's new revision
+ :>json string id: Document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 200: Attachment successfully removed
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database, document or attachment was not found
+ :code 409: Document's revision wasn't specified or it's not the latest
+
+ **Request**:
+
+ .. code-block:: http
+
+ DELETE /recipes/SpaghettiWithMeatballs?rev=6-440b2dd39c20413045748b42c6aba6e2 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ Alternatively, instead of ``rev`` query parameter you may use
+ :header:`If-Match` header:
+
+ .. code-block:: http
+
+ DELETE /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ If-Match: 6-440b2dd39c20413045748b42c6aba6e2
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:23:13 GMT
+ ETag: "7-05185cf5fcdf4b6da360af939431d466"
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "7-05185cf5fcdf4b6da360af939431d466"
+ }
.. _api/doc/attachment/range:
HTTP Range Requests
--------------------
+===================
HTTP allows you to specify byte ranges for requests. This allows the
-implementation of resumable downloads and skippable audio and video
-streams alike. This is available for all attachments inside CouchDB.
+implementation of resumable downloads and skippable audio and video streams
+alike. This is available for all attachments inside CouchDB.
-This is just a real quick run through how this looks under the hood.
-Usually, you will have larger binary files to serve from CouchDB, like
-MP3s and videos, but to make things a little more obvious, I use a text
-file here (Note that I use the :mimetype:`application/octet-stream`
-:header`Content-Type` instead of :mimetype:`text/plain`).
+This is just a real quick run through how this looks under the hood. Usually,
+you will have larger binary files to serve from CouchDB, like MP3s and videos,
+but to make things a little more obvious, I use a text file here (Note that I
+use the :mimetype:`application/octet-stream` :header`Content-Type` instead of
+:mimetype:`text/plain`).
.. code-block:: bash
shell> cat file.txt
My hovercraft is full of eels!
-Now let's store this text file as an attachment in CouchDB. First, we
-create a database:
+Now let's store this text file as an attachment in CouchDB. First, we create a
+database:
.. code-block:: bash
@@ -311,8 +313,8 @@ HTTP supports many ways to specify single and even multiple byte
ranges. Read all about it in :rfc:`2616#section-14.27`.
.. note::
- Databases that have been created with CouchDB 1.0.2 or earlier will
- support range requests in |version|, but they are using a less-optimal
- algorithm. If you plan to make heavy use of this feature, make sure
- to compact your database with CouchDB |version| to take advantage of a
- better algorithm to find byte ranges.
+ Databases that have been created with CouchDB 1.0.2 or earlier will support
+ range requests in |version|, but they are using a less-optimal algorithm.
+ If you plan to make heavy use of this feature, make sure to compact your
+ database with CouchDB |version| to take advantage of a better algorithm to
+ find byte ranges.