CouchDB API Server Configuration Methods

Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 38236 invoked by uid 99); 12 Dec 2012 20:33:59 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 12 Dec 2012 20:33:59 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 4AB0881B9A9; Wed, 12 Dec 2012 20:33:59 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: dch@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [10/34] Transmogrify Couchbase XML to .rst and support Sphinx Message-Id: <20121212203359.4AB0881B9A9@tyr.zones.apache.org> Date: Wed, 12 Dec 2012 20:33:59 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/couchdb/blob/de115c3a/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml deleted file mode 100644 index aa1ac27..0000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-config-metasrc.xml +++ /dev/null @@ -1,359 +0,0 @@ - - -%every.entities; -]> - - - CouchDB API Server Configuration Methods - - - The CouchDB API Server Configuration Methods provide an interface to - query and update the various configuration values within a running - CouchDB instance. - - - - A list of the available methods and URL paths are provided below: - - - - Configuration API Calls - - - - - - - - - - - - - - -

- - <literal>GET /_config</literal> - - - - - - - - - - - - - - - - - Returns the entire CouchDB server configuration as a JSON - structure. The structure is organized by different configuration - sections, with individual values. - - - - For example, to get the configuration for a server: - - - -GET http://couchdb:5984/_config -Accept: application/json - - - - The response is the JSON structure: - - - ->}", - "_config" : "{couch_httpd_misc_handlers, handle_config_req}", - "_utils" : "{couch_httpd_misc_handlers, handle_utils_dir_req, \"/usr/share/couchdb/www\"}", - "_active_tasks" : "{couch_httpd_misc_handlers, handle_task_status_req}", - "_session" : "{couch_httpd_auth, handle_session_req}", - "_log" : "{couch_httpd_misc_handlers, handle_log_req}", - "favicon.ico" : "{couch_httpd_misc_handlers, handle_favicon_req, \"/usr/share/couchdb/www\"}", - "_all_dbs" : "{couch_httpd_misc_handlers, handle_all_dbs_req}", - "_oauth" : "{couch_httpd_oauth, handle_oauth_req}", - "_restart" : "{couch_httpd_misc_handlers, handle_restart_req}", - "_uuids" : "{couch_httpd_misc_handlers, handle_uuids_req}", - "_stats" : "{couch_httpd_stats_handlers, handle_stats_req}" - } -}]]> - - -

- -

- - <literal>GET /_config/section</literal> - - - - - - - - - - - - - - - - - Gets the configuration structure for a single section. For - example, to retrieve the CouchDB configuration section values: - - - -GET http://couchdb:5984/_config/couchdb -Accept: application/json - - - - The returned JSON contains just the configuration values for this - section: - - - -{ - "os_process_timeout" : "5000", - "max_attachment_chunk_size" : "4294967296", - "max_document_size" : "4294967296", - "uri_file" : "/var/lib/couchdb/couch.uri", - "max_dbs_open" : "100", - "view_index_dir" : "/var/lib/couchdb", - "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib", - "database_dir" : "/var/lib/couchdb", - "delayed_commits" : "true" -} - - -

- -

- - <literal>GET /_config/section/key</literal> - - - - - - - - - - - - - - - - - Gets a single configuration value from within a specific - configuration section. For example, to obtain the current log - level: - - - -GET http://couchdb:5984/_config/log/level -Accept: application/json - - - - Returns the string of the log level: - - - -"info" - - - - - The returned value will be the JSON of the value, which may be a - string or numeric value, or an array or object. Some client - environments may not parse simple strings or numeric values as - valid JSON. - - - -

- -

- - <literal>PUT /_config/section/key</literal> - - - - - - - - - - - - - - - - - Updates a configuration value. The new value should be supplied in - the request body in the corresponding JSON format. For example, if - you are setting a string value, you must supply a valid JSON - string. - - - - For example, to set the function used to generate UUIDs by the - GET /_uuids API call to use the - utc_random generator: - - - -PUT http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json - -"utc_random" - - - - The return value will be empty, with the response code indicating - the success or failure of the configuration setting. - - -

- -

- - <literal>DELETE /_config/section/key</literal> - - - - - - - - - - - - - - - - - Deletes a configuration value. The returned JSON will be the value - of the configuration parameter before it was deleted. For example, - to delete the UUID parameter: - - - -DELETE http://couchdb:5984/_config/uuids/algorithm -Content-Type: application/json - - - - The returned value is the last configured UUID function: - - - -"random" - - -

- - http://git-wip-us.apache.org/repos/asf/couchdb/blob/de115c3a/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml deleted file mode 100644 index 0b3084a..0000000 --- a/share/docs/couchdb-manual-1.1/couchdb-api-db-metasrc.xml +++ /dev/null @@ -1,1828 +0,0 @@ - - -%every.entities; -]> - - - CouchDB API Server Database Methods - - - The Database methods provide an interface to an entire database - withing CouchDB. These are database, rather than document, level - requests. - - - - A list of the available methods and URL paths are provided below: - - - - Database API Calls - - - - - - - - - - - - - - - - For all the database methods, 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: - - - -GET /recipes - - - - For clarity, the form below is used in the URL paths: - - - -GET /db - - - - Where db is the name of any database. - - -

- - <literal>GET /db</literal> - - - - - - - - - - - - - - - - - Gets information about the specified database. For example, to - retrieve the information for the database - recipe: - - - -GET http://couchdb:5984/recipes -Accept: application/json - - - - The JSON response contains meta information about the database. A - sample of the JSON returned for an empty database is provided - below: - - - -{ - "compact_running" : false, - "committed_update_seq" : 375048, - "disk_format_version" : 5, - "disk_size" : 33153123, - "doc_count" : 18386, - "doc_del_count" : 0, - "db_name" : "recipes", - "instance_start_time" : "1290700340925570", - "purge_seq" : 10, - "update_seq" : 375048 -} - - - - The elements of the returned structure are shown in the table - below: - - - - - - - - - - - - - - -

- -

- - <literal>PUT /db</literal> - - - - - - - - - - - - - - - - - Creates a new database. The database name must be composed of one - or more of the following characters: - - - - - - - Lowercase characters (a-z) - - - - - - Name must begin with a lowercase letter - - - - - - Digits (0-9) - - - - - - Any of the characters _, - $, (, - ), +, - -, and /. - - - - - - - Trying to create a database that does not meet these requirements - will return an error quoting these restrictions. - - - - To create the database recipes: - - - -PUT http://couchdb:5984/recipes -Content-Type: application/json - - - - The returned content contains the JSON status: - - - -{ - "ok" : true -} - - - - Anything should be treated as an error, and the problem should be - taken form the HTTP response code. - - -

- -

- - <literal>DELETE /db</literal> - - - - - - - - - - - - - - - - - Deletes the specified database, and all the documents and - attachments contained within it. - - - - To delete the database recipes you would send - the request: - - - -DELETE http://couchdb:5984/recipes -Content-Type: application/json - - - - If successful, the returned JSON will indicate success - - - -{ - "ok" : true -} - - -

- -

- - <literal>GET /db/_changes</literal> - - - - - - - - - - - - - - - - - Obtains a list of the changes made to the database. This can be - used to monitor for update and modifications to the database for - post processing or synchronization. There are three different - types of supported changes feeds, poll, longpoll, and continuous. - All requests are poll requests by default. You can select any feed - type explicitly using the feed query argument. - - - - - - - - Poll - - - - With polling you can request the changes that have occured - since a specific sequence number. This returns the JSON - structure containing the changed document information. When - you perform a poll change request, only the changes since - the specific sequence number are returned. For example, the - query - - - -DELETE http://couchdb:5984/recipes/_changes -Content-Type: application/json - - - - Will get all of the changes in the database. You can request - a starting point using the since query - argument and specifying the sequence number. You will need - to record the latest sequence number in your client and then - use this when making another request as the new value to the - since parameter. - - - - - - Longpoll - - - - With long polling the request to the server will remain open - until a change is made on the database, when the changes - will be reported, and then the connection will close. The - long poll is useful when you want to monitor for changes for - a specific purpose without wanting to monitoring - continuously for changes. - - - - 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 open. - - - - - - Continuous - - - - Continuous sends all new changes back to the client - immediately, without closing the connection. In continuous - mode the format of the changes is slightly different to - accommodate the continuous nature while ensuring that the - JSON output is still valid for each change notification. - - - - 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 changesand updates. - - - - - - - - The return structure for normal and - longpoll modes is a JSON array of changes - objects, and the last update sequence number. The structure is - described in the following table. - - - - - - - - - - - - - - - - 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. - - - - You can also request the full contents of each document change - (instead of just the change notification) by using the - include_docs parameter. - - -

- - 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 filter name. For example: - - - -GET /db/_changes?filter=design_doc/filtername - - - - The _changes feed can be used to watch - changes to specific document ID's or the list of - _design documents in a database. If the - filters parameter is set to - _doc_ids a list of doc IDs can be passed in - the parameter as a JSON array. - - - - For more information, see - . - - -

- -

- - <literal>POST /db/_compact</literal> - - - - - - - - - - - - - - - - - Request compaction of the specified database. Compaction - compresses the disk database file by performing the following - operations: - - - - - - - Writes a new version of the database file, removing any unused - sections from the new version during write. Because a new file - is temporary created for this purpose, you will need twice the - current storage space of the specified database in order for - the compaction routine to complete. - - - - - - Removes old revisions of documents from the database, up to - the per-database limit specified by the - _revs_limit database parameter. See - . - - - - - - - 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 - . - - - - You can also obtain a list of running processes to determine - whether compaction is currently running. See - . - - -

- -

- - <literal>POST /db/_compact/design-doc</literal> - - - - - - - - - - - - - - - - - Compacts the view indexes associated with the specified design - document. You can use this in place of the full database - compaction if you know a specific set of view indexes have been - affected by a recent database change. - - - - For example, to compact the views associated with the - recipes design document: - - - -POST http://couchdb:5984/recipes/_compact/recipes -Content-Type: application/json - - - - CouchDB will immediately return with a status indicating that the - compaction request has been received (HTTP status code 202): - - - -{ - "ok" : true -} - - -

- -

- - <literal>POST /db/_view_cleanup</literal> - - - - - - - - - - - - - - - - - Cleans up the cached view output on disk for a given view. For - example: - - - -POST http://couchdb:5984/recipes/_view_cleanup -Content-Type: application/json - - - - If the request is successful, a basic status message us returned: - - - -{ - "ok" : true -} - - -

- -

- - <literal>POST /db/_ensure_full_commit</literal> - - - - - - - - - - - - - - - - - Commits any recent changes to the specified database to disk. You - should call this if you want to ensure that recent changes have - been written. For example, to commit all the changes to disk for - the database recipes you would use: - - - -POST http://couchdb:5984/recipes/_ensure_full_commit -Content-Type: application/json - - - - This returns a status message, containing the success message and - the timestamp for when the CouchDB instance was started: - - - -{ - "ok" : true, - "instance_start_time" : "1288186189373361" -} - - - - -

- -

- - <literal>POST /db/_bulk_docs</literal> - - - - - - - - - - - - - - - - - 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 and . - When creating new documents the document ID is optional. For - updating existing documents, you must provide the document ID, - revision information, and new document values. - - - - For both inserts and updates the basic structure of the JSON is - the same: - - - - - - - - - - - - - - -

- - Inserting Documents in Bulk - - - 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. Using this method you can either include a - document ID, or allow the document ID to be automatically - generated. - - - - For example, the following inserts three new documents, two with - the supplied document IDs, and one which will have a document ID - generated: - - - -{ - "docs" : [ - { - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - }, - { - "_id" : "LambStew", - "servings" : 6, - "subtitle" : "Delicious with scone topping", - "title" : "Lamb Stew" - }, - { - "servings" : 8, - "subtitle" : "Delicious with suet dumplings", - "title" : "Beef Stew" - }, - ] -} - - - - The return type from a bulk insertion will be 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: - - - -POST http://couchdb:5984/recipes/_bulk_docs -Content-Type: application/json - -[ - { - "id" : "FishStew", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee", - }, - { - "id" : "LambStew", - "rev" : "1-34c318924a8f327223eed702ddfdc66d", - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "1-857c7cbeb6c8dd1dd34a0c73e8da3c44", - } -] - - - - The content and structure of the returned JSON will depend on - the transaction semantics being used for the bulk update; see - - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - . - - -

- -

- - 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: - - - -POST http://couchdb:5984/recipes/_bulk_docs -Content-Type: application/json - -{ - "docs" : [ - { - "_id" : "FishStew", - "_rev" : "1-9c65296036141e575d32ba9c034dd3ee", - "servings" : 4, - "subtitle" : "Delicious with freshly baked bread", - "title" : "Fish Stew" - }, - { - "_id" : "LambStew", - "_rev" : "1-34c318924a8f327223eed702ddfdc66d", - "servings" : 6, - "subtitle" : "Serve with a wholemeal scone topping", - "title" : "Lamb Stew" - }, - { - "_id" : "7f7638c86173eb440b8890839ff35433" - "_rev" : "1-857c7cbeb6c8dd1dd34a0c73e8da3c44", - "servings" : 8, - "subtitle" : "Hand-made dumplings make a great accompaniment", - "title" : "Beef Stew" - } - ] -} - - - - The return structure is the JSON of the updated documents, with - the new revision and ID information: - - - -[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -] - - - - You can optionally delete documents during a bulk update by - adding the _deleted field with a value of - true to each docment ID/revision combination - within the submitted JSON structure. - - - - The return type from a bulk insertion will be 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 - - for more information. Conflicts and validation errors when - updating documents in bulk must be handled separately; see - . - - -

- -

- - 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: - - - -[ - { - "id" : "FishStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "LambStew", - "error" : "conflict", - "reason" : "Document update conflict." - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "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: - - - -[ - { - "id" : "FishStew", - "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1" - }, - { - "id" : "LambStew", - "rev" : "2-0786321986194c92dd3b57dfbfc741ce" - }, - { - "id" : "7f7638c86173eb440b8890839ff35433", - "rev" : "2-bdd3bf3563bee516b96885a66c743f8e" - } -] - - - - 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 in the table below: - - - - Conflicts on Bulk Inserts - - - - - Transaction Mode - - - Transaction - - - Cause - - - Resolution - - - - - - - Non-atomic - - - Insert - - - Requested document ID already exists - - - Resubmit with different document ID, or update the - existing document - - - - - Non-atomic - - - Update - - - Revision missing or incorrect - - - Resubmit with correct revision - - - - - All-or-nothing - - - Insert - - - Additional revision inserted - - - Resolve conflicted revisions - - - - - All-or-nothing - - - Update - - - Additional revision inserted - - - 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. - - -

- -

- - 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. - - - - The exact structure of the returned information is shown in - . - - - - - - - - - - - - - - - - When a document (or document revision) is not correctly comitted - 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 validation routine includes the - following: - - - throw({forbidden: 'invalid recipe ingredient'}); - - - The error returned will be: - - - -{ - "id" : "7f7638c86173eb440b8890839ff35433", - "error" : "forbidden", - "reason" : "invalid recipe ingredient" -} - - - - For more information, see - . - - - - - -

- -

- - <literal>POST /db/_temp_view</literal> - - - - - - - - - - - - - - - - - Creates (and executes) a temporary view based on the view function - supplied in the JSON request. For example: - - - -POST http://couchdb:5984/recipes/_temp_view -Content-Type: application/json - -{ - "map" : "function(doc) { if (doc.value > 9995) { emit(null, doc.value); } }" -} - - - - The resulting JSON response is the result from the execution of - the temporary view: - - - -{ - "total_rows" : 3, - "rows" : [ - { - "value" : 9998.41913029012, - "id" : "05361cc6aa42033878acc1bacb1f39c2", - "key" : null - }, - { - "value" : 9998.94149934853, - "id" : "1f443f471e5929dd7b252417625ed170", - "key" : null - }, - { - "value" : 9998.01511339154, - "id" : "1f443f471e5929dd7b252417629c102b", - "key" : null - } - ], - "offset" : 0 -} - - - - 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. In - addition to the time taken, they are also computationally very - expensive to produce. You should use a defined view if you want to - achieve the best performance. - - - - For more information, see - . - - -

- -

- - <literal>POST /db/_purge</literal> - - - - - - - - - - - - - - - - - A database purge permanently removes the references to deleted - documents from the database. Deleting a document within CouchDB - does not actually remove the documen from the database, instead, - the document is marked as a deleted (and a new revision is - created). This is to ensure that deleted documents are 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. - - - - The purge operation removes the refernces 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. - - - - - Purging documents does not remove the space used by them on - disk. To reclaim disk space, you should run a database compact - (see , and - compact views (see - ). - - - - - To perform a purge operation you must send a request including the - JSON of the document IDs that you want to purge. For example: - - - -POST http://couchdb:5984/recipes/_purge -Content-Type: application/json - -{ - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] -} - - - - 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. - - - -{ - "purged" : { - "FishStew" : [ - "17-b3eb5ac6fbaef4428d712e66483dcb79" - ] - }, - "purge_seq" : 11 -} - - -

- - 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. - - -

- -

- - <literal>GET /db/_all_docs</literal> - - - - - - - - - - - - - - - - - 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, and the - list documents and basic contents, consisting the ID, revision and - key. The key is generated from the document ID. - - - - - - - - - - - - - - - - By default the information returned contains only the document ID - and revision. For example, the request: - - - -GET http://couchdb:5984/recipes/_all_docs -Accept: application/json - - - - Returns the following structure: - - - -{ - "total_rows" : 18386, - "rows" : [ - { - "value" : { - "rev" : "1-bc0d5aed1e339b1cc1f29578f3220a45" - }, - "id" : "Aberffrawcake", - "key" : "Aberffrawcake" - }, - { - "value" : { - "rev" : "3-68a20c89a5e70357c20148f8e82ca331" - }, - "id" : "Adukiandorangecasserole-microwave", - "key" : "Adukiandorangecasserole-microwave" - }, - { - "value" : { - "rev" : "3-9b2851ed9b6f655cc4eb087808406c60" - }, - "id" : "Aioli-garlicmayonnaise", - "key" : "Aioli-garlicmayonnaise" - }, - ... - ], - "offset" : 0 -} - - - - The information is returned in the form of a temporary view of all - the database documents, with the returned key consisting of the ID - of the document. The remainder of the interface is therefore - identical to the View query arguments and their behavior. - - - - -

- -

- - <literal>POST /db/_all_docs</literal> - - - - - - - - - - - - - - - - - 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 - requests. - - - - The request body should contain a list of the keys to be returned - as an array to a keys object. For example: - - - -POST http://couchdb:5984/recipes/_all_docs -User-Agent: MyApp/0.1 libwww-perl/5.837 - -{ - "keys" : [ - "Zingylemontart", - "Yogurtraita" - ] -} - - - - The return JSON is the all documents structure, but with only the - selected keys in the output: - - - -{ - "total_rows" : 2666, - "rows" : [ - { - "value" : { - "rev" : "1-a3544d296de19e6f5b932ea77d886942" - }, - "id" : "Zingylemontart", - "key" : "Zingylemontart" - }, - { - "value" : { - "rev" : "1-91635098bfe7d40197a1b98d7ee085fc" - }, - "id" : "Yogurtraita", - "key" : "Yogurtraita" - } - ], - "offset" : 0 -} - - - - -

- -

- - <literal>POST /db/_missing_revs</literal> - - - - - - - - - - - - - - - -

- -

- - <literal>POST /db/_revs_diff</literal> - - - - - - - - - - - - - - - -

- -

- - <literal>GET /db/_security</literal> - - - - - - - - - - - - - - - - - Gets the current secrity object from the specified database. The - security object consists of two compulsory elements, - admins and readers, which - are used to specify the list of users and/or roles that have admin - and reader rights to the database respectively. Any 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. - - - - To get the existing security object you would send the following - request: - - - -{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -} - - - - - - - - - - - - - - - - - If the security object for a database has never beent set, then - the value returned will be empty. - - - -

- -

- - <literal>PUT /db/_security</literal> - - - - - - - - - - - - - - - - - Sets the security object for the given database.For example, to - set the security object for the recipes - database: - - - -PUT http://couchdb:5984/recipes/_security -Content-Type: application/json - -{ - "admins" : { - "roles" : [], - "names" : [ - "mc", - "slp" - ] - }, - "readers" : { - "roles" : [], - "names" : [ - "tim", - "brian" - ] - } -} - - - If the setting was successful, a JSON status object will be - returned: - - - -{ - "ok" : true -} - - -

- -

- - <literal>GET /db/_revs_limit</literal> - - - - - - - - - - - - - - - - - Gets the current revs_limit (revision limit) - setting. - - - - For example to get the current limit: - - - -GET http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json - - - - The returned information is the current setting as a numerical - scalar: - - - -1000 - - -

- -

- - <literal>PUT /db/_revs_limit</literal> - - - - - - - - - - - - - - - - - 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 by using PUT with - a scalar integer of the limit that you want to set as the request - body. - - - - For example to set the revs limit to 100 for the - recipes database: - - - -PUT http://couchdb:5984/recipes/_revs_limit -Content-Type: application/json - -100 - - - - If the setting was successful, a JSON status object will be - returned: - - - -{ - "ok" : true -} - - -

- -