couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kxe...@apache.org
Subject [32/50] git commit: updated refs/heads/1781-reorganize-and-improve-docs to 360107b
Date Wed, 21 Aug 2013 16:37:59 GMT
Update Compaction API reference.


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/edacbca2
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/edacbca2
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/edacbca2

Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: edacbca23e142a714ee7472831a3d51132d24caf
Parents: 4fba147
Author: Alexander Shorin <kxepal@apache.org>
Authored: Mon Aug 12 14:32:01 2013 +0400
Committer: Alexander Shorin <kxepal@apache.org>
Committed: Wed Aug 21 20:29:40 2013 +0400

----------------------------------------------------------------------
 share/doc/src/api/database/compact.rst | 256 +++++++++++++++++-----------
 1 file changed, 157 insertions(+), 99 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/edacbca2/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 40a1f62..51e9c3f 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -12,157 +12,215 @@
 
 
 .. _api/db/compact:
-.. _api/db/compact.post:
 
-``POST /db/_compact``
-=====================
+``/db/_compact``
+================
 
-* **Method**: ``POST /db/_compact``
-* **Request**: None
-* **Response**: JSON success statement
-* **Admin Privileges Required**: yes
-* **Return Codes**:
+.. http:post:: /{db}/_compact
 
-  * **202**:
-    Compaction request has been accepted
+  Request compaction of the specified database. Compaction compresses the
+  disk database file by performing the following operations:
 
-  * **404**:
-    The requested content could not be found. The returned content will include
-    further information, as a JSON object, if available.
+  -  Writes a new version of the database file, removing any unused
+     sections from the new version during write. Because a new file is
+     temporary created for this purpose, you will need twice the current
+     storage space of the specified database in order for the compaction
+     routine to complete.
 
-Request compaction of the specified database. Compaction compresses the
-disk database file by performing the following operations:
+  -  Removes old revisions of documents from the database, up to the
+     per-database limit specified by the ``_revs_limit`` database
+     parameter.
 
--  Writes a new version of the database file, removing any unused
-   sections from the new version during write. Because a new file is
-   temporary created for this purpose, you will need twice the current
-   storage space of the specified database in order for the compaction
-   routine to complete.
+  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.
 
--  Removes old revisions of documents from the database, up to the
-   per-database limit specified by the ``_revs_limit`` database
-   parameter.
+  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
+  :http:get:`/{db}`.
 
-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 also obtain a list of running processes to determine whether
+  compaction is currently running. See :ref:`api/server/active_tasks`.
 
-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
-:http:get:`/{db}`.
+  :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: Administrator`s privileges required
+  :code 415: Bad :http:header:`Content-Type` value
 
-You can also obtain a list of running processes to determine whether
-compaction is currently running. See :ref:`api/server/active_tasks`.
+  **Request**:
 
-.. _api/db/compact/ddoc:
-.. _api/db/compact/ddoc.post:
+  .. code-block:: http
 
-``POST /db/_compact/design-doc``
-================================
+    POST /db/_compact HTTP/1.1
+    Accept: application/json
+    Content-Type: application/json
+    Host: localhost:5984
 
-* **Method**: ``POST /db/_compact/design-doc``
-* **Request**: None
-* **Response**: JSON success statement
-* **Admin Privileges Required**: yes
-* **Return Codes**:
+  **Response**:
 
-  * **202**:
-    Compaction request has been accepted
+  .. code-block:: http
 
-  * **404**:
-    The requested content could not be found. The returned content will include
-    further information, as a JSON object, if available.
+    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/1.4.0 (Erlang OTP/R16B)
 
-Compacts the view indexes associated with the specified design document.
-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.
+    {
+        "ok": true
+    }
 
-For example, to compact the views associated with the ``recipes`` design
-document:
 
-.. code-block:: http
+.. _api/db/compact/ddoc:
 
-    POST http://couchdb:5984/recipes/_compact/recipes
-    Content-Type: application/json
+``/db/_compact/design-doc``
+===========================
 
-CouchDB will immediately return with a status indicating that the
-compaction request has been received (HTTP status code 202):
+.. http:post:: /{db}/_compact/{ddoc}
 
-.. code-block:: javascript
+  Compacts the view indexes associated with the specified design document.
+  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.
 
-    {
-       "ok" : true
-    }
+  :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: Administrator`s privileges required
+  :code 404: Design document not found
+  :code 415: Bad :http: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**:
 
-.. _api/db/ensure_full_commit:
-.. _api/db/ensure_full_commit.post:
+  .. 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/1.4.0 (Erlang OTP/R16B)
 
-``POST /db/_ensure_full_commit``
-================================
+    {
+        "ok": true
+    }
 
-* **Method**: ``POST /db/_ensure_full_commit``
-* **Request**: None
-* **Response**: JSON success statement
-* **Admin Privileges Required**: no
-* **Return Codes**:
 
-  * **202**:
-    Commit completed successfully
+.. _api/db/ensure_full_commit:
 
-  * **404**:
-    The requested content could not be found. The returned content will include
-    further information, as a JSON object, if available.
+``/db/_ensure_full_commit``
+===========================
 
+.. http:post:: /{db}/_ensure_full_commit
 
-Commits any recent changes to the specified database to disk. You should
-call this if you want to ensure that recent changes have been written.
-For example, to commit all the changes to disk for the database
-``recipes`` you would use:
+  Commits any recent changes to the specified database to disk. You should
+  call this if you want to ensure that recent changes have been written.
 
-.. code-block:: http
+  :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 :http:header:`Content-Type` value
 
-    POST http://couchdb:5984/recipes/_ensure_full_commit
+  **Request**:
+
+  .. code-block:: http
+
+    POST /db/_ensure_full_commit HTTP/1.1
+    Accept: application/json
     Content-Type: application/json
+    Host: localhost:5984
 
-This returns a status message, containing the success message and the
-timestamp for when the CouchDB instance was started:
+  **Response**:
 
-.. code-block:: javascript
+  .. 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/1.4.0 (Erlang OTP/R16B)
 
     {
-      "ok" : true,
-      "instance_start_time" : "1288186189373361"
+        "instance_start_time": "1376269047459338",
+        "ok": true
     }
 
 
 .. _api/db/view_cleanup:
-.. _api/db/view_cleanup.post:
 
-``POST /db/_view_cleanup``
-==========================
+``/db/_view_cleanup``
+=====================
+
+.. http:post:: /{db}/_view_cleanup
 
-* **Method**: ``POST /db/_view_cleanup``
-* **Request**: None
-* **Response**: JSON success statement
-* **Admin Privileges Required**: yes
+  Cleans up the cached view output on disk for a given view.
 
-Cleans up the cached view output on disk for a given view. For example:
+  :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: Administrator`s privileges required
+  :code 415: Bad :http:header:`Content-Type` value
 
-.. code-block:: http
+  **Request**:
 
-    POST http://couchdb:5984/recipes/_view_cleanup
+  .. code-block:: http
+
+    POST /db/_view_cleanup HTTP/1.1
+    Accept: application/json
     Content-Type: application/json
+    Host: localhost:5984
+
+  **Response**:
 
-If the request is successful, a basic status message us returned:
+  .. code-block:: http
 
-.. code-block:: javascript
+    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/1.4.0 (Erlang OTP/R16B)
 
     {
-       "ok" : true
+        "ok": true
     }


Mime
View raw message