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:54 UTC
[21/26] documentation commit: updated refs/heads/master to 5a81ace
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/src/api/database/changes.rst b/src/api/database/changes.rst
index c892626..70c0d6b 100644
--- a/src/api/database/changes.rst
+++ b/src/api/database/changes.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/db/changes:
================
@@ -18,147 +17,147 @@
================
.. http:get:: /{db}/_changes
- :synopsis: Returns changes for the given database
-
- Returns a sorted list of changes made to documents in the database, in time
- order of application, can be obtained from the database's ``_changes``
- resource. Only the most recent change for a given document is guaranteed to
- be provided, for example if a document has had fields added, and then deleted,
- an API client checking for changes will not necessarily receive the
- intermediate state of added documents.
-
- This can be used to listen for update and modifications to the database for
- post processing or synchronization, and for practical purposes, a continuously
- connected ``_changes`` feed is a reasonable approach for generating a
- real-time log for most applications.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/event-stream`
- - :mimetype:`text/plain`
- :<header Last-Event-ID: ID of the last events received by the server on a
- previous connection. Overrides `since` query parameter.
- :query array doc_ids: List of document IDs to filter the changes feed as
- valid JSON array. Used with :ref:`_doc_ids <changes/filter/doc_ids>` filter.
- Since `length of URL is limited`_, it is better to use
- :post:`/{db}/_changes` instead.
- :query boolean conflicts: Includes `conflicts` information in response.
- Ignored if `include_docs` isn't ``true``. Default is ``false``.
- :query boolean descending: Return the change results in descending sequence
- order (most recent change first). Default is ``false``.
- :query string feed: see :ref:`changes`. Default is ``normal``.
- :query string filter: Reference to a :ref:`filter function <filterfun>`
- from a design document that will filter whole stream emitting only filtered
- events. See the section `Change Notifications in the book
- CouchDB The Definitive Guide`_ for more information.
- :query number heartbeat: Period in *milliseconds* after which an empty line is
- sent in the results. Only applicable for :ref:`longpoll <changes/longpoll>`
- or :ref:`continuous <changes/continuous>` feeds. Overrides any timeout to
- keep the feed alive indefinitely. Default is ``60000``. May be ``true`` to
- use default value.
- :query boolean include_docs: Include the associated document with each result.
- If there are conflicts, only the winning revision is returned.
- 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 number last-event-id: Alias of `Last-Event-ID` header.
- :query number limit: Limit number of result rows to the specified value
- (note that using ``0`` here has the same effect as ``1``).
- :query since: Start the results from the change immediately after the given
- sequence number. Can be integer number or ``now`` value. Default is ``0``.
- :query string style: Specifies how many revisions are returned in the changes
- array. The default, ``main_only``, will only return the current "winning"
- revision; ``all_docs`` will return all leaf revisions (including conflicts
- and deleted former conflicts).
- :query number timeout: Maximum period in *milliseconds* to wait for a change
- before the response is sent, even if there are no results. Only applicable
- for :ref:`longpoll <changes/longpoll>` or :ref:`continuous
- <changes/continuous>` feeds. Default value is specified by
- :config:option:`httpd/changes_timeout` configuration option.
- Note that ``60000`` value is also the default maximum timeout to prevent
- undetected dead connections.
- :query string view: Allows to use view functions as filters. Documents
- counted as "passed" for view filter in case if map function emits at least
- one record for them. See :ref:`changes/filter/view` for more info.
- :>header Cache-Control: ``no-cache`` if changes feed is
- :ref:`eventsource <changes/eventsource>`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/event-stream`
- - :mimetype:`text/plain; charset=utf-8`
- :>header ETag: Response hash is changes feed is `normal`
- :>header Transfer-Encoding: ``chunked``
- :>json number last_seq: Last change sequence number
- :>json array results: Changes made to a database
- :code 200: Request completed successfully
- :code 400: Bad request
-
- The ``result`` field of database changes
-
- :json array changes: List of document`s leafs with single field ``rev``
- :json string id: Document ID
- :json number seq: Update sequence number
-
- **Request**:
-
- .. code-block:: http
-
- GET /db/_changes?style=all_docs 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: Mon, 12 Aug 2013 00:54:58 GMT
- ETag: "6ASLEKEMSRABT0O5XY9UPO9Z"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
-
- {
- "last_seq": 11,
- "results": [
- {
- "changes": [
- {
- "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
- }
- ],
- "id": "6478c2ae800dfc387396d14e1fc39626",
- "seq": 6
- },
- {
- "changes": [
- {
- "rev": "3-7379b9e515b161226c6559d90c4dc49f"
- }
- ],
- "deleted": true,
- "id": "5bbc9ca465f1b0fcd62362168a7c8831",
- "seq": 9
- },
- {
- "changes": [
- {
- "rev": "6-460637e73a6288cb24d532bf91f32969"
- },
- {
- "rev": "5-eeaa298781f60b7bcae0c91bdedd1b87"
- }
- ],
- "id": "729eb57437745e506b333068fff665ae",
- "seq": 11
- }
- ]
- }
+ :synopsis: Returns changes for the given database
+
+ Returns a sorted list of changes made to documents in the database, in time
+ order of application, can be obtained from the database's ``_changes``
+ resource. Only the most recent change for a given document is guaranteed to
+ be provided, for example if a document has had fields added, and then deleted,
+ an API client checking for changes will not necessarily receive the
+ intermediate state of added documents.
+
+ This can be used to listen for update and modifications to the database for
+ post processing or synchronization, and for practical purposes, a continuously
+ connected ``_changes`` feed is a reasonable approach for generating a
+ real-time log for most applications.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/event-stream`
+ - :mimetype:`text/plain`
+ :<header Last-Event-ID: ID of the last events received by the server on a
+ previous connection. Overrides `since` query parameter.
+ :query array doc_ids: List of document IDs to filter the changes feed as
+ valid JSON array. Used with :ref:`_doc_ids <changes/filter/doc_ids>` filter.
+ Since `length of URL is limited`_, it is better to use
+ :post:`/{db}/_changes` instead.
+ :query boolean conflicts: Includes `conflicts` information in response.
+ Ignored if `include_docs` isn't ``true``. Default is ``false``.
+ :query boolean descending: Return the change results in descending sequence
+ order (most recent change first). Default is ``false``.
+ :query string feed: see :ref:`changes`. Default is ``normal``.
+ :query string filter: Reference to a :ref:`filter function <filterfun>`
+ from a design document that will filter whole stream emitting only filtered
+ events. See the section `Change Notifications in the book
+ CouchDB The Definitive Guide`_ for more information.
+ :query number heartbeat: Period in *milliseconds* after which an empty line is
+ sent in the results. Only applicable for :ref:`longpoll <changes/longpoll>`
+ or :ref:`continuous <changes/continuous>` feeds. Overrides any timeout to
+ keep the feed alive indefinitely. Default is ``60000``. May be ``true`` to
+ use default value.
+ :query boolean include_docs: Include the associated document with each result.
+ If there are conflicts, only the winning revision is returned.
+ 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 number last-event-id: Alias of `Last-Event-ID` header.
+ :query number limit: Limit number of result rows to the specified value
+ (note that using ``0`` here has the same effect as ``1``).
+ :query since: Start the results from the change immediately after the given
+ sequence number. Can be integer number or ``now`` value. Default is ``0``.
+ :query string style: Specifies how many revisions are returned in the changes
+ array. The default, ``main_only``, will only return the current "winning"
+ revision; ``all_docs`` will return all leaf revisions (including conflicts
+ and deleted former conflicts).
+ :query number timeout: Maximum period in *milliseconds* to wait for a change
+ before the response is sent, even if there are no results. Only applicable
+ for :ref:`longpoll <changes/longpoll>` or :ref:`continuous
+ <changes/continuous>` feeds. Default value is specified by
+ :config:option:`httpd/changes_timeout` configuration option.
+ Note that ``60000`` value is also the default maximum timeout to prevent
+ undetected dead connections.
+ :query string view: Allows to use view functions as filters. Documents
+ counted as "passed" for view filter in case if map function emits at least
+ one record for them. See :ref:`changes/filter/view` for more info.
+ :>header Cache-Control: ``no-cache`` if changes feed is
+ :ref:`eventsource <changes/eventsource>`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/event-stream`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Response hash is changes feed is `normal`
+ :>header Transfer-Encoding: ``chunked``
+ :>json number last_seq: Last change sequence number
+ :>json array results: Changes made to a database
+ :code 200: Request completed successfully
+ :code 400: Bad request
+
+ The ``result`` field of database changes
+
+ :json array changes: List of document`s leafs with single field ``rev``
+ :json string id: Document ID
+ :json number seq: Update sequence number
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /db/_changes?style=all_docs 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: Mon, 12 Aug 2013 00:54:58 GMT
+ ETag: "6ASLEKEMSRABT0O5XY9UPO9Z"
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 11,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+ }
+ ],
+ "id": "6478c2ae800dfc387396d14e1fc39626",
+ "seq": 6
+ },
+ {
+ "changes": [
+ {
+ "rev": "3-7379b9e515b161226c6559d90c4dc49f"
+ }
+ ],
+ "deleted": true,
+ "id": "5bbc9ca465f1b0fcd62362168a7c8831",
+ "seq": 9
+ },
+ {
+ "changes": [
+ {
+ "rev": "6-460637e73a6288cb24d532bf91f32969"
+ },
+ {
+ "rev": "5-eeaa298781f60b7bcae0c91bdedd1b87"
+ }
+ ],
+ "id": "729eb57437745e506b333068fff665ae",
+ "seq": 11
+ }
+ ]
+ }
.. _length of URL is limited: http://stackoverflow.com/a/417184/965635
@@ -173,63 +172,61 @@
parameters
.. warning::
- Using the ``attachments`` parameter to include attachments in the changes
- feed 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 the changes
+ feed 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}/_changes
- :synopsis: Returns changes for the given database for certain document IDs
-
- Requests the database changes feed in the same way as
- :get:`/{db}/_changes` does, but is widely used with
- ``?filter=_doc_ids`` query parameter and allows one to pass a larger list of
- document IDs to filter.
-
- **Request**:
-
- .. code-block:: http
-
- POST /recipes/_changes?filter=_doc_ids HTTP/1.1
- Accept: application/json
- Content-Length: 40
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "doc_ids": [
- "SpaghettiWithMeatballs"
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Sat, 28 Sep 2013 07:23:09 GMT
- ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
- Server: CouchDB (Erlang OTP)
- Transfer-Encoding: chunked
-
- {
- "last_seq": 38,
- "results": [
- {
- "changes": [
- {
- "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
- }
- ],
- "id": "SpaghettiWithMeatballs",
- "seq": 38
- }
- ]
- }
-
+ :synopsis: Returns changes for the given database for certain document IDs
+
+ Requests the database changes feed in the same way as
+ :get:`/{db}/_changes` does, but is widely used with
+ ``?filter=_doc_ids`` query parameter and allows one to pass a larger list of
+ document IDs to filter.
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /recipes/_changes?filter=_doc_ids HTTP/1.1
+ Accept: application/json
+ Content-Length: 40
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "doc_ids": [
+ "SpaghettiWithMeatballs"
+ ]
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:23:09 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
+ }
+ ],
+ "id": "SpaghettiWithMeatballs",
+ "seq": 38
+ }
+ ]
+ }
.. _changes:
@@ -269,7 +266,6 @@ including the given sequence number::
GET /somedatabase/_changes?since=3 HTTP/1.1
-
The return structure for ``normal`` and ``longpoll`` modes is a JSON
array of changes objects, and the last update sequence number.
@@ -320,7 +316,6 @@ timeout before the connection is automatically closed (the
the ``heartbeat`` query argument), which sends a newline to keep the
connection active.
-
.. _changes/continuous:
Continuous
@@ -379,44 +374,43 @@ parameter.
// define the event handling function
if (window.EventSource) {
- var source = new EventSource("/somedatabase/_changes?feed=eventsource");
- source.onerror = function(e) {
- alert('EventSource failed.');
- };
+ var source = new EventSource("/somedatabase/_changes?feed=eventsource");
+ source.onerror = function(e) {
+ alert('EventSource failed.');
+ };
- var results = [];
- var sourceListener = function(e) {
- var data = JSON.parse(e.data);
- results.push(data);
- };
+ var results = [];
+ var sourceListener = function(e) {
+ var data = JSON.parse(e.data);
+ results.push(data);
+ };
- // start listening for events
- source.addEventListener('message', sourceListener, false);
+ // start listening for events
+ source.addEventListener('message', sourceListener, false);
- // stop listening for events
- source.removeEventListener('message', sourceListener, false);
+ // stop listening for events
+ source.removeEventListener('message', sourceListener, false);
}
-If you set a heartbeat interval (using the ``heartbeat`` query argument), CouchDB will
-send a ``hearbeat`` event that you can subscribe to with:
+If you set a heartbeat interval (using the ``heartbeat`` query argument),
+CouchDB will send a ``hearbeat`` event that you can subscribe to with:
.. code-block:: javascript
source.addEventListener('heartbeat', function () {}, false);
-This can be monitored by the client application to restart the EventSource connection if
-needed (i.e. if the TCP connection gets stuck in a half-open state).
+This can be monitored by the client application to restart the EventSource
+connection if needed (i.e. if the TCP connection gets stuck in a half-open
+state).
.. note::
-
- EventSource connections are subject to cross-origin resource sharing
- restrictions. You might need to configure :ref:`CORS support
- <cors>` to get the EventSource to work in your application.
+ EventSource connections are subject to cross-origin resource sharing
+ restrictions. You might need to configure :ref:`CORS support
+ <cors>` to get the EventSource to work in your application.
.. _W3C eventsource specification: http://www.w3.org/TR/eventsource/
-
.. _changes/filter:
Filtering
@@ -441,7 +435,6 @@ to the ``filter`` parameter, specifying the design document name and
Additionally, there are couple of builtin filters are available and described
below.
-
.. _changes/filter/doc_ids:
_doc_ids
@@ -451,7 +444,6 @@ This filter accepts only changes for documents which ID in specified in
``doc_ids`` query parameter or payload's object array. See
:post:`/{db}/_changes` for an example.
-
.. _changes/filter/design:
_design
@@ -464,57 +456,56 @@ requested database.
.. code-block:: http
- GET /recipes/_changes?filter=_design HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/_changes?filter=_design 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: Sat, 28 Sep 2013 07:28:28 GMT
- ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
- Server: CouchDB (Erlang OTP)
- Transfer-Encoding: chunked
-
- {
- "last_seq": 38,
- "results": [
- {
- "changes": [
- {
- "rev": "10-304cae84fd862832ea9814f02920d4b2"
- }
- ],
- "id": "_design/ingredients",
- "seq": 29
- },
- {
- "changes": [
- {
- "rev": "123-6f7c1b7c97a9e4f0d22bdf130e8fd817"
- }
- ],
- "deleted": true,
- "id": "_design/cookbook",
- "seq": 35
- },
- {
- "changes": [
- {
- "rev": "6-5b8a52c22580e922e792047cff3618f3"
- }
- ],
- "deleted": true,
- "id": "_design/meta",
- "seq": 36
- }
- ]
- }
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:28:28 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "10-304cae84fd862832ea9814f02920d4b2"
+ }
+ ],
+ "id": "_design/ingredients",
+ "seq": 29
+ },
+ {
+ "changes": [
+ {
+ "rev": "123-6f7c1b7c97a9e4f0d22bdf130e8fd817"
+ }
+ ],
+ "deleted": true,
+ "id": "_design/cookbook",
+ "seq": 35
+ },
+ {
+ "changes": [
+ {
+ "rev": "6-5b8a52c22580e922e792047cff3618f3"
+ }
+ ],
+ "deleted": true,
+ "id": "_design/meta",
+ "seq": 36
+ }
+ ]
+ }
.. _changes/filter/view:
@@ -523,62 +514,61 @@ _view
.. versionadded:: 1.2
-The special filter ``_view`` allows to use existing :ref:`map function <mapfun>`
-as the :ref:`filter <filterfun>`. If the map function emits anything for the
-processed document it counts as accepted and the changes event emits to the
-feed. For most use-practice cases `filter` functions are very similar to `map`
-ones, so this feature helps to reduce amount of duplicated code.
+The special filter ``_view`` allows to use existing
+:ref:`map function <mapfun>` as the :ref:`filter <filterfun>`. If the map
+function emits anything for the processed document it counts as accepted and
+the changes event emits to the feed. For most use-practice cases `filter`
+functions are very similar to `map` ones, so this feature helps to reduce
+amount of duplicated code.
.. warning::
-
- While :ref:`map functions <mapfun>` doesn't process the design documents,
- using ``_view`` filter forces them to do this. You need to be sure, that
- they are ready to handle documents with *alien* structure without panic
- crush.
+ While :ref:`map functions <mapfun>` doesn't process the design documents,
+ using ``_view`` filter forces them to do this. You need to be sure, that
+ they are ready to handle documents with *alien* structure without panic
+ crush.
.. note::
+ Using ``_view`` filter doesn't queries the view index files, so you cannot
+ use common :ref:`view query parameters <api/ddoc/view>` to additionally
+ filter the changes feed by index key. Also, CouchDB doesn't returns
+ the result instantly as it does for views - it really uses the specified
+ map function as filter.
- Using ``_view`` filter doesn't queries the view index files, so you cannot
- use common :ref:`view query parameters <api/ddoc/view>` to additionally
- filter the changes feed by index key. Also, CouchDB doesn't returns
- the result instantly as it does for views - it really uses the specified
- map function as filter.
-
- Moreover, you cannot make such filters dynamic e.g. process the request
- query parameters or handle the :ref:`userctx_object` - the map function is
- only operates with the document.
+ Moreover, you cannot make such filters dynamic e.g. process the request
+ query parameters or handle the :ref:`userctx_object` - the map function is
+ only operates with the document.
**Request**:
.. code-block:: http
- GET /recipes/_changes?filter=_view&view=ingredients/by_recipe HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/_changes?filter=_view&view=ingredients/by_recipe 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: Sat, 28 Sep 2013 07:36:40 GMT
- ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
- Server: CouchDB (Erlang OTP)
- Transfer-Encoding: chunked
-
- {
- "last_seq": 38,
- "results": [
- {
- "changes": [
- {
- "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
- }
- ],
- "id": "SpaghettiWithMeatballs",
- "seq": 38
- }
- ]
- }
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:36:40 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
+ }
+ ],
+ "id": "SpaghettiWithMeatballs",
+ "seq": 38
+ }
+ ]
+ }
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/src/api/database/common.rst b/src/api/database/common.rst
index a1483d9..56876a5 100644
--- a/src/api/database/common.rst
+++ b/src/api/database/common.rst
@@ -12,375 +12,373 @@
.. _api/db:
+=======
``/db``
=======
.. http:head:: /{db}
- :synopsis: Checks the database existence
+ :synopsis: Checks the database existence
- Returns the HTTP Headers containing a minimal amount of information
- about the specified database. Since the response body is empty, using the
- HEAD method is a lightweight way to check if the database exists already or
- not.
+ Returns the HTTP Headers containing a minimal amount of information
+ about the specified database. Since the response body is empty, using the
+ HEAD method is a lightweight way to check if the database exists already or
+ not.
- :param db: Database name
- :code 200: Database exists
- :code 404: Requested database not found
+ :param db: Database name
+ :code 200: Database exists
+ :code 404: Requested database not found
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- HEAD /test HTTP/1.1
- Host: localhost:5984
+ HEAD /test HTTP/1.1
+ Host: localhost:5984
- **Response**:
+ **Response**:
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 01:27:41 GMT
- Server: CouchDB (Erlang/OTP)
+ .. code-block:: http
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 01:27:41 GMT
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}
- :synopsis: Returns the database information
-
- Gets information about the specified database.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json number committed_update_seq: The number of committed update.
- :>json boolean compact_running: Set to ``true`` if the database compaction
- routine is operating on this database.
- :>json string db_name: The name of the database.
- :>json number disk_format_version: The version of the physical format used
- for the data when it is stored on disk.
- :>json number data_size: Actual data size in bytes of the database data.
- :>json number disk_size: Size in bytes of the data as stored on the disk.
- Views indexes are not included in the calculation.
- :>json number doc_count: A count of the documents in the specified database.
- :>json number doc_del_count: Number of deleted documents
- :>json string instance_start_time: Timestamp of when the database was opened,
- expressed in microseconds since the epoch.
- :>json number purge_seq: The number of purge operations on the database.
- :>json number update_seq: The current number of updates to the database.
- :code 200: Request completed successfully
- :code 404: Requested database not found
-
- **Request**:
-
- .. code-block:: http
-
- GET /receipts HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 258
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 01:38:57 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "committed_update_seq": 292786,
- "compact_running": false,
- "data_size": 65031503,
- "db_name": "receipts",
- "disk_format_version": 6,
- "disk_size": 137433211,
- "doc_count": 6146,
- "doc_del_count": 64637,
- "instance_start_time": "1376269325408900",
- "purge_seq": 0,
- "update_seq": 292786
- }
-
+ :synopsis: Returns the database information
+
+ Gets information about the specified database.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json number committed_update_seq: The number of committed update.
+ :>json boolean compact_running: Set to ``true`` if the database compaction
+ routine is operating on this database.
+ :>json string db_name: The name of the database.
+ :>json number disk_format_version: The version of the physical format used
+ for the data when it is stored on disk.
+ :>json number data_size: Actual data size in bytes of the database data.
+ :>json number disk_size: Size in bytes of the data as stored on the disk.
+ Views indexes are not included in the calculation.
+ :>json number doc_count: A count of the documents in the specified
+ database.
+ :>json number doc_del_count: Number of deleted documents
+ :>json string instance_start_time: Timestamp of when the database was
+ opened, expressed in microseconds since the epoch.
+ :>json number purge_seq: The number of purge operations on the database.
+ :>json number update_seq: The current number of updates to the database.
+ :code 200: Request completed successfully
+ :code 404: Requested database not found
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /receipts HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 258
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 01:38:57 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "committed_update_seq": 292786,
+ "compact_running": false,
+ "data_size": 65031503,
+ "db_name": "receipts",
+ "disk_format_version": 6,
+ "disk_size": 137433211,
+ "doc_count": 6146,
+ "doc_del_count": 64637,
+ "instance_start_time": "1376269325408900",
+ "purge_seq": 0,
+ "update_seq": 292786
+ }
.. http:put:: /{db}
- :synopsis: Creates a new database
+ :synopsis: Creates a new database
- Creates a new database. The database name ``{db}`` must be composed by
- following next rules:
+ Creates a new database. The database name ``{db}`` must be composed by
+ following next rules:
- - Name must begin with a lowercase letter (``a-z``)
+ - Name must begin with a lowercase letter (``a-z``)
- - Lowercase characters (``a-z``)
+ - Lowercase characters (``a-z``)
- - Digits (``0-9``)
+ - Digits (``0-9``)
- - Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and
- ``/``.
+ - Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and
+ ``/``.
- If you're familiar with `Regular Expressions`_, the rules above could be
- written as ``^[a-z][a-z0-9_$()+/-]*$``.
+ If you're familiar with `Regular Expressions`_, the rules above could be
+ written as ``^[a-z][a-z0-9_$()+/-]*$``.
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header Location: Database URI location
- :>json boolean ok: Operation status. Available in case of success
- :>json string error: Error type. Available if response code is ``4xx``
- :>json string reason: Error description. Available if response code is ``4xx``
- :code 201: Database created successfully
- :code 400: Invalid database name
- :code 401: CouchDB Server Administrator privileges required
- :code 412: Database already exists
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header Location: Database URI location
+ :>json boolean ok: Operation status. Available in case of success
+ :>json string error: Error type. Available if response code is ``4xx``
+ :>json string reason: Error description. Available if response code is
+ ``4xx``
+ :code 201: Database created successfully
+ :code 400: Invalid database name
+ :code 401: CouchDB Server Administrator privileges required
+ :code 412: Database already exists
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- PUT /db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ PUT /db HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 08:01:45 GMT
- Location: http://localhost:5984/db
- Server: CouchDB (Erlang/OTP)
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 08:01:45 GMT
+ Location: http://localhost:5984/db
+ Server: CouchDB (Erlang/OTP)
- {
- "ok": true
- }
+ {
+ "ok": true
+ }
- If we repeat the same request to CouchDB, it will response with :code:`412`
- since the database already exists:
+ If we repeat the same request to CouchDB, it will response with :code:`412`
+ since the database already exists:
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- PUT /db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ PUT /db HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 412 Precondition Failed
- Cache-Control: must-revalidate
- Content-Length: 95
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 08:01:16 GMT
- Server: CouchDB (Erlang/OTP)
+ HTTP/1.1 412 Precondition Failed
+ Cache-Control: must-revalidate
+ Content-Length: 95
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 08:01:16 GMT
+ Server: CouchDB (Erlang/OTP)
- {
- "error": "file_exists",
- "reason": "The database could not be created, the file already exists."
- }
+ {
+ "error": "file_exists",
+ "reason": "The database could not be created, the file already exists."
+ }
- If an invalid database name is supplied, CouchDB returns response with :code:`400`:
+ If an invalid database name is supplied, CouchDB returns response with
+ :code:`400`:
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- PUT /_db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ PUT /_db HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 400 Bad Request
- Cache-Control: must-revalidate
- Content-Length: 194
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 08:02:10 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "error": "illegal_database_name",
- "reason": "Name: '_db'. Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
- }
+ HTTP/1.1 400 Bad Request
+ Cache-Control: must-revalidate
+ Content-Length: 194
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 08:02:10 GMT
+ Server: CouchDB (Erlang/OTP)
+ {
+ "error": "illegal_database_name",
+ "reason": "Name: '_db'. Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
+ }
.. http:delete:: /{db}
- :synopsis: Deletes an existing database
+ :synopsis: Deletes an existing database
- Deletes the specified database, and all the documents and attachments
- contained within it.
+ Deletes the specified database, and all the documents and attachments
+ contained within it.
- .. note::
+ .. note::
+ To avoid deleting a database, CouchDB will respond with the HTTP status
+ code 400 when the request URL includes a ?rev= parameter. This suggests
+ that one wants to delete a document but forgot to add the document id
+ to the URL.
- To avoid deleting a database, CouchDB will respond with the HTTP status code 400
- when the request URL includes a ?rev= parameter. This suggests that one wants to delete
- a document but forgot to add the document id to the URL.
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json boolean ok: Operation status
+ :code 200: Database removed successfully
+ :code 400: Invalid database name or forgotten document id by accident
+ :code 401: CouchDB Server Administrator privileges required
+ :code 404: Database doesn't exist
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json boolean ok: Operation status
- :code 200: Database removed successfully
- :code 400: Invalid database name or forgotten document id by accident
- :code 401: CouchDB Server Administrator privileges required
- :code 404: Database doesn't exist
+ **Request**:
- **Request**:
+ .. code-block:: http
- .. code-block:: http
+ DELETE /db HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- DELETE /db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ **Response**:
- **Response**:
+ .. code-block:: http
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 08:54:00 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "ok": true
- }
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 08:54:00 GMT
+ Server: CouchDB (Erlang/OTP)
+ {
+ "ok": true
+ }
.. http:post:: /{db}
- :synopsis: Creates a new document with generated ID if _id is not specified
-
- Creates a new document in the specified database, using the supplied JSON
- document structure.
-
- If the JSON structure includes the ``_id`` field, then the document will be
- created with the specified document ID.
-
- If the ``_id`` field is not specified, a new unique ID will be generated,
- following whatever UUID algorithm is configured for that server.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<header X-Couch-Full-Commit: Overrides server's
- :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
- are: ``false`` and ``true``. *Optional*.
- :query string batch: Stores document 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: Quoted new document's revision
- :>header Location: Document's URI
- :>json string id: Document ID
- :>json boolean ok: Operation status
- :>json string rev: Revision info
- :code 201: Document created and stored on disk
- :code 202: Document data accepted, but not yet stored on disk
- :code 400: Invalid database name
- :code 401: Write privileges required
- :code 404: Database doesn't exist
- :code 409: A Conflicting Document with same ID already exists
-
- **Request**:
-
- .. code-block:: http
-
- POST /db HTTP/1.1
- Accept: application/json
- Content-Length: 81
- Content-Type: application/json
-
- {
- "servings": 4,
- "subtitle": "Delicious with fresh bread",
- "title": "Fish Stew"
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 95
- Content-Type: application/json
- Date: Tue, 13 Aug 2013 15:19:25 GMT
- ETag: "1-9c65296036141e575d32ba9c034dd3ee"
- Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d
- Server: CouchDB (Erlang/OTP)
-
- {
- "id": "ab39fe0993049b84cfa81acd6ebad09d",
- "ok": true,
- "rev": "1-9c65296036141e575d32ba9c034dd3ee"
- }
-
+ :synopsis: Creates a new document with generated ID if _id is not specified
+
+ Creates a new document in the specified database, using the supplied JSON
+ document structure.
+
+ If the JSON structure includes the ``_id`` field, then the document will be
+ created with the specified document ID.
+
+ If the ``_id`` field is not specified, a new unique ID will be generated,
+ following whatever UUID algorithm is configured for that server.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<header X-Couch-Full-Commit: Overrides server's
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*.
+ :query string batch: Stores document 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: Quoted new document's revision
+ :>header Location: Document's URI
+ :>json string id: Document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision info
+ :code 201: Document created and stored on disk
+ :code 202: Document data accepted, but not yet stored on disk
+ :code 400: Invalid database name
+ :code 401: Write privileges required
+ :code 404: Database doesn't exist
+ :code 409: A Conflicting Document with same ID already exists
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db HTTP/1.1
+ Accept: application/json
+ Content-Length: 81
+ Content-Type: application/json
+
+ {
+ "servings": 4,
+ "subtitle": "Delicious with fresh bread",
+ "title": "Fish Stew"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 95
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 15:19:25 GMT
+ ETag: "1-9c65296036141e575d32ba9c034dd3ee"
+ Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "id": "ab39fe0993049b84cfa81acd6ebad09d",
+ "ok": true,
+ "rev": "1-9c65296036141e575d32ba9c034dd3ee"
+ }
Specifying the Document ID
---------------------------
+==========================
The document ID can be specified by including the ``_id`` field in the
JSON of the submitted record. The following request will create the same
document with the ID ``FishStew``.
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- POST /db HTTP/1.1
- Accept: application/json
- Content-Length: 98
- Content-Type: application/json
+ POST /db HTTP/1.1
+ Accept: application/json
+ Content-Length: 98
+ Content-Type: application/json
- {
- "_id": "FishStew",
- "servings": 4,
- "subtitle": "Delicious with fresh bread",
- "title": "Fish Stew"
- }
+ {
+ "_id": "FishStew",
+ "servings": 4,
+ "subtitle": "Delicious with fresh bread",
+ "title": "Fish Stew"
+ }
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 71
- Content-Type: application/json
- Date: Tue, 13 Aug 2013 15:19:25 GMT
- ETag: "1-9c65296036141e575d32ba9c034dd3ee"
- Location: http://localhost:5984/db/FishStew
- Server: CouchDB (Erlang/OTP)
-
- {
- "id": "FishStew",
- "ok": true,
- "rev": "1-9c65296036141e575d32ba9c034dd3ee"
- }
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 71
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 15:19:25 GMT
+ ETag: "1-9c65296036141e575d32ba9c034dd3ee"
+ Location: http://localhost:5984/db/FishStew
+ Server: CouchDB (Erlang/OTP)
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "1-9c65296036141e575d32ba9c034dd3ee"
+ }
.. _api/doc/batch-writes:
Batch Mode Writes
------------------
+=================
You can write documents to the database at a higher rate by using the
batch option. This collects document writes together in memory (on a
@@ -393,44 +391,43 @@ URL of the ``PUT`` or :post:`/{db}` request. The CouchDB server will
respond with a HTTP :statuscode:`202` response code immediately.
.. note::
-
- Creating or updating documents with batch mode doesn't guarantee that all
- documents will be successfully stored on disk. For example, individual
- documents may not be saved due to conflicts, rejection by
- :ref:`validation function <vdufun>` or by other reasons, even if overall
- the batch was sucessfully submitted.
+ Creating or updating documents with batch mode doesn't guarantee that all
+ documents will be successfully stored on disk. For example, individual
+ documents may not be saved due to conflicts, rejection by
+ :ref:`validation function <vdufun>` or by other reasons, even if overall
+ the batch was sucessfully submitted.
**Request**:
.. code-block:: http
- POST /db?batch=ok HTTP/1.1
- Accept: application/json
- Content-Length: 98
- Content-Type: application/json
+ POST /db?batch=ok HTTP/1.1
+ Accept: application/json
+ Content-Length: 98
+ Content-Type: application/json
- {
- "_id": "FishStew",
- "servings": 4,
- "subtitle": "Delicious with fresh bread",
- "title": "Fish Stew"
- }
+ {
+ "_id": "FishStew",
+ "servings": 4,
+ "subtitle": "Delicious with fresh bread",
+ "title": "Fish Stew"
+ }
**Response**:
.. code-block:: http
- HTTP/1.1 202 Accepted
- Cache-Control: must-revalidate
- Content-Length: 28
- Content-Type: application/json
- Date: Tue, 13 Aug 2013 15:19:25 GMT
- Location: http://localhost:5984/db/FishStew
- Server: CouchDB (Erlang/OTP)
-
- {
- "id": "FishStew",
- "ok": true
- }
+ HTTP/1.1 202 Accepted
+ Cache-Control: must-revalidate
+ Content-Length: 28
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 15:19:25 GMT
+ Location: http://localhost:5984/db/FishStew
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "id": "FishStew",
+ "ok": true
+ }
.. _Regular Expressions: http://en.wikipedia.org/wiki/Regular_expression
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/src/api/database/compact.rst b/src/api/database/compact.rst
index 706eedf..483e9dd 100644
--- a/src/api/database/compact.rst
+++ b/src/api/database/compact.rst
@@ -10,234 +10,234 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/db/compact:
+================
``/db/_compact``
================
.. http:post:: /{db}/_compact
- :synopsis: Starts a compaction for the database
+ :synopsis: Starts a compaction for the database
- Request compaction of the specified database. Compaction compresses the
- disk database file by performing the following operations:
+ Request compaction of the specified database. Compaction compresses the
+ disk database file by performing the following operations:
- - Writes a new, optimised, version of the database file, removing any unused
- sections from the new version during write. Because a new file is
- temporarily created for this purpose, you may require up to twice the current
- storage space of the specified database in order for the compaction
- routine to complete.
+ - Writes a new, optimised, version of the database file, removing any
+ unused sections from the new version during write. Because a new file is
+ temporarily created for this purpose, you may require up to twice the
+ current storage space of the specified database in order for the
+ compaction routine to complete.
- - Removes old revisions of documents from the database, up to the
- per-database limit specified by the ``_revs_limit`` database
- parameter.
+ - Removes old revisions of documents from the database, up to the
+ per-database limit specified by the ``_revs_limit`` database
+ parameter.
- Compaction can only be requested on an individual database; you cannot
- compact all the databases for a CouchDB instance. The compaction process
- runs as a background process.
+ Compaction can only be requested on an individual database; you cannot
+ compact all the databases for a CouchDB instance. The compaction process
+ runs as a background process.
- You can determine if the compaction process is operating on a database
- by obtaining the database meta information, the ``compact_running``
- value of the returned database structure will be set to true. See
- :get:`/{db}`.
+ You can determine if the compaction process is operating on a database
+ by obtaining the database meta information, the ``compact_running``
+ value of the returned database structure will be set to true. See
+ :get:`/{db}`.
- You can also obtain a list of running processes to determine whether
- compaction is currently running. See :ref:`api/server/active_tasks`.
+ You can also obtain a list of running processes to determine whether
+ compaction is currently running. See :ref:`api/server/active_tasks`.
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json boolean ok: Operation status
- :code 202: Compaction request has been accepted
- :code 400: Invalid database name
- :code 401: CouchDB Server Administrator privileges required
- :code 415: Bad :header:`Content-Type` value
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json boolean ok: Operation status
+ :code 202: Compaction request has been accepted
+ :code 400: Invalid database name
+ :code 401: CouchDB Server Administrator privileges required
+ :code 415: Bad :header:`Content-Type` value
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- POST /db/_compact HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Host: localhost:5984
+ POST /db/_compact HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Host: localhost:5984
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 202 Accepted
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 09:27:43 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "ok": true
- }
+ HTTP/1.1 202 Accepted
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 09:27:43 GMT
+ Server: CouchDB (Erlang/OTP)
+ {
+ "ok": true
+ }
.. _api/db/compact/ddoc:
+===========================
``/db/_compact/design-doc``
===========================
.. http:post:: /{db}/_compact/{ddoc}
- :synopsis: Starts a compaction for all the views in the selected design document
-
- Compacts the view indexes associated with the specified design document.
- If may be that compacting a large view can return more storage than
- compacting the actual db. Thus, you can use this in place of the full
- database compaction if you know a specific set of view indexes have been
- affected by a recent database change.
-
- :param db: Database name
- :param ddoc: Design document name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json boolean ok: Operation status
- :code 202: Compaction request has been accepted
- :code 400: Invalid database name
- :code 401: CouchDB Server Administrator privileges required
- :code 404: Design document not found
- :code 415: Bad :header:`Content-Type` value
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_compact/posts HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 202 Accepted
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 09:36:44 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "ok": true
- }
+ :synopsis: Starts a compaction for all the views in the selected design document
+
+ Compacts the view indexes associated with the specified design document.
+ If may be that compacting a large view can return more storage than
+ compacting the actual db. Thus, you can use this in place of the full
+ database compaction if you know a specific set of view indexes have been
+ affected by a recent database change.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json boolean ok: Operation status
+ :code 202: Compaction request has been accepted
+ :code 400: Invalid database name
+ :code 401: CouchDB Server Administrator privileges required
+ :code 404: Design document not found
+ :code 415: Bad :header:`Content-Type` value
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_compact/posts HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 202 Accepted
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 09:36:44 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "ok": true
+ }
.. note::
-
- View indexes are stored in a separate ``.couch`` file based on
- a hash of the design document's relevant functions, in a sub directory
- of where the main ``.couch`` database files are located.
+ View indexes are stored in a separate ``.couch`` file based on a hash
+ of the design document's relevant functions, in a sub directory of
+ where the main ``.couch`` database files are located.
.. _api/db/ensure_full_commit:
+===========================
``/db/_ensure_full_commit``
===========================
.. http:post:: /{db}/_ensure_full_commit
- :synopsis: Makes sure all uncommitted changes are written and synchronized to the disk
-
- Commits any recent changes to the specified database to disk. You should
- call this if you want to ensure that recent changes have been flushed.
- This function is likely not required, assuming you have the recommended
- configuration setting of ``delayed_commits=false``, which requires CouchDB
- to ensure changes are written to disk before a 200 or similar result is
- returned.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json string instance_start_time: Timestamp of when the database was opened,
- expressed in microseconds since the epoch.
- :>json boolean ok: Operation status
- :code 201: Commit completed successfully
- :code 400: Invalid database name
- :code 415: Bad :header:`Content-Type` value
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_ensure_full_commit HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 53
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 10:22:19 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "instance_start_time": "1376269047459338",
- "ok": true
- }
-
+ :synopsis: Makes sure all uncommitted changes are written and synchronized to the disk
+
+ Commits any recent changes to the specified database to disk. You should
+ call this if you want to ensure that recent changes have been flushed.
+ This function is likely not required, assuming you have the recommended
+ configuration setting of ``delayed_commits=false``, which requires CouchDB
+ to ensure changes are written to disk before a 200 or similar result is
+ returned.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json string instance_start_time: Timestamp of when the database was opened,
+ expressed in microseconds since the epoch.
+ :>json boolean ok: Operation status
+ :code 201: Commit completed successfully
+ :code 400: Invalid database name
+ :code 415: Bad :header:`Content-Type` value
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_ensure_full_commit HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 53
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 10:22:19 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "instance_start_time": "1376269047459338",
+ "ok": true
+ }
.. _api/db/view_cleanup:
+=====================
``/db/_view_cleanup``
=====================
.. http:post:: /{db}/_view_cleanup
- :synopsis: Removes view files that are not used by any design document
-
- Removes view index files that are no longer required by CouchDB as a result
- of changed views within design documents. As the view filename is based on
- a hash of the view functions, over time old views will remain, consuming
- storage. This call cleans up the cached view output on disk for a given view.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json boolean ok: Operation status
- :code 202: Compaction request has been accepted
- :code 400: Invalid database name
- :code 401: CouchDB Server Administrator privileges required
- :code 415: Bad :header:`Content-Type` value
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_view_cleanup HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 202 Accepted
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 09:27:43 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "ok": true
- }
+ :synopsis: Removes view files that are not used by any design document
+
+ Removes view index files that are no longer required by CouchDB as a result
+ of changed views within design documents. As the view filename is based on
+ a hash of the view functions, over time old views will remain, consuming
+ storage. This call cleans up the cached view output on disk for a given view.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json boolean ok: Operation status
+ :code 202: Compaction request has been accepted
+ :code 400: Invalid database name
+ :code 401: CouchDB Server Administrator privileges required
+ :code 415: Bad :header:`Content-Type` value
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_view_cleanup HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 202 Accepted
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 09:27:43 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "ok": true
+ }
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/index.rst
----------------------------------------------------------------------
diff --git a/src/api/database/index.rst b/src/api/database/index.rst
index 5da6a32..91d392e 100644
--- a/src/api/database/index.rst
+++ b/src/api/database/index.rst
@@ -37,11 +37,10 @@ For clarity, the form below is used in the URL paths:
Where ``db`` is the name of any database.
.. toctree::
-
- common
- bulk-api
- changes
- compact
- security
- temp-views
- misc
+ common
+ bulk-api
+ changes
+ compact
+ security
+ temp-views
+ misc