You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ns...@apache.org on 2012/09/29 18:11:19 UTC
[13/19] moving things around and preparing base automake setup
http://git-wip-us.apache.org/repos/asf/couchdb/blob/0357f044/share/docs/rst/api/design.rst
----------------------------------------------------------------------
diff --git a/share/docs/rst/api/design.rst b/share/docs/rst/api/design.rst
deleted file mode 100644
index e1dd212..0000000
--- a/share/docs/rst/api/design.rst
+++ /dev/null
@@ -1,1252 +0,0 @@
-.. _api-design:
-
-=======================
-Design Document Methods
-=======================
-
-In CouchDB, design documents provide the main interface for building a
-CouchDB application. The design document defines the views used to
-extract information from CouchDB through one or more views. Design
-documents are created within your CouchDB instance in the same way as
-you create database documents, but the content and definition of the
-documents is different. Design Documents are named using an ID defined
-with the design document URL path, and this URL can then be used to
-access the database contents.
-
-Views and lists operate together to provide automated (and formatted)
-output from your database.
-
-A list of the available methods and URL paths are provided below:
-
-Design Document API Calls
-
-``GET /db/_design/design-doc``
-==============================
-
-* **Method**: ``GET /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of the existing design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: revs
-
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**:
-
- * **true**: Includes the revisions
-
- * **Argument**: revs_info
-
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**:
-
- * **true**: Includes the revisions
-
-Returns the specified design document, ``design-doc`` from the specified
-``db``. For example, to retrieve the design document ``recipes`` you
-would send the following request:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/_design/recipes
- Content-Type: application/json
-
-The returned string will be the JSON of the design document:
-
-.. code-block:: javascript
-
- {
- "_id" : "_design/recipes",
- "_rev" : "5-39f56a392b86bbee57e2138921346406"
- "language" : "javascript",
- "views" : {
- "by_recipe" : {
- "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
- },
- },
- }
-
-A list of the revisions can be obtained by using the ``revs`` query
-argument, or an extended list of revisions using the ``revs_info`` query
-argument. This operates in the same way as for other documents. Fur
-further examples, see :ref:`api-get-doc`.
-
-``PUT /db/_design/design-doc``
-==============================
-
-* **Method**: ``PUT /db/_design/design-doc``
-* **Request**: JSON of the design document
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-
-Upload the specified design document, ``design-doc``, to the specified
-database. The design document should follow the definition of a design
-document, as summarised in the following table.
-
-* **_id**: Design Document ID
-* **_rev**: Design Document Revision
-* **views**: View
-
- * **viewname**: View Definition
-
- * **map**: Map Function for View
- * **reduce (optional)**: Reduce Function for View
-
-For more information on writing views, see :ref:`views`.
-
-``DELETE /db/_design/design-doc``
-=================================
-
-* **Method**: ``DELETE /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of deleted design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **409**:
- Supplied revision is incorrect or missing
-
-Delete an existing design document. Deleting a design document also
-deletes all of the associated view indexes, and recovers the
-corresponding space on disk for the indexes in question.
-
-To delete, you must specify the current revision of the design document
-using the ``rev`` query argument.
-
-For example:
-
-.. code-block:: http
-
- DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
- Content-Type: application/json
-
-The response contains the delete document ID and revision:
-
-.. code-block:: javascript
-
- {
- "id" : "recipe/_design/recipes"
- "ok" : true,
- "rev" : "3-7a05370bff53186cb5d403f861aca154",
- }
-
-``COPY /db/_design/design-doc``
-===============================
-
-* **Method**: ``COPY /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of the new document and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Revision to copy from
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Destination``
-
- * **Description**: Destination document (and optional revision)
- * **Optional**: no
-
-The ``COPY`` command (non-standard HTTP) copies an existing design
-document to a new or existing document.
-
-The source design document is specified on the request line, with the
-``Destination`` HTTP Header of the request specifying the target
-document.
-
-Copying a Design Document
--------------------------
-
-To copy the latest version of a design document to a new document you
-specify the base document and target document:
-
-.. code-block:: http
-
- COPY http://couchdb:5984/recipes/_design/recipes
- Content-Type: application/json
- Destination: /recipes/_design/recipelist
-
-The above request copies the design document ``recipes`` to the new
-design document ``recipelist``. The response is the ID and revision of
-the new document.
-
-.. code-block:: javascript
-
- {
- "id" : "recipes/_design/recipelist"
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
- }
-
-.. note::
- Copying a design document does automatically reconstruct the view
- indexes. These will be recreated, as with other views, the first
- time the new view is accessed.
-
-Copying from a Specific Revision
---------------------------------
-
-To copy *from* a specific version, use the ``rev`` argument to the query
-string:
-
-.. code-block:: http
-
- COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5
- Content-Type: application/json
- Destination: recipes/_design/recipelist
-
-The new design document will be created using the specified revision of
-the source document.
-
-Copying to an Existing Design Document
---------------------------------------
-
-To copy to an existing document, you must specify the current revision
-string for the target document, using the ``rev`` parameter to the
-``Destination`` HTTP Header string. For example:
-
-.. code-block:: http
-
- COPY http://couchdb:5984/recipes/_design/recipes
- Content-Type: application/json
- Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee
-
-The return value will be the new revision of the copied document:
-
-.. code-block:: javascript
-
- {
- "id" : "recipes/_design/recipes"
- "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
- }
-
-``GET /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``GET /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: Returns the attachment data
-* **Admin Privileges Required**: no
-
-Returns the file attachment ``attachment`` associated with the design
-document ``/_design_/design-doc``. The raw data of the associated
-attachment is returned (just as if you were accessing a static file. The
-returned HTTP ``Content-type`` will be the same as the content type set
-when the document attachment was submitted into the database.
-
-``PUT /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``PUT /db/_design/design-doc/attachment``
-* **Request**: Raw document data
-* **Response**: JSON document status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Content-Length``
-
- * **Description**: Length (bytes) of the attachment being uploaded
- * **Optional**: no
-
- * **Header**: ``Content-Type``
-
- * **Description**: MIME type for the uploaded attachment
- * **Optional**: no
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-Upload the supplied content as an attachment to the specified design
-document (``/_design/design-doc``). The ``attachment`` name provided
-must be a URL encoded string. You must also supply either the ``rev``
-query argument or the ``If-Match`` HTTP header for validation, and the
-HTTP headers (to set the attacment content type). The content type is
-used when the attachment is requested as the corresponding content-type
-in the returned document header.
-
-For example, you could upload a simple text document using the following
-request:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e
- Content-Length: 39
- Content-Type: text/plain
-
- div.recipetitle {
- font-weight: bold;
- }
-
-Or by using the ``If-Match`` HTTP header:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew/basic
- If-Match: 7-f7114d4d81124b223283f3e89eee043e
- Content-Length: 39
- Content-Type: text/plain
-
- div.recipetitle {
- font-weight: bold;
- }
-
-The returned JSON contains the new document information:
-
-.. code-block:: javascript
-
- {
- "id" : "_design/recipes"
- "ok" : true,
- "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5",
- }
-
-.. note::
- Uploading an attachment updates the corresponding document revision.
- Revisions are tracked for the parent document, not individual attachments.
-
-``DELETE /db/_design/design-doc/attachment``
-============================================
-
-* **Method**: ``DELETE /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **200**:
- Attachment deleted successfully
- * **409**:
- Supplied revision is incorrect or missing
-
-Deletes the attachment ``attachment`` to the specified
-``_design/design-doc``. You must supply the ``rev`` argument with the
-current revision to delete the attachment.
-
-For example to delete the attachment ``view.css`` from the design
-document ``recipes``:
-
-.. code-block:: http
-
- DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a
-
-The returned JSON contains the updated revision information for the
-parent document:
-
-.. code-block:: javascript
-
- {
- "id" : "_design/recipes"
- "ok" : true,
- "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
- }
-
-``GET /db/_design/design-doc/_info``
-====================================
-
-* **Method**: ``GET /db/_design/design-doc/_info``
-* **Request**: None
-* **Response**: JSON of the design document information
-* **Admin Privileges Required**: no
-
-Obtains information about a given design document, including the index,
-index size and current status of the design document and associated
-index information.
-
-For example, to get the information for the ``recipes`` design document:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/_design/recipes/_info
- Content-Type: application/json
-
-This returns the following JSON structure:
-
-.. code-block:: javascript
-
- {
- "name" : "recipes"
- "view_index" : {
- "compact_running" : false,
- "updater_running" : false,
- "language" : "javascript",
- "purge_seq" : 10,
- "waiting_commit" : false,
- "waiting_clients" : 0,
- "signature" : "fc65594ee76087a3b8c726caf5b40687",
- "update_seq" : 375031,
- "disk_size" : 16491
- },
- }
-
-The individual fields in the returned JSON structure are detailed below:
-
-* **name**: Name/ID of Design Document
-* **view_index**: View Index
-
- * **compact_running**: Indicates whether a compaction routine is currently
- running on the view
- * **disk_size**: Size in bytes of the view as stored on disk
- * **language**: Language for the defined views
- * **purge_seq**: The purge sequence that has been processed
- * **signature**: MD5 signature of the views for the design document
- * **update_seq**: The update sequence of the corresponding database that
- has been indexed
- * **updater_running**: Indicates if the view is currently being updated
- * **waiting_clients**: Number of clients waiting on views from this design
- document
- * **waiting_commit**: Indicates if there are outstanding commits to the
- underlying database that need to processed
-
-.. _api-get-view:
-
-.. _views:
-
-``GET /db/_design/design-doc/_view/view-name``
-==============================================
-
-* **Method**: ``GET /db/_design/design-doc/_view/view-name``
-* **Request**: None
-* **Response**: JSON of the documents returned by the view
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: descending
-
- * **Description**: Return the documents in descending by key order
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: endkey
-
- * **Description**: Stop returning records when the specified key is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: endkey_docid
-
- * **Description**: Stop returning records when the specified document
- ID is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: group
-
- * **Description**: Group the results using the reduce function to a
- group or single row
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: group_level
-
- * **Description**: Specify the group level to be used
- * **Optional**: yes
- * **Type**: numeric
-
- * **Argument**: include_docs
-
- * **Description**: Include the full content of the documents in the return
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: inclusive_end
-
- * **Description**: Specifies whether the specified end key should be
- included in the result
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
-
- * **Argument**: key
-
- * **Description**: Return only documents that match the specified key
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: limit
-
- * **Description**: Limit the number of the returned documents to the
- specified number
- * **Optional**: yes
- * **Type**: numeric
-
- * **Argument**: reduce
-
- * **Description**: Use the reduction function
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
-
- * **Argument**: skip
-
- * **Description**: Skip this number of records before starting to return
- the results
- * **Optional**: yes
- * **Type**: numeric
- * **Default**: 0
-
- * **Argument**: stale
-
- * **Description**: Allow the results from a stale view to be used
- * **Optional**: yes
- * **Type**: string
- * **Default**:
- * **Supported Values**
-
- * **ok**: Allow stale views
-
- * **Argument**: startkey
-
- * **Description**: Return records starting with the specified key
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: startkey_docid
-
- * **Description**: Return records starting with the specified document ID
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: update_seq
-
- * **Description**: Include the update sequence in the generated results
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
-Executes the specified ``view-name`` from the specified ``design-doc``
-design document.
-
-Querying Views and Indexes
---------------------------
-
-The definition of a view within a design document also creates an index
-based on the key information defined within each view. The production
-and use of the index significantly increases the speed of access and
-searching or selecting documents from the view.
-
-However, the index is not updated when new documents are added or
-modified in the database. Instead, the index is generated or updated,
-either when the view is first accessed, or when the view is accessed
-after a document has been updated. In each case, the index is updated
-before the view query is executed against the database.
-
-View indexes are updated incrementally in the following situations:
-
-- A new document has been added to the database.
-
-- A document has been deleted from the database.
-
-- A document in the database has been updated.
-
-View indexes are rebuilt entirely when the view definition changes. To
-achieve this, a 'fingerprint' of the view definition is created when the
-design document is updated. If the fingerprint changes, then the view
-indexes are entirely rebuilt. This ensures that changes to the view
-definitions are reflected in the view indexes.
-
-.. note::
- View index rebuilds occur when one view from the same the view group
- (i.e. all the views defined within a single a design document) has
- been determined as needing a rebuild. For example, if 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 ``/db/_changes`` method to monitor for changes to the
- database and then access the view to force the corresponding view
- index to be updated. See :ref:`api-changes` for more information.
-
-- Use a monitor with the ``update_notification`` 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. For more
- information, see :ref:`update-notifications`.
-
-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:
-
-.. code-block:: text
-
- http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok
-
-Accessing a stale view:
-
-- Does not trigger a rebuild of the view indexes, even if there have
- been changes since the last access.
-
-- Returns the current version of the view index, if a current version
- exists.
-
-- Returns an empty result set if the given view index does 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 :ref:`api-get-db`).
-
-Sorting Returned Rows
----------------------
-
-Each element within the returned array is sorted using native UTF-8
-sorting according to the contents of the key portion of the emitted
-content. The basic order of output is as follows:
-
-- ``null``
-
-- ``false``
-
-- ``true``
-
-- Numbers
-
-- Text (case sensitive, lowercase first)
-
-- Arrays (according to the values of each element, in order)
-
-- Objects (according to the values of keys, in key order)
-
-You can reverse the order of the returned view information by using the
-``descending`` query value set to true. For example, Retrieving the list
-of recipes using the ``by_title`` (limited to 5 records) view:
-
-.. code-block:: javascript
-
- {
- "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
- }
-
-Requesting the same in descending order will reverse the entire view
-content. For example the request
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true
- Accept: application/json
- Content-Type: application/json
-
-Returns the last 5 records from the view:
-
-.. code-block:: javascript
-
- {
- "offset" : 0,
- "rows" : [
- {
- "id" : "Zucchiniinagrodolcesweet-sourcourgettes",
- "key" : "Zucchini in agrodolce (sweet-sour courgettes)",
- "value" : [
- null,
- "Zucchini in agrodolce (sweet-sour courgettes)"
- ]
- },
- {
- "id" : "Zingylemontart",
- "key" : "Zingy lemon tart",
- "value" : [
- null,
- "Zingy lemon tart"
- ]
- },
- {
- "id" : "Zestyseafoodavocado",
- "key" : "Zesty seafood avocado",
- "value" : [
- null,
- "Zesty seafood avocado"
- ]
- },
- {
- "id" : "Zabaglione",
- "key" : "Zabaglione",
- "value" : [
- null,
- "Zabaglione"
- ]
- },
- {
- "id" : "Yogurtraita",
- "key" : "Yogurt raita",
- "value" : [
- null,
- "Yogurt raita"
- ]
- }
- ],
- "total_rows" : 2667
- }
-
-The sorting direction is applied before the filtering applied using the
-``startkey`` and ``endkey`` query arguments. For example the following
-query:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22
- Accept: application/json
- Content-Type: application/json
-
-Will operate correctly when listing all the matching entries between
-“carrots” and ``egg``. If the order of output is reversed with the
-``descending`` query argument, the view request will return no entries:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22
- Accept: application/json
- Content-Type: application/json
-
-The returned result is empty:
-
-.. code-block:: javascript
-
- {
- "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.
-
-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:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22
- Accept: application/json
- Content-Type: application/json
-
-Specifying Start and End Values
--------------------------------
-
-.. todo:: Specifying Start and End Values
-
-The ``startkey`` and ``endkey`` query arguments can be used to specify
-the range of values to be displayed when querying the view.
-
-Using Limits and Skipping Rows
-------------------------------
-
-.. todo:: Using Limits and Skipping Rows
-
-TBC
-
-View Reduction and Grouping
----------------------------
-
-.. todo:: View Reduction and Grouping
-
-TBC
-
-``POST /db/_design/design-doc/_view/view-name``
-===============================================
-
-* **Method**: ``POST /db/_design/design-doc/_view/view-name``
-* **Request**: List of keys to be returned from specified view
-* **Response**: JSON of the documents returned by the view
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: descending
-
- * **Description**: Return the documents in descending by key order
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: endkey
-
- * **Description**: Stop returning records when the specified key is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: endkey_docid
-
- * **Description**: Stop returning records when the specified document ID
- is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: group
-
- * **Description**: Group the results using the reduce function to a group
- or single row
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: group_level
-
- * **Description**: Specify the group level to be used
- * **Optional**: yes
- * **Type**: numeric
-
- * **Argument**: include_docs
-
- * **Description**: Include the full content of the documents in the return
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: inclusive_end
-
- * **Description**: Specifies whether the specified end key should be
- included in the result
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
-
- * **Argument**: key
-
- * **Description**: Return only documents that match the specified key
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: limit
-
- * **Description**: Limit the number of the returned documents to the
- specified number
- * **Optional**: yes
- * **Type**: numeric
-
- * **Argument**: reduce
-
- * **Description**: Use the reduction function
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
-
- * **Argument**: skip
-
- * **Description**: Skip this number of records before starting to return
- the results
- * **Optional**: yes
- * **Type**: numeric
- * **Default**: 0
-
- * **Argument**: stale
-
- * **Description**: Allow the results from a stale view to be used
- * **Optional**: yes
- * **Type**: string
- * **Default**:
- * **Supported Values**:
-
- * **ok**: Allow stale views
-
- * **Argument**: startkey
-
- * **Description**: Return records starting with the specified key
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: startkey_docid
-
- * **Description**: Return records starting with the specified document ID
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: update_seq
-
- * **Description**: Include the update sequence in the generated results
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
-Executes the specified ``view-name`` from the specified ``design-doc``
-design document. Unlike the ``GET`` method for accessing views, the
-``POST`` method supports the specification of explicit keys to be
-retrieved from the view results. The remainder of the ``POST`` view
-functionality is identical to the :ref:`api-get-view` API.
-
-For example, the request below will return all the recipes where the key
-for the view matches either “claret” or “clear apple cider” :
-
-.. code-block:: http
-
- POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient
- Content-Type: application/json
-
- {
- "keys" : [
- "claret",
- "clear apple juice"
- ]
- }
-
-
-The returned view data contains the standard view information, but only
-where the keys match.
-
-.. code-block:: javascript
-
- {
- "total_rows" : 26484,
- "rows" : [
- {
- "value" : [
- "Scotch collops"
- ],
- "id" : "Scotchcollops",
- "key" : "claret"
- },
- {
- "value" : [
- "Stand pie"
- ],
- "id" : "Standpie",
- "key" : "clear apple juice"
- }
- ],
- "offset" : 6324
- }
-
-Multi-document Fetching
------------------------
-
-By combining the ``POST`` method to a given view with the
-``include_docs=true`` query argument you can obtain multiple documents
-from a database. The result is more efficient than using multiple
-:ref:`api-get-doc` requests.
-
-For example, sending the following request for ingredients matching
-“claret” and “clear apple juice”:
-
-.. code-block:: http
-
- POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true
- Content-Type: application/json
-
- {
- "keys" : [
- "claret",
- "clear apple juice"
- ]
- }
-
-Returns the full document for each recipe:
-
-.. code-block:: javascript
-
- {
- "offset" : 6324,
- "rows" : [
- {
- "doc" : {
- "_id" : "Scotchcollops",
- "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178",
- "cooktime" : "8",
- "ingredients" : [
- {
- "ingredient" : "onion",
- "ingredtext" : "onion, peeled and chopped",
- "meastext" : "1"
- },
- ...
- ],
- "keywords" : [
- "cook method.hob, oven, grill@hob",
- "diet@wheat-free",
- "diet@peanut-free",
- "special collections@classic recipe",
- "cuisine@british traditional",
- "diet@corn-free",
- "diet@citrus-free",
- "special collections@very easy",
- "diet@shellfish-free",
- "main ingredient@meat",
- "occasion@christmas",
- "meal type@main",
- "diet@egg-free",
- "diet@gluten-free"
- ],
- "preptime" : "10",
- "servings" : "4",
- "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.",
- "title" : "Scotch collops",
- "totaltime" : "18"
- },
- "id" : "Scotchcollops",
- "key" : "claret",
- "value" : [
- "Scotch collops"
- ]
- },
- {
- "doc" : {
- "_id" : "Standpie",
- "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a",
- "cooktime" : "92",
- "ingredients" : [
- ... ],
- "keywords" : [
- "diet@dairy-free",
- "diet@peanut-free",
- "special collections@classic recipe",
- "cuisine@british traditional",
- "diet@corn-free",
- "diet@citrus-free",
- "occasion@buffet party",
- "diet@shellfish-free",
- "occasion@picnic",
- "special collections@lunchbox",
- "main ingredient@meat",
- "convenience@serve with salad for complete meal",
- "meal type@main",
- "cook method.hob, oven, grill@hob / oven",
- "diet@cow dairy-free"
- ],
- "preptime" : "30",
- "servings" : "6",
- "subtitle" : "Serve this pie with pickled vegetables and potato salad.",
- "title" : "Stand pie",
- "totaltime" : "437"
- },
- "id" : "Standpie",
- "key" : "clear apple juice",
- "value" : [
- "Stand pie"
- ]
- }
- ],
- "total_rows" : 26484
- }
-
-``GET /db/_design/design-doc/_show/show-name``
-===============================================
-
-.. todo:: GET /db/_design/design-doc/_show/show-name
-
-* **Method**: ``GET /db/_design/design-doc/_show/show-name``
-* **Request**: None
-* **Response**: Returns the result of the show
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: details
-
- * **Description**: Indicates whether details should be included
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: format
-
- * **Description**: Format of the returned information
- * **Optional**: yes
- * **Type**: string
-
-``POST /db/_design/design-doc/_show/show-name/doc``
-===================================================
-
-.. todo:: POST /db/_design/design-doc/_show/show-name/doc
-
-* **Method**: ``POST /db/_design/design-doc/_show/show-name``
-* **Request**: Custom data
-* **Response**: Returns the result of the show
-* **Admin Privileges Required**: no
-
-``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-=========================================================================
-
-.. todo:: GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name
-
-* **Method**: ``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
-
-``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-==========================================================================
-
-.. todo:: POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name
-
-* **Method**: ``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
-
-``GET /db/_design/design-doc/_list/list-name/view-name``
-========================================================
-
-.. todo:: GET /db/_design/design-doc/_list/list-name/view-name
-
-* **Method**: ``GET /db/_design/design-doc/_list/list-name/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
-
-``POST /db/_design/design-doc/_list/list-name/view-name``
-=========================================================
-
-.. todo:: POST /db/_design/design-doc/_list/list-name/view-name
-
-* **Method**: ``POST /db/_design/design-doc/_list/list-name/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
-
-``PUT /db/_design/design-doc/_update/updatename/doc``
-=====================================================
-
-.. todo:: POST /db/_design/design-doc/_update/updatename/doc
-
-* **Method**: ``POST /db/_design/design-doc/_update/updatename/doc``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
-
-``POST /db/_design/design-doc/_update/updatename``
-==================================================
-
-.. todo:: PUT /db/_design/design-doc/_update/updatename/doc
-
-* **Method**: ``PUT /db/_design/design-doc/_update/updatename/doc``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
-
-``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
-=============================================================
-
-.. todo:: ALL /db/_design/design-doc/_rewrite/rewrite-name/anything
-
-* **Method**: ``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
http://git-wip-us.apache.org/repos/asf/couchdb/blob/0357f044/share/docs/rst/api/documents.rst
----------------------------------------------------------------------
diff --git a/share/docs/rst/api/documents.rst b/share/docs/rst/api/documents.rst
deleted file mode 100644
index 9bbf315..0000000
--- a/share/docs/rst/api/documents.rst
+++ /dev/null
@@ -1,919 +0,0 @@
-.. _api-doc:
-
-================
-Document Methods
-================
-
-The CouchDB API Server Document methods detail how to create, read,
-update and delete documents within a database.
-
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| POST | /db | Create a new document |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/doc | Returns the latest revision of the |
-| | | document |
-+--------+-------------------------+-------------------------------------------+
-| HEAD | /db/doc | Returns bare information in the HTTP |
-| | | Headers for the document |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/doc | Inserts a new document, or new version |
-| | | of an existing document |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db/doc | Deletes the document |
-+--------+-------------------------+-------------------------------------------+
-| COPY | /db/doc | Copies the document |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/doc/attachment | Gets the attachment of a document |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/doc/attachment | Adds an attachment of a document |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db/doc/attachment | Deletes an attachment of a document |
-+--------+-------------------------+-------------------------------------------+
-
-``POST /db``
-============
-
-* **Method**: ``POST /db``
-* **Request**: JSON of the new document
-* **Response**: JSON with the committed document information
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: batch
-
- * **Description**: Allow document store request to be batched with others
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**: asd
- * **ok**: Enable
-
-* **Return Codes**:
-
- * **201**:
- Document has been created successfully
- * **409**:
- Conflict - a document with the specified document ID already exists
-
-Create 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.
-
-For example, you can generate a new document with a generated UUID using
-the following request:
-
-.. code-block:: http
-
- POST http://couchdb:5984/recipes/
- Content-Type: application/json
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- }
-
-The return JSON will specify the automatically enerated ID and revision
-information:
-
-.. code-block:: javascript
-
- {
- "id" : "64575eef70ab90a2b8d55fc09e00440d",
- "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``:
-
-.. code-block:: http
-
- POST http://couchdb:5984/recipes/
- Content-Type: application/json
-
- {
- "_id" : "FishStew",
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- }
-
-The structure of the submitted document is as shown in the table below:
-
-In either case, the returned JSON will specify the document ID, revision
-ID, and status message:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
-
-
-.. _api-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
-user-by-user basis) before they are committed to disk. This increases
-the risk of the documents not being stored in the event of a failure,
-since the documents are not written to disk immediately.
-
-To use the batched mode, append the ``batch=ok`` query argument to the
-URL of the ``PUT`` or ``POST`` request. The CouchDB server will respond
-with a 202 HTTP response code immediately.
-
-Including Attachments
----------------------
-
-You can include one or more attachments with a given document by
-incorporating the attachment information within the JSON of the
-document. This provides a simpler alternative to loading documents with
-attachments than making a separate call (see :ref:`api-put-attachment`).
-
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_attachments** (optional): Document Attachment
-
- * **filename**: Attachment information
-
- * **content_type**: MIME Content type string
- * **data**: File attachment content, Base64 encoded
-
-The ``filename`` will be the attachment name. For example, when sending
-the JSON structure below:
-
-.. code-block:: javascript
-
- {
- "_id" : "FishStew",
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- "_attachments" : {
- "styling.css" : {
- "content-type" : "text/css",
- "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=",
- },
- },
- }
-
-
-The attachment ``styling.css`` can be accessed using
-``/recipes/FishStew/styling.css``. For more information on attachments,
-see :ref:`api-get-attachment`.
-
-The document data embedded in to the structure must be encoded using
-base64.
-
-.. _api-get-doc:
-
-``GET /db/doc``
-===============
-
-* **Method**: ``GET /db/doc``
-* **Request**: None
-* **Response**: Returns the JSON for the document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: conflicts
-
- * **Description**: Returns the conflict tree for the document.
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
- * **Supported Values**:
-
- * **true**: Includes the revisions
-
- * **Argument**: rev
-
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**:
-
- * **true**: Includes the revisions
-
- * **Argument**: revs
-
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
-
- * **Argument**: revs_info
-
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**:
-
- * **true**: Includes the revisions
-
-* **Return Codes**:
-
- * **200**:
- Document retrieved
- * **400**:
- The format of the request or revision was invalid
- * **404**:
- The specified document or revision cannot be found, or has been deleted
- * **409**:
- Conflict - a document with the specified document ID already exists
-
-Returns the specified ``doc`` from the specified ``db``. For example, to
-retrieve the document with the id ``FishStew`` you would send the
-following request:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
- Accept: application/json
-
-The returned JSON is the JSON of the document, including the document ID
-and revision number:
-
-.. code-block:: javascript
-
- {
- "_id" : "FishStew",
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "title" : "Irish Fish Stew"
- }
-
-
-Unless you request a specific revision, the latest revision of the
-document will always be returned.
-
-Attachments
------------
-
-If the document includes attachments, then the returned structure will
-contain a summary of the attachments associated with the document, but
-not the attachment data itself.
-
-The JSON for the returned document will include the ``_attachments``
-field, with one or more attachment definitions. For example:
-
-.. code-block:: javascript
-
- {
- "_id" : "FishStew",
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- "_attachments" : {
- "styling.css" : {
- "stub" : true,
- "content-type" : "text/css",
- "length" : 783426,
- },
- },
- }
-
-The format of the returned JSON is shown in the table below:
-
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_attachments** (optional): Document Attachment
-
- * **filename**: Attachment information
-
- * **content_type**: MIME Content type string
- * **length**: Length (bytes) of the attachment data
- * **revpos**: Revision where this attachment exists
- * **stub**: Indicates whether the attachment is a stub
-
-Getting a List of Revisions
----------------------------
-
-You can obtain a list of the revisions for a given document by adding
-the ``revs=true`` parameter to the request URL. For example:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/FishStew?revs=true
- Accept: application/json
-
-The returned JSON structure includes the original document, including a
-``_revisions`` structure that includes the revision information:
-
-.. code-block:: javascript
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "_id" : "FishStew",
- "title" : "Irish Fish Stew",
- "_revisions" : {
- "ids" : [
- "a1a9b39ee3cc39181b796a69cb48521c",
- "7c4740b4dcf26683e941d6641c00c39d",
- "9c65296036141e575d32ba9c034dd3ee"
- ],
- "start" : 3
- },
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
- }
-
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_revisions**: CouchDB Document Revisions
-
- * **ids** [array]: Array of valid revision IDs, in reverse order
- (latest first)
- * **start**: Prefix number for the latest revision
-
-Obtaining an Extended Revision History
---------------------------------------
-
-You can get additional information about the revisions for a given
-document by supplying the ``revs_info`` argument to the query:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/FishStew?revs_info=true
- Accept: application/json
-
-This returns extended revision information, including the availability
-and status of each revision:
-
-.. code-block:: javascript
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "_id" : "FishStew",
- "_revs_info" : [
- {
- "status" : "available",
- "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
- },
- {
- "status" : "available",
- "rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
- },
- {
- "status" : "available",
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
- ],
- "title" : "Irish Fish Stew",
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
- }
-
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_revs_info** [array]: CouchDB Document Extended Revision Info
-
- * **rev**: Full revision string
- * **status**: Status of the revision
-
-Obtaining a Specific Revision
------------------------------
-
-To get a specific revision, use the ``rev`` argument to the request, and
-specify the full revision number:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
- Accept: application/json
-
-The specified revision of the document will be returned, including a
-``_rev`` field specifying the revision that was requested:
-
-.. code-block:: javascript
-
- {
- "_id" : "FishStew",
- "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "title" : "Fish Stew"
- }
-
-``HEAD /db/doc``
-================
-
-* **Method**: ``HEAD /db/doc``
-* **Request**: None
-* **Response**: None
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: revs
-
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
-
- * **Argument**: revs_info
-
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
-
-* **Return Codes**:
-
- * **404**:
- The specified document or revision cannot be found, or has been deleted
-
-Returns the HTTP Headers containing a minimal amount of information
-about the specified document. The method supports the same query
-arguments as the ``GET`` method, but only the header information
-(including document size, and the revision as an ETag), is returned. For
-example, a simple ``HEAD`` request:
-
-.. code-block:: http
-
- HEAD http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
-
-
-Returns the following HTTP Headers:
-
-.. code-block:: javascript
-
- HTTP/1.1 200 OK
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
- Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
- Date: Fri, 05 Nov 2010 14:54:43 GMT
- Content-Type: text/plain;charset=utf-8
- Content-Length: 136
- Cache-Control: must-revalidate
-
-The ``Etag`` header shows the current revision for the requested
-document, and the ``Content-Length`` specifies the length of the data,
-if the document were requested in full.
-
-Adding any of the query arguments (as supported by ```GET```_ method),
-then the resulting HTTP Headers will correspond to what would be
-returned. Note that the current revision is not returned when the
-``refs_info`` argument is used. For example:
-
-.. code-block:: http
-
- HTTP/1.1 200 OK
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
- Date: Fri, 05 Nov 2010 14:57:16 GMT
- Content-Type: text/plain;charset=utf-8
- Content-Length: 609
- Cache-Control: must-revalidate
-
-.. _api-put-doc:
-
-``PUT /db/doc``
-===============
-
-* **Method**: ``PUT /db/doc``
-* **Request**: JSON of the new document, or updated version of the existed
- document
-* **Response**: JSON of the document ID and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: batch
-
- * **Description**: Allow document store request to be batched with others
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**:
-
- * **ok**: Enable
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **201**:
- Document has been created successfully
- * **202**:
- Document accepted for writing (batch mode)
-
-
-The ``PUT`` method creates a new named document, or creates a new
-revision of the existing document. Unlike the ``POST`` method, you
-must specify the document ID in the request URL.
-
-For example, to create the document ``FishStew``, you would send the
-following request:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- }
-
-The return type is JSON of the status, document ID,and revision number:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
-
-Updating an Existing Document
------------------------------
-
-To update an existing document you must specify the current revision
-number within the ``_rev`` parameter. For example:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
-
- {
- "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
- "servings" : 4,
- "subtitle" : "Delicious with fresh salad",
- "title" : "Fish Stew"
- }
-
-Alternatively, you can supply the current revision number in the
-``If-Match`` HTTP header of the request. For example:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew
- If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
- Content-Type: application/json
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh salad",
- "title" : "Fish Stew"
- }
-
-The JSON returned will include the updated revision number:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew99",
- "ok" : true,
- "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
- }
-
-For information on batched writes, which can provide improved
-performance, see :ref:`api-batch-writes`.
-
-.. _api-del-doc:
-
-``DELETE /db/doc``
-==================
-
-* **Method**: ``DELETE /db/doc``
-* **Request**: None
-* **Response**: JSON of the deleted revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **409**:
- Revision is missing, invalid or not the latest
-
-Deletes the specified document from the database. You must supply the
-current (latest) revision, either by using the ``rev`` parameter to
-specify the revision:
-
-.. code-block:: http
-
- DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
- Content-Type: application/json
-
-Alternatively, you can use ETags with the ``If-Match`` field:
-
-.. code-block:: http
-
- DELETE http://couchdb:5984/recipes/FishStew
- If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
- Content-Type: application/json
-
-
-The returned JSON contains the document ID, revision and status:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "4-2719fd41187c60762ff584761b714cfb"
- }
-
-.. note:: Note that deletion of a record increments the revision number. The
- use of a revision for deletion of the record allows replication of
- the database to correctly track the deletion in synchronized copies.
-
-.. _api-copy-doc:
-
-``COPY /db/doc``
-================
-
-* **Method**: ``COPY /db/doc``
-* **Request**: None
-* **Response**: JSON of the new document and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Revision to copy from
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Destination``
-
- * **Description**: Destination document (and optional revision)
- * **Optional**: no
-
-* **Return Codes**:
-
- * **201**:
- Document has been copied and created successfully
- * **409**:
- Revision is missing, invalid or not the latest
-
-The ``COPY`` command (which is non-standard HTTP) copies an existing
-document to a new or existing document.
-
-The source document is specified on the request line, with the
-``Destination`` HTTP Header of the request specifying the target
-document.
-
-Copying a Document
-------------------
-
-You can copy the latest version of a document to a new document by
-specifying the current document and target document:
-
-.. code-block:: http
-
- COPY http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
- Destination: IrishFishStew
-
-The above request copies the document ``FishStew`` to the new document
-``IrishFishStew``. The response is the ID and revision of the new
-document.
-
-.. code-block:: javascript
-
- {
- "id" : "IrishFishStew",
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
-
-Copying from a Specific Revision
---------------------------------
-
-To copy *from* a specific version, use the ``rev`` argument to the query
-string:
-
-.. code-block:: http
-
- COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
- Content-Type: application/json
- Destination: IrishFishStew
-
-The new document will be created using the information in the specified
-revision of the source document.
-
-Copying to an Existing Document
--------------------------------
-
-To copy to an existing document, you must specify the current revision
-string for the target document, using the ``rev`` parameter to the
-``Destination`` HTTP Header string. For example:
-
-.. code-block:: http
-
- COPY http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
- Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee
-
-The return value will be the new revision of the copied document:
-
-.. code-block:: javascript
-
- {
- "id" : "IrishFishStew",
- "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
- }
-
-.. _api-get-attachment:
-
-``GET /db/doc/attachment``
-==========================
-
-* **Method**: ``GET /db/doc/attachment``
-* **Request**: None
-* **Response**: Returns the attachment data
-* **Admin Privileges Required**: no
-
-Returns the file attachment ``attachment`` associated with the document
-``doc``. The raw data of the associated attachment is returned (just as
-if you were accessing a static file. The returned HTTP ``Content-type``
-will be the same as the content type set when the document attachment
-was submitted into the database.
-
-.. _api-put-attachment:
-
-``PUT /db/doc/attachment``
-==========================
-
-* **Method**: ``PUT /db/doc/attachment``
-* **Request**: Raw document data
-* **Response**: JSON document status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Content-Length``
-
- * **Description**: Length (bytes) of the attachment being uploaded
- * **Optional**: no
-
- * **Header**: ``Content-Type``
-
- * **Description**: MIME type for the uploaded attachment
- * **Optional**: no
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **201**:
- Attachment has been accepted
-
-Upload the supplied content as an attachment to the specified document
-(``doc``). The ``attachment`` name provided must be a URL encoded
-string. You must also supply either the ``rev`` query argument or the
-``If-Match`` HTTP header for validation, and the HTTP headers (to set
-the attachment content type). The content type is used when the
-attachment is requested as the corresponding content-type in the
-returned document header.
-
-For example, you could upload a simple text document using the following
-request:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
- Content-Length: 10
- Content-Type: text/plain
-
- Roast it
-
-Or by using the ``If-Match`` HTTP header:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew/basic
- If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
- Content-Length: 10
- Content-Type: text/plain
-
- Roast it
-
-The returned JSON contains the new document information:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
- }
-
-.. note:: Uploading an attachment updates the corresponding document revision.
- Revisions are tracked for the parent document, not individual
- attachments.
-
-Updating an Existing Attachment
--------------------------------
-
-Uploading an attachment using an existing attachment name will update
-the corresponding stored content of the database. Since you must supply
-the revision information to add an attachment to a document, this serves
-as validation to update the existing attachment.
-
-``DELETE /db/doc/attachment``
-=============================
-
-* **Method**: ``DELETE /db/doc/attachment``
-* **Request**: None
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **200**:
- Attachment deleted successfully
- * **409**:
- Supplied revision is incorrect or missing
-
-Deletes the attachment ``attachment`` to the specified ``doc``. You must
-supply the ``rev`` argument with the current revision to delete the
-attachment.
-
-For example to delete the attachment ``basic`` from the recipe
-``FishStew``:
-
-.. code-block:: http
-
- DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
- Content-Type: application/json
-
-
-
-The returned JSON contains the updated revision information:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
- }
-
-.. _JSON object: #table-couchdb-api-db_db-json-changes
-.. _POST: #couchdb-api-dbdoc_db_post
http://git-wip-us.apache.org/repos/asf/couchdb/blob/0357f044/share/docs/rst/api/local.rst
----------------------------------------------------------------------
diff --git a/share/docs/rst/api/local.rst b/share/docs/rst/api/local.rst
deleted file mode 100644
index f73442b..0000000
--- a/share/docs/rst/api/local.rst
+++ /dev/null
@@ -1,157 +0,0 @@
-.. _api-local:
-
-========================================
-Local (non-replicating) Document Methods
-========================================
-
-The Local (non-replicating) document interface allows you to create
-local documents that are not replicated to other databases. These
-documents can be used to hold configuration or other information that is
-required specifically on the local CouchDB instance.
-
-Local documents have the following limitations:
-
-- Local documents are not replicated to other databases.
-
-- The ID of the local document must be known for the document to
- accessed. You cannot obtain a list of local documents from the
- database.
-
-- Local documents are not output by views, or the ``_all_docs`` view.
-
-Local documents can be used when you want to store configuration or
-other information for the current (local) instance of a given database.
-
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| GET | /db/_local/local-doc | Returns the latest revision of the |
-| | | non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/_local/local-doc | Inserts a new version of the |
-| | | non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db/_local/local-doc | Deletes the non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| COPY | /db/_local/local-doc | Copies the non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-
-``GET /db/_local/local-doc``
-============================
-
-* **Method**: ``GET /db/_local/local-doc``
-* **Request**: None
-* **Response**: JSON of the returned document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**:
-
- * **true**: Includes the revisions
-
- * **Argument**: revs
-
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
-
- * **Argument**: revs_info
-
- * **Description**: Return a list of detailed revision information for
- the document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**
-
- * **true**: Includes the revisions
-
-* **Return Codes**:
-
- * **400**:
- The format of the request or revision was invalid
- * **404**:
- The specified document or revision cannot be found, or has been deleted
-
-Gets the specified local document. The semantics are identical to
-accessing a standard document in the specified database, except that the
-document is not replicated. See :ref:`api-get-doc`.
-
-``PUT /db/_local/local-doc``
-============================
-
-* **Method**: ``PUT /db/_local/local-doc``
-* **Request**: JSON of the document
-* **Response**: JSON with the committed document information
-* **Admin Privileges Required**: no
-* **Return Codes**:
-
- * **201**:
- Document has been created successfully
-
-Stores the specified local document. The semantics are identical to
-storing a standard document in the specified database, except that the
-document is not replicated. See :ref:`api-put-doc`.
-
-``DELETE /db/_local/local-doc``
-===============================
-
-* **Method**: ``DELETE /db/_local/local-doc``
-* **Request**: None
-* **Response**: JSON with the deleted document information
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **409**:
- Supplied revision is incorrect or missing
-
-Deletes the specified local document. The semantics are identical to
-deleting a standard document in the specified database, except that the
-document is not replicated. See :ref:`api-del-doc`.
-
-``COPY /db/_local/local-doc``
-=============================
-
-* **Method**: ``COPY /db/_local/local-doc``
-* **Request**: None
-* **Response**: JSON of the copied document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Revision to copy from
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Destination``
-
- * **Description**: Destination document (and optional revision)
- * **Optional**: no
-
-Copies the specified local document. The semantics are identical to
-copying a standard document in the specified database, except that the
-document is not replicated. See :ref:`api-copy-doc`.