You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ro...@apache.org on 2014/11/28 22:00:23 UTC
[21/47] couchdb commit: updated refs/heads/enable-csp-default to
dbd38a1
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
deleted file mode 100644
index d13ff30..0000000
--- a/share/doc/src/api/database/bulk-api.rst
+++ /dev/null
@@ -1,646 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/db/all_docs:
-
-``/db/_all_docs``
-=================
-
-.. http:get:: /{db}/_all_docs
- :synopsis: Returns a built-in view of all documents in this database
-
- Returns a JSON structure of all of the documents in a given database.
- The information is returned as a JSON structure containing meta
- information about the return structure, including a list of all documents
- and basic contents, consisting the ID, revision and key. The key is the
- from the document's ``_id``.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :query boolean conflicts: Includes `conflicts` information in response.
- Ignored if `include_docs` isn't ``true``. Default is ``false``.
- :query boolean descending: Return the documents in descending by key order.
- Default is ``false``.
- :query string endkey: Stop returning records when the specified key is
- reached. *Optional*.
- :query string end_key: Alias for `endkey` param.
- :query string endkey_docid: Stop returning records when the specified
- document ID is reached. *Optional*.
- :query string end_key_doc_id: Alias for `endkey_docid` param.
- :query boolean include_docs: Include the full content of the documents in
- the return. Default is ``false``.
- :query boolean inclusive_end: Specifies whether the specified end key should
- be included in the result. Default is ``true``.
- :query string key: Return only documents that match the specified key.
- *Optional*.
- :query number limit: Limit the number of the returned documents to the
- specified number. *Optional*.
- :query number skip: Skip this number of records before starting to return
- the results. Default is ``0``.
- :query string stale: Allow the results from a stale view to be used, without
- triggering a rebuild of all views within the encompassing design doc.
- Supported values: ``ok`` and ``update_after``. *Optional*.
- :query string startkey: Return records starting with the specified key.
- *Optional*.
- :query string start_key: Alias for `startkey` param.
- :query string startkey_docid: Return records starting with the specified
- document ID. *Optional*.
- :query string start_key_doc_id: Alias for `startkey_docid` param.
- :query boolean update_seq: Response includes an ``update_seq`` value
- indicating which sequence id of the underlying database the view reflects.
- Default is ``false``.
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header ETag: Response signature
- :>json number offset: Offset where the document list started
- :>json array rows: Array of view row objects. By default the information
- returned contains only the document ID and revision.
- :>json number total_rows: Number of documents in the database/view. Note that
- this is not the number of rows returned in the actual query.
- :>json number update_seq: Current update sequence for the database
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET /db/_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: Sat, 10 Aug 2013 16:22:56 GMT
- ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
-
- {
- "offset": 0,
- "rows": [
- {
- "id": "16e458537602f5ef2a710089dffd9453",
- "key": "16e458537602f5ef2a710089dffd9453",
- "value": {
- "rev": "1-967a00dff5e02add41819138abb3284d"
- }
- },
- {
- "id": "a4c51cdfa2069f3e905c431114001aff",
- "key": "a4c51cdfa2069f3e905c431114001aff",
- "value": {
- "rev": "1-967a00dff5e02add41819138abb3284d"
- }
- },
- {
- "id": "a4c51cdfa2069f3e905c4311140034aa",
- "key": "a4c51cdfa2069f3e905c4311140034aa",
- "value": {
- "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
- }
- },
- {
- "id": "a4c51cdfa2069f3e905c431114003597",
- "key": "a4c51cdfa2069f3e905c431114003597",
- "value": {
- "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
- }
- },
- {
- "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
- "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
- "value": {
- "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
- }
- }
- ],
- "total_rows": 5
- }
-
-
-.. http:post:: /{db}/_all_docs
- :synopsis: Returns certain rows from the built-in view of all documents
-
- The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
- selected from the database. This enables you to request multiple
- documents in a single request, in place of multiple :get:`/{db}/{docid}`
- requests.
-
- The request body should contain a list of the keys to be returned as an
- array to a ``keys`` object. For example:
-
- .. code-block:: http
-
- POST /db/_all_docs HTTP/1.1
- Accept: application/json
- Content-Length: 70
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "keys" : [
- "Zingylemontart",
- "Yogurtraita"
- ]
- }
-
- The returned JSON is the all documents structure, but with only the
- selected keys in the output:
-
- .. code-block:: javascript
-
- {
- "total_rows" : 2666,
- "rows" : [
- {
- "value" : {
- "rev" : "1-a3544d296de19e6f5b932ea77d886942"
- },
- "id" : "Zingylemontart",
- "key" : "Zingylemontart"
- },
- {
- "value" : {
- "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
- },
- "id" : "Yogurtraita",
- "key" : "Yogurtraita"
- }
- ],
- "offset" : 0
- }
-
-
-.. _api/db/bulk_docs:
-
-``/db/_bulk_docs``
-==================
-
-.. http:post:: /{db}/_bulk_docs
- :synopsis: Inserts or updates multiple documents in to the database in a single request
-
- The bulk document API allows you to create and update multiple documents
- at the same time within a single request. The basic operation is similar
- to creating or updating a single document, except that you batch the
- document structure and information.
-
- When creating new documents the document ID (``_id``) is optional.
-
- For updating existing documents, you must provide the document ID, revision
- information (``_rev``), and new document values.
-
- In case of batch deleting documents all fields as document ID, revision
- information and deletion status (``_deleted``) are required.
-
- :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*
- :<json boolean all_or_nothing: Sets the database commit mode to use
- :ref:`all-or-nothing <api/db/bulk_docs/semantics>` semantics.
- Default is ``false``. *Optional*
- :<json array docs: List of documents objects
- :<json boolean new_edits: If ``false``, prevents the database from assigning
- them new revision IDs. Default is ``true``. *Optional*
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>jsonarr string id: Document ID
- :>jsonarr string rev: New document revision token. Available
- if document have saved without errors. *Optional*
- :>jsonarr string error: Error type. *Optional*
- :>jsonarr string reason: Error reason. *Optional*
- :code 201: Document(s) have been created or updated
- :code 400: The request provided invalid JSON data
- :code 417: Occurs when ``all_or_nothing`` option set as ``true`` and
- at least one document was rejected by :ref:`validation function <vdufun>`
- :code 500: Malformed data provided, while it's still valid JSON
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_bulk_docs HTTP/1.1
- Accept: application/json
- Content-Length: 109
- Content-Type:application/json
- Host: localhost:5984
-
- {
- "docs": [
- {
- "_id": "FishStew"
- },
- {
- "_id": "LambStew",
- "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
- "_deleted": true
- }
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 144
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 00:15:05 GMT
- Server: CouchDB (Erlang/OTP)
-
- [
- {
- "ok": true,
- "id": "FishStew",
- "rev":" 1-967a00dff5e02add41819138abb3284d"
- },
- {
- "ok": true,
- "id": "LambStew",
- "rev": "3-f9c62b2169d0999103e9f41949090807"
- }
- ]
-
-
-Inserting Documents in Bulk
----------------------------
-
-Each time a document is stored or updated in CouchDB, the internal B-tree
-is updated. Bulk insertion provides efficiency gains in both storage space,
-and time, by consolidating many of the updates to intermediate B-tree nodes.
-
-It is not intended as a way to perform ``ACID``-like transactions in CouchDB,
-the only transaction boundary within CouchDB is a single update to a single
-database. The constraints are detailed in :ref:`api/db/bulk_docs/semantics`.
-
-To insert documents in bulk into a database you need to supply a JSON
-structure with the array of documents that you want to add to the database.
-You can either include a document ID, or allow the document ID to be
-automatically generated.
-
-For example, the following update inserts three new documents, two with the
-supplied document IDs, and one which will have a document ID generated:
-
-.. code-block:: http
-
- POST /source/_bulk_docs HTTP/1.1
- Accept: application/json
- Content-Length: 323
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "docs": [
- {
- "_id": "FishStew",
- "servings": 4,
- "subtitle": "Delicious with freshly baked bread",
- "title": "FishStew"
- },
- {
- "_id": "LambStew",
- "servings": 6,
- "subtitle": "Serve with a whole meal scone topping",
- "title": "LambStew"
- },
- {
- "_id": "BeefStew",
- "servings": 8,
- "subtitle": "Hand-made dumplings make a great accompaniment",
- "title": "BeefStew"
- }
- ]
- }
-
-
-The return type from a bulk insertion will be :statuscode:`201`,
-with the content of the returned structure indicating specific success
-or otherwise messages on a per-document basis.
-
-The return structure from the example above contains a list of the
-documents created, here with the combination and their revision IDs:
-
-.. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 215
- Content-Type: application/json
- Date: Sat, 26 Oct 2013 00:10:39 GMT
- Server: CouchDB (Erlang OTP)
-
- [
- {
- "id": "FishStew",
- "ok": true,
- "rev": "1-6a466d5dfda05e613ba97bd737829d67"
- },
- {
- "id": "LambStew",
- "ok": true,
- "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
- },
- {
- "id": "BeefStew",
- "ok": true,
- "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
- }
- ]
-
-
-The content and structure of the returned JSON will depend on the transaction
-semantics being used for the bulk update; see :ref:`api/db/bulk_docs/semantics`
-for more information. Conflicts and validation errors when updating documents in
-bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
-
-Updating Documents in Bulk
---------------------------
-
-The bulk document update procedure is similar to the insertion
-procedure, except that you must specify the document ID and current
-revision for every document in the bulk update JSON string.
-
-For example, you could send the following request:
-
-.. code-block:: http
-
- POST /recipes/_bulk_docs HTTP/1.1
- Accept: application/json
- Content-Length: 464
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "docs": [
- {
- "_id": "FishStew",
- "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
- "servings": 4,
- "subtitle": "Delicious with freshly baked bread",
- "title": "FishStew"
- },
- {
- "_id": "LambStew",
- "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
- "servings": 6,
- "subtitle": "Serve with a whole meal scone topping",
- "title": "LambStew"
- },
- {
- "_id": "BeefStew",
- "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
- "servings": 8,
- "subtitle": "Hand-made dumplings make a great accompaniment",
- "title": "BeefStew"
- }
- ]
- }
-
-The return structure is the JSON of the updated documents, with the new
-revision and ID information:
-
-.. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 215
- Content-Type: application/json
- Date: Sat, 26 Oct 2013 00:10:39 GMT
- Server: CouchDB (Erlang OTP)
-
- [
- {
- "id": "FishStew",
- "ok": true,
- "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
- },
- {
- "id": "LambStew",
- "ok": true,
- "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
- },
- {
- "id": "BeefStew",
- "ok": true,
- "rev": "2-9801936a42f06a16f16c30027980d96f"
- }
- ]
-
-
-You can optionally delete documents during a bulk update by adding the
-``_deleted`` field with a value of ``true`` to each document ID/revision
-combination within the submitted JSON structure.
-
-The return type from a bulk insertion will be :statuscode:`201`, with the
-content of the returned structure indicating specific success or otherwise
-messages on a per-document basis.
-
-The content and structure of the returned JSON will depend on the transaction
-semantics being used for the bulk update; see :ref:`api/db/bulk_docs/semantics`
-for more information. Conflicts and validation errors when updating documents in
-bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
-
-.. _api/db/bulk_docs/semantics:
-
-Bulk Documents Transaction Semantics
-------------------------------------
-
-CouchDB supports two different modes for updating (or inserting)
-documents using the bulk documentation system. Each mode affects both
-the state of the documents in the event of system failure, and the level
-of conflict checking performed on each document. The two modes are:
-
-- **non-atomic**
-
- The default mode is `non-atomic`, that is, CouchDB will only guarantee
- that some of the documents will be saved when you send the request.
- The response will contain the list of documents successfully inserted
- or updated during the process. In the event of a crash, some of the
- documents may have been successfully saved, and some will have been
- lost.
-
- In this mode, the response structure will indicate whether the
- document was updated by supplying the new ``_rev`` parameter
- indicating a new document revision was created. If the update failed,
- then you will get an ``error`` of type ``conflict``. For example:
-
- .. code-block:: javascript
-
- [
- {
- "id" : "FishStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- },
- {
- "id" : "LambStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- },
- {
- "id" : "BeefStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- }
- ]
-
-
- In this case no new revision has been created and you will need to
- submit the document update, with the correct revision tag, to update
- the document.
-
-- **all-or-nothing**
-
- In `all-or-nothing` mode, either all documents are written to the
- database, or no documents are written to the database, in the event
- of a system failure during commit.
-
- In addition, the per-document conflict checking is not performed.
- Instead a new revision of the document is created, even if the new
- revision is in conflict with the current revision in the database.
- The returned structure contains the list of documents with new
- revisions:
-
- .. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 215
- Content-Type: application/json
- Date: Sat, 26 Oct 2013 00:13:33 GMT
- Server: CouchDB (Erlang OTP)
-
- [
- {
- "id": "FishStew",
- "ok": true,
- "rev": "1-6a466d5dfda05e613ba97bd737829d67"
- },
- {
- "id": "LambStew",
- "ok": true,
- "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
- },
- {
- "id": "BeefStew",
- "ok": true,
- "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
- }
- ]
-
- When updating documents using this mode the revision of a document
- included in views will be arbitrary. You can check the conflict
- status for a document by using the ``conflicts=true`` query argument
- when accessing the view. Conflicts should be handled individually to
- ensure the consistency of your database.
-
- To use this mode, you must include the ``all_or_nothing`` field (set
- to true) within the main body of the JSON of the request.
-
-The effects of different database operations on the different modes are
-summarized below:
-
-* **Transaction Mode**: ``Non-atomic``
-
- * **Transaction**: ``Insert``
-
- * **Cause**: Requested document ID already exists
- * **Resolution**: Resubmit with different document ID, or update the
- existing document
-
- * **Transaction**: ``Update``
-
- * **Cause**: Revision missing or incorrect
- * **Resolution**: Resubmit with correct revision
-
-* **Transaction Mode**: ``All-or-nothing``
-
- * **Transaction**: ``Insert`` / ``Update``
-
- * **Cause**: Additional revision inserted
- * **Resolution**: Resolve conflicted revisions
-
-Replication of documents is independent of the type of insert or update.
-The documents and revisions created during a bulk insert or update are
-replicated in the same way as any other document. This can mean that if
-you make use of the `all-or-nothing` mode the exact list of documents,
-revisions (and their conflict state) may or may not be replicated to
-other databases correctly.
-
-.. _api/db/bulk_docs/validation:
-
-Bulk Document Validation and Conflict Errors
---------------------------------------------
-
-The JSON returned by the ``_bulk_docs`` operation consists of an array
-of JSON structures, one for each document in the original submission.
-The returned JSON structure should be examined to ensure that all of the
-documents submitted in the original request were successfully added to
-the database.
-
-When a document (or document revision) is not correctly committed to the
-database because of an error, you should check the ``error`` field to
-determine error type and course of action. Errors will be one of the
-following type:
-
-- **conflict**
-
- The document as submitted is in conflict. If you used the default
- bulk transaction mode then the new revision will not have been
- created and you will need to re-submit the document to the database.
- If you used ``all-or-nothing`` mode then you will need to manually
- resolve the conflicted revisions of the document.
-
- Conflict resolution of documents added using the bulk docs interface
- is identical to the resolution procedures used when resolving
- conflict errors during replication.
-
-- **forbidden**
-
- Entries with this error type indicate that the validation routine
- applied to the document during submission has returned an error.
-
- For example, if your :ref:`validation routine <vdufun>` includes
- the following:
-
- .. code-block:: javascript
-
- throw({forbidden: 'invalid recipe ingredient'});
-
- The error response returned will be:
-
- .. code-block:: http
-
- HTTP/1.1 417 Expectation Failed
- Cache-Control: must-revalidate
- Content-Length: 120
- Content-Type: application/json
- Date: Sat, 26 Oct 2013 00:05:17 GMT
- Server: CouchDB (Erlang OTP)
-
- {
- "error": "forbidden",
- "id": "LambStew",
- "reason": "invalid recipe ingredient",
- "rev": "1-34c318924a8f327223eed702ddfdc66d"
- }
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
deleted file mode 100644
index 6e48f9b..0000000
--- a/share/doc/src/api/database/changes.rst
+++ /dev/null
@@ -1,584 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/db/changes:
-
-================
-``/db/_changes``
-================
-
-.. 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
- }
- ]
- }
-
-.. _length of URL is limited: http://stackoverflow.com/a/417184/965635
-
-.. versionchanged:: 0.11.0 added ``include_docs`` parameter
-.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
- for ``filter`` one
-.. versionchanged:: 1.3.0 ``since`` parameter could take `now` value to start
- listen changes since current seq number.
-.. versionchanged:: 1.3.0 ``eventsource`` feed type added.
-.. versionchanged:: 1.4.0 Support ``Last-Event-ID`` header.
-.. versionchanged:: 1.6.0 added ``attachments`` and ``att_encoding_info``
- 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.
-
-
-.. 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
- }
- ]
- }
-
-
-.. _changes:
-
-Changes Feeds
-=============
-
-.. _changes/normal:
-
-Polling
--------
-
-By default all changes are immediately returned within the JSON body::
-
- GET /somedatabase/_changes HTTP/1.1
-
-.. code-block:: javascript
-
- {"results":[
- {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]},
- {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]},
- {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
- ],
- "last_seq":5}
-
-``results`` is the list of changes in sequential order. New and changed
-documents only differ in the value of the rev; deleted documents include the
-``"deleted": true`` attribute. (In the ``style=all_docs mode``, deleted applies
-only to the current/winning revision. The other revisions listed might be
-deleted even if there is no deleted property; you have to ``GET`` them
-individually to make sure.)
-
-``last_seq`` is the sequence number of the last update returned. (Currently it
-will always be the same as the seq of the last item in results.)
-
-Sending a ``since`` param in the query string skips all changes up to and
-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.
-
-In the return format for ``continuous`` mode, the server sends a ``CRLF``
-(carriage-return, linefeed) delimited line for each change. Each line
-contains the `JSON object` described above.
-
-You can also request the full contents of each document change (instead
-of just the change notification) by using the ``include_docs`` parameter.
-
-.. code-block:: javascript
-
- {
- "last_seq": 5
- "results": [
- {
- "changes": [
- {
- "rev": "2-eec205a9d413992850a6e32678485900"
- }
- ],
- "deleted": true,
- "id": "deleted",
- "seq": 5,
- }
- ]
- }
-
-.. _changes/longpoll:
-
-Long Polling
-------------
-
-The `longpoll` feed, probably most applicable for a browser, is a more
-efficient form of polling that waits for a change to occur before the response
-is sent. `longpoll` avoids the need to frequently poll CouchDB to discover
-nothing has changed!
-
-The request to the server will remain open until a change is made on the
-database and is subsequently transferred, and then the connection will close.
-This is low load for both server and client.
-
-The response is basically the same JSON as is sent for the `normal` feed.
-
-Because the wait for a change can be significant you can set a
-timeout before the connection is automatically closed (the
-``timeout`` argument). You can also set a heartbeat interval (using
-the ``heartbeat`` query argument), which sends a newline to keep the
-connection active.
-
-
-.. _changes/continuous:
-
-Continuous
-----------
-
-Continually polling the CouchDB server is not ideal - setting up new HTTP
-connections just to tell the client that nothing happened puts unnecessary
-strain on CouchDB.
-
-A continuous feed stays open and connected to the database until explicitly
-closed and changes are sent to the client as they happen, i.e. in near
-real-time.
-
-As with the `longpoll` feed type you can set both the timeout and heartbeat
-intervals to ensure that the connection is kept open for new changes
-and updates.
-
-The continuous feed's response is a little different than the other feed types
-to simplify the job of the client - each line of the response is either empty
-or a JSON object representing a single change, as found in the normal feed's
-results.
-
-.. code-block:: text
-
- GET /somedatabase/_changes?feed=continuous HTTP/1.1
-
-.. code-block:: javascript
-
- {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]}
- {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]}
- {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
- ... tum tee tum ...
- {"seq":6,"id":"updated","changes":[{"rev":"3-825cb35de44c433bfb2df415563a19de"}]}
-
-Obviously, `... tum tee tum ...` does not appear in the actual response, but
-represents a long pause before the change with seq 6 occurred.
-
-.. _Change Notifications in the book CouchDB The Definitive Guide: http://guide.couchdb.org/draft/notifications.html
-
-.. _changes/eventsource:
-
-Event Source
-------------
-
-The `eventsource` feed provides push notifications that can be consumed in
-the form of DOM events in the browser. Refer to the `W3C eventsource
-specification`_ for further details. CouchDB also honours the ``Last-Event-ID``
-parameter.
-
-.. code-block:: text
-
- GET /somedatabase/_changes?feed=eventsource HTTP/1.1
-
-.. code-block:: javascript
-
- // define the event handling function
- if (window.EventSource) {
-
- 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);
- };
-
- // start listening for events
- source.addEventListener('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:
-
-.. 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).
-
-.. 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.
-
-.. _W3C eventsource specification: http://www.w3.org/TR/eventsource/
-
-
-.. _changes/filter:
-
-Filtering
-=========
-
-You can filter the contents of the changes feed in a number of ways. The
-most basic way is to specify one or more document IDs to the query. This
-causes the returned structure value to only contain changes for the
-specified IDs. Note that the value of this query argument should be a
-JSON formatted array.
-
-You can also filter the ``_changes`` feed by defining a filter function
-within a design document. The specification for the filter is the same
-as for replication filters. You specify the name of the filter function
-to the ``filter`` parameter, specifying the design document name and
-:ref:`filter name <filterfun>`. For example:
-
-.. code-block:: http
-
- GET /db/_changes?filter=design_doc/filtername
-
-Additionally, there are couple of builtin filters are available and described
-below.
-
-
-.. _changes/filter/doc_ids:
-
-_doc_ids
---------
-
-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
--------
-
-The ``_design`` filter accepts only changes for any design document within the
-requested database.
-
-**Request**:
-
-.. code-block:: http
-
- 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
- }
- ]
- }
-
-
-.. _changes/filter/view:
-
-_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.
-
-.. 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.
-
-.. 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.
-
- 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
-
-**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://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
deleted file mode 100644
index a1483d9..0000000
--- a/share/doc/src/api/database/common.rst
+++ /dev/null
@@ -1,436 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _api/db:
-
-``/db``
-=======
-
-.. http:head:: /{db}
- :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.
-
- :param db: Database name
- :code 200: Database exists
- :code 404: Requested database not found
-
- **Request**:
-
- .. code-block:: http
-
- HEAD /test HTTP/1.1
- 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 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
- }
-
-
-.. http:put:: /{db}
- :synopsis: Creates a new database
-
- Creates a new database. The database name ``{db}`` must be composed by
- following next rules:
-
- - Name must begin with a lowercase letter (``a-z``)
-
- - Lowercase characters (``a-z``)
-
- - Digits (``0-9``)
-
- - Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and
- ``/``.
-
- 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
-
- **Request**:
-
- .. code-block:: http
-
- PUT /db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. 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)
-
- {
- "ok": true
- }
-
- If we repeat the same request to CouchDB, it will response with :code:`412`
- since the database already exists:
-
- **Request**:
-
- .. code-block:: http
-
- PUT /db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. 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)
-
- {
- "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`:
-
- **Request**:
-
- .. code-block:: http
-
- PUT /_db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Request**:
-
- .. 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:delete:: /{db}
- :synopsis: Deletes an existing database
-
- Deletes the specified database, and all the documents and attachments
- contained within it.
-
- .. 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.
-
- :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**:
-
- .. code-block:: http
-
- DELETE /db HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. 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: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"
- }
-
-
-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**:
-
- .. code-block:: http
-
- 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"
- }
-
- **Response**:
-
- .. 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"
- }
-
-
-.. _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
-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:`/{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.
-
-**Request**:
-
-.. code-block:: http
-
- 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"
- }
-
-**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
- }
-
-.. _Regular Expressions: http://en.wikipedia.org/wiki/Regular_expression
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/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
deleted file mode 100644
index 706eedf..0000000
--- a/share/doc/src/api/database/compact.rst
+++ /dev/null
@@ -1,243 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. 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
-
- 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.
-
- - 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.
-
- 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`.
-
- :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/_compact 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
- }
-
-
-.. _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
- }
-
- .. 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.
-
-.. _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
- }
-
-
-.. _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
- }
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/database/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/index.rst b/share/doc/src/api/database/index.rst
deleted file mode 100644
index 5da6a32..0000000
--- a/share/doc/src/api/database/index.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _api/database:
-
-=========
-Databases
-=========
-
-The Database endpoint provides an interface to an entire database with in
-CouchDB. These are database-level, rather than document-level requests.
-
-For all these requests, the database name within the URL path
-should be the database name that you wish to perform the operation on.
-For example, to obtain the meta information for the database
-``recipes``, you would use the HTTP request:
-
-.. code-block:: http
-
- GET /recipes
-
-For clarity, the form below is used in the URL paths:
-
-.. code-block:: http
-
- GET /db
-
-Where ``db`` is the name of any database.
-
-.. toctree::
-
- common
- bulk-api
- changes
- compact
- security
- temp-views
- misc
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
deleted file mode 100644
index 194dac3..0000000
--- a/share/doc/src/api/database/misc.rst
+++ /dev/null
@@ -1,351 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/db/purge:
-
-``/db/_purge``
-==============
-
-.. http:post:: /{db}/_purge
- :synopsis: Purges some historical documents entirely from database history
-
- A database purge permanently removes the references to deleted documents
- from the database. Normal deletion of a document within CouchDB does not
- remove the document from the database, instead, the document is marked as
- ``_deleted=true`` (and a new revision is created). This is to ensure that
- deleted documents can be replicated to other databases as having been
- deleted. This also means that you can check the status of a document and
- identify that the document has been deleted by its absence.
-
- .. warning::
-
- Purging a document from a database should only be done as a last resort
- when sensitive information has been introduced inadvertently into a
- database. In clustered or replicated environments it is very difficult
- to guarantee that a particular purged document has been removed from all
- replicas. Do not rely on this API as a way of doing secure deletion.
-
- The purge operation removes the references to the deleted documents from
- the database. The purging of old documents is not replicated to other
- databases. If you are replicating between databases and have deleted a
- large number of documents you should run purge on each database.
-
- .. note::
-
- Purging documents does not remove the space used by them on disk. To
- reclaim disk space, you should run a database compact (see
- :ref:`api/db/compact`), and compact views (see :ref:`api/db/compact/ddoc`).
-
- The format of the request must include the document ID and one or more
- revisions that must be purged.
-
- The response will contain the purge sequence number, and a list of the
- document IDs and revisions successfully purged.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object: Mapping of document ID to list of revisions to purge
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json number purge_seq: Purge sequence number
- :>json object purged: Mapping of document ID to list of purged revisions
- :code 200: Request completed successfully
- :code 400: Invalid database name or JSON payload
- :code 415: Bad :header:`Content-Type` value
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_purge HTTP/1.1
- Accept: application/json
- Content-Length: 76
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
- "3-0e871ef78849b0c206091f1a7af6ec41"
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 103
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "purge_seq":3,
- "purged":{
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
- ]
- }
- }
-
-
-Updating Indexes
-----------------
-
-The number of purges on a database is tracked using a purge sequence.
-This is used by the view indexer to optimize the updating of views that
-contain the purged documents.
-
-When the indexer identifies that the purge sequence on a database has
-changed, it compares the purge sequence of the database with that stored
-in the view index. If the difference between the stored sequence and
-database is sequence is only 1, then the indexer uses a cached list of
-the most recently purged documents, and then removes these documents
-from the index individually. This prevents completely rebuilding the
-index from scratch.
-
-If the difference between the stored sequence number and current
-database sequence is greater than 1, then the view index is entirely
-rebuilt. This is an expensive operation as every document in the
-database must be examined.
-
-
-.. _api/db/missing_revs:
-
-``/db/_missing_revs``
-=====================
-
-.. http:post:: /{db}/_missing_revs
- :synopsis: By given list of document revisions returns the document revisions that do not exist in the database
-
- With given a list of document revisions, returns the document revisions that
- do not exist in the database.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object: Mapping of document ID to list of revisions to lookup
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json object missing_revs: Mapping of document ID to list of missed revisions
- :code 200: Request completed successfully
- :code 400: Invalid database name or JSON payload
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_missing_revs HTTP/1.1
- Accept: application/json
- Content-Length: 76
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
- "3-0e871ef78849b0c206091f1a7af6ec41"
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 64
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "missed_revs":{
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
- ]
- }
- }
-
-
-.. _api/db/revs_diff:
-
-``/db/_revs_diff``
-==================
-
-.. http:post:: /{db}/_revs_diff
- :synopsis: By given list of document revisions returns differences between the given revisions and ones that are in the database
-
- Given a set of document/revision IDs, returns the subset of those that do
- not correspond to revisions stored in the database.
-
- Its primary use is by the replicator, as an important optimization: after
- receiving a set of new revision IDs from the source database, the replicator
- sends this set to the destination database's ``_revs_diff`` to find out which
- of them already exist there. It can then avoid fetching and sending
- already-known document bodies.
-
- Both the request and response bodies are JSON objects whose keys are document
- IDs; but the values are structured differently:
-
- - In the request, a value is an array of revision IDs for that document.
-
- - In the response, a value is an object with a ``missing``: key, whose value
- is a list of revision IDs for that document (the ones that are not stored
- in the database) and optionally a ``possible_ancestors`` key, whose value is
- an array of revision IDs that are known that might be ancestors of
- the missing revisions.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object: Mapping of document ID to list of revisions to lookup
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json array missing: List of missed revisions for specified document
- :>json array possible_ancestors: List of revisions that *may be* ancestors
- for specified document and its current revision in requested database
- :code 200: Request completed successfully
- :code 400: Invalid database name or JSON payload
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_revs_diff HTTP/1.1
- Accept: application/json
- Content-Length: 113
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "190f721ca3411be7aa9477db5f948bbb": [
- "3-bb72a7682290f94a985f7afac8b27137",
- "4-10265e5a26d807a3cfa459cf1a82ef2e",
- "5-067a00dff5e02add41819138abb3284d"
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 88
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 16:56:02 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "190f721ca3411be7aa9477db5f948bbb": {
- "missing": [
- "3-bb72a7682290f94a985f7afac8b27137",
- "5-067a00dff5e02add41819138abb3284d"
- ],
- "possible_ancestors": [
- "4-10265e5a26d807a3cfa459cf1a82ef2e"
- ]
- }
- }
-
-
-.. _api/db/revs_limit:
-
-``/db/_revs_limit``
-===================
-
-.. http:get:: /{db}/_revs_limit
- :synopsis: Returns the limit of historical revisions to store for a single document in the database
-
- Gets the current ``revs_limit`` (revision limit) setting.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET /db/_revs_limit HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 5
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 17:27:30 GMT
- Server: CouchDB (Erlang/OTP)
-
- 1000
-
-
-.. http:put:: /{db}/_revs_limit
- :synopsis: Sets the limit of historical revisions to store for a single document in the database
-
- Sets the maximum number of document revisions that will be tracked by
- CouchDB, even after compaction has occurred. You can set the revision
- limit on a database with a scalar integer of the limit that you want
- to set as the request body.
-
- :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 200: Request completed successfully
- :code 400: Invalid JSON data
-
- **Request**:
-
- .. code-block:: http
-
- PUT /db/_revs_limit HTTP/1.1
- Accept: application/json
- Content-Length: 5
- Content-Type: application/json
- Host: localhost:5984
-
- 1000
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 17:47:52 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "ok": true
- }
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
deleted file mode 100644
index f01d447..0000000
--- a/share/doc/src/api/database/security.rst
+++ /dev/null
@@ -1,182 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/db/security:
-
-``/db/_security``
-=================
-
-.. http:get:: /{db}/_security
- :synopsis: Returns the special security object for the database
-
- Returns the current security object from the specified database.
-
- The security object consists of two compulsory elements, ``admins``
- and ``members``, which are used to specify the list of users and/or roles
- that have admin and members rights to the database respectively:
-
- - ``members``: they can read all types of documents from the DB, and they can
- write (and edit) documents to the DB except for design documents.
-
- - ``admins``: they have all the privileges of ``members`` plus the privileges:
- write (and edit) design documents, add/remove database admins and members,
- set the :ref:`database revisions limit <api/db/revs_limit>` and execute
- :ref:`temporary views <api/db/temp_view>` against the database.
- They can not create a database nor delete a database.
-
- Both ``members`` and ``admins`` objects contain two array-typed fields:
-
- - ``names``: List of CouchDB user names as strings
- - ``roles``: List of roles as strings
-
- Any other additional fields in the security object are optional.
- The entire security object is made available to validation and other
- internal functions so that the database can control and limit functionality.
-
- If both the names and roles fields of either the admins or members properties
- are empty arrays, it means the database has no admins or members.
-
- Having no admins, only server admins (with the reserved ``_admin`` role)
- are able to update design document and make other admin level changes.
-
- Having no members, any user can write regular documents (any non-design
- document) and read documents from the database.
-
- If there are any member names or roles defined for a database, then only
- authenticated users having a matching name or role are allowed to
- read documents from the database (or do a :get:`/{db}` call).
-
- .. note::
-
- If the security object for a database has never been set, then the
- value returned will be empty.
-
- Also note, that security objects are not regular versioned documents
- (that is, they are not under MVCC rules). This is a design choice to
- speedup authorization checks (avoids traversing a database`s documents
- B-Tree).
-
- :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 object admins: Object with two fields as ``names`` and ``roles``.
- See description above for more info.
- :>json object members: Object with two fields as ``names`` and ``roles``.
- See description above for more info.
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET /db/_security HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 109
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 19:05:29 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "admins": {
- "names": [
- "superuser"
- ],
- "roles": [
- "admins"
- ]
- },
- "members": {
- "names": [
- "user1",
- "user2"
- ],
- "roles": [
- "developers"
- ]
- }
- }
-
-
-.. http:put:: /{db}/_security
- :synopsis: Sets the special security object for the database
-
- Sets the security object for the given database.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object admins: Object with two fields as ``names`` and ``roles``.
- :ref:`See description above for more info <api/db/security>`.
- :<json object members: Object with two fields as ``names`` and ``roles``.
- :ref:`See description above for more info <api/db/security>`.
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json boolean ok: Operation status
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**:
-
- .. code-block:: http
-
- PUT /db/_security HTTP/1.1
- Accept: application/json
- Content-Length: 121
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "admins": {
- "names": [
- "superuser"
- ],
- "roles": [
- "admins"
- ]
- },
- "members": {
- "names": [
- "user1",
- "user2"
- ],
- "roles": [
- "developers"
- ]
- }
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Tue, 13 Aug 2013 11:26:28 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "ok": true
- }
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/database/temp-views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst
deleted file mode 100644
index 2888e3a..0000000
--- a/share/doc/src/api/database/temp-views.rst
+++ /dev/null
@@ -1,79 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/db/temp_view:
-
-``/db/_temp_view``
-==================
-
-.. http:post:: /{db}/_temp_view
- :synopsis: Executes a given view function for all documents and returns the result
-
- Creates (and executes) a temporary view based on the view function
- supplied in the JSON request.
-
- The arguments also available to standard view requests also apply to
- temporary views, but the execution of the view may take some time as it
- relies on being executed at the time of the request. This means that for
- every temporary view you create, the entire database will be read
- one doc at a time and passed through the view function.
-
- This should not be used on production CouchDB instances, and is purely a
- convenience function for quick development testing. You should use a
- defined view if you want to achieve the best performance.
-
- See :ref:`api/ddoc/view` for more info.
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_temp_view?group=true HTTP/1.1
- Accept: application/json
- Content-Length: 92
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "map": "function(doc) { if (doc.value) { emit(doc.value, null); } }",
- "reduce": "_count"
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Tue, 13 Aug 2013 12:28:12 GMT
- ETag: "AU33B3N7S9K4SAZSFA048HVB4"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
-
- {
- "rows": [
- {
- "key": -10,
- "value": 1
- },
- {
- "key": 10,
- "value": 2
- },
- {
- "key": 15,
- "value": 1
- }
- ]
- }