Update base DDoc API referece.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/9947e588 Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9947e588 Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9947e588 Branch: refs/heads/1781-reorganize-and-improve-docs Commit: 9947e5888a58bc558bbd71296f594e898a2ffac5 Parents: e475c72 Author: Alexander Shorin <[email protected]> Authored: Wed Aug 21 15:21:40 2013 +0400 Committer: Alexander Shorin <[email protected]> Committed: Fri Sep 27 21:59:45 2013 +0400 ---------------------------------------------------------------------- share/doc/src/api/ddoc/common.rst | 524 ++++++++---------------------- share/doc/src/query-server/index.rst | 1 + 2 files changed, 139 insertions(+), 386 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/9947e588/share/doc/src/api/ddoc/common.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst index c5ba9ce..0d6ec17 100644 --- a/share/doc/src/api/ddoc/common.rst +++ b/share/doc/src/api/ddoc/common.rst @@ -11,454 +11,206 @@ .. the License. -.. _api/ddoc.get: +.. _api/ddoc: -``GET /db/_design/design-doc`` -============================== +``/db/_design/design-doc`` +========================== -* **Method**: ``GET /db/_design/design-doc`` -* **Request**: None -* **Response**: JSON of the existing design document -* **Admin Privileges Required**: no -* **Query Arguments**: +.. http:head:: /{db}/_design/{ddocname} - * **Argument**: rev + Returns the HTTP Headers containing a minimal amount of information + about the specified design document. - * **Description**: Specify the revision to return - * **Optional**: yes - * **Type**: string + .. seealso:: - * **Argument**: revs + :http:head:`/{db}/{docid}` - * **Description**: Return a list of the revisions for the document - * **Optional**: yes - * **Type**: boolean - * **Supported Values**: - * **true**: Includes the revisions +.. http:get:: /{db}/_design/{ddocname} - * **Argument**: revs_info + Returns design document with the specified design document` from the specified + database. Unless you request a specific revision, the latest revision of the + document will always be returned. - * **Description**: Return a list of detailed revision information for the - document - * **Optional**: yes - * **Type**: boolean - * **Supported Values**: + .. seealso:: - * **true**: Includes the revisions + :http:get:`/{db}/{docid}` -Returns the specified design document, ``design-doc`` from the specified -``db``. For example, to retrieve the design document ``recipes`` you -would send the following request: -.. code-block:: http +.. http:put:: /{db}/_design/{ddocname} - GET http://couchdb:5984/recipes/_design/recipes - Content-Type: application/json - -The returned string will be the JSON of the design document: - -.. code-block:: javascript - - { - "_id" : "_design/recipes", - "_rev" : "5-39f56a392b86bbee57e2138921346406" - "language" : "javascript", - "views" : { - "by_recipe" : { - "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }" - }, - }, - } - -A list of the revisions can be obtained by using the ``revs`` query -argument, or an extended list of revisions using the ``revs_info`` query -argument. This operates in the same way as for other documents. Fur -further examples, see :http:get:`/{db}/{docid}`. - -.. _api/ddoc.put: - -``PUT /db/_design/design-doc`` -============================== - -* **Method**: ``PUT /db/_design/design-doc`` -* **Request**: JSON of the design document -* **Response**: JSON status -* **Admin Privileges Required**: no - -Upload the specified design document, ``design-doc``, to the specified -database. The design document should follow the definition of a design -document, as summarised in the following table. - -* **_id**: Design Document ID -* **_rev**: Design Document Revision -* **views**: View - - * **viewname**: View Definition - - * **map**: Map Function for View - * **reduce (optional)**: Reduce Function for View - -For more information on writing views, see :ref:`api/ddoc/view`. - -.. _api/ddoc.delete: - -``DELETE /db/_design/design-doc`` -================================= - -* **Method**: ``DELETE /db/_design/design-doc`` -* **Request**: None -* **Response**: JSON of deleted design document -* **Admin Privileges Required**: no -* **Query Arguments**: - - * **Argument**: rev - - * **Description**: Current revision of the document for validation - * **Optional**: yes - * **Type**: string - -* **HTTP Headers** - - * **Header**: ``If-Match`` - - * **Description**: Current revision of the document for validation - * **Optional**: yes - -* **Return Codes**: - - * **409**: - Supplied revision is incorrect or missing - -Delete an existing design document. Deleting a design document also -deletes all of the associated view indexes, and recovers the -corresponding space on disk for the indexes in question. - -To delete, you must specify the current revision of the design document -using the ``rev`` query argument. - -For example: - -.. code-block:: http - - DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8 - Content-Type: application/json - -The response contains the delete document ID and revision: - -.. code-block:: javascript - - { - "id" : "recipe/_design/recipes" - "ok" : true, - "rev" : "3-7a05370bff53186cb5d403f861aca154", - } - -.. _api/ddoc.copy: - -``COPY /db/_design/design-doc`` -=============================== - -* **Method**: ``COPY /db/_design/design-doc`` -* **Request**: None -* **Response**: JSON of the new document and revision -* **Admin Privileges Required**: no -* **Query Arguments**: - - * **Argument**: rev - - * **Description**: Revision to copy from - * **Optional**: yes - * **Type**: string - -* **HTTP Headers** - - * **Header**: ``Destination`` - - * **Description**: Destination document (and optional revision) - * **Optional**: no - -The ``COPY`` command (non-standard HTTP) copies an existing design -document to a new or existing document. - -The source design document is specified on the request line, with the -``Destination`` HTTP Header of the request specifying the target -document. + The :http:method:`PUT` method creates a new named design document, or creates + a new revision of the existing design document. -Copying a Design Document -------------------------- + The design documents have some agreement upon their fields and structure. + Currently it is the next: -To copy the latest version of a design document to a new document you -specify the base document and target document: + * **language** (*string*): Defines :ref:`Query Server <query-server>` + :ref:`key <config/query_servers>` to process design document functions + * **options** (*object*): View's default options + * **filters** (*object*): :ref:`Filter functions <filterfun>` definition + * **lists** (*object*): :ref:`List functions <listfun>` definition + * **rewrites** (*array*): Rewrite rules definition + * **shows** (*object*): :ref:`Show functions <showfun>` definition + * **updates** (*object*): :ref:`Update functions <updatefun>` definition + * **validate_doc_update** (*string*): :ref:`Validate document update <vdufun>` + function source + * **views** (*object*): :ref:`View functions <viewfun>` definition. -.. code-block:: http + Note, that for ``filters``, ``lists``, ``shows`` and ``updates`` fields + objects are mapping of function name to string function source code. + For ``views`` mapping is the same except that values are objects with ``map`` + and ``reduce`` (optional) keys which also contains functions source code. - COPY http://couchdb:5984/recipes/_design/recipes - Content-Type: application/json - Destination: /recipes/_design/recipelist - -The above request copies the design document ``recipes`` to the new -design document ``recipelist``. The response is the ID and revision of -the new document. - -.. code-block:: javascript - - { - "id" : "recipes/_design/recipelist" - "rev" : "1-9c65296036141e575d32ba9c034dd3ee", - } + .. seealso:: -.. note:: - Copying a design document does automatically reconstruct the view - indexes. These will be recreated, as with other views, the first - time the new view is accessed. + :http:put:`/{db}/{docid}` -Copying from a Specific Revision --------------------------------- -To copy *from* a specific version, use the ``rev`` argument to the query -string: +.. http:delete:: /{db}/_design/{ddocname} -.. code-block:: http + Deletes the specified document from the database. You must supply the + current (latest) revision, either by using the ``rev`` parameter to + specify the revision. - COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5 - Content-Type: application/json - Destination: recipes/_design/recipelist - -The new design document will be created using the specified revision of -the source document. + .. seealso:: -Copying to an Existing Design Document --------------------------------------- + :http:delete:`/{db}/{docid}` -To copy to an existing document, you must specify the current revision -string for the target document, using the ``rev`` parameter to the -``Destination`` HTTP Header string. For example: +.. http:copy:: /{db}/_design/{ddocname} -.. code-block:: http + The :http:method:`COPY` (which is non-standard HTTP) copies an existing + design document to a new or existing one. - COPY http://couchdb:5984/recipes/_design/recipes - Content-Type: application/json - Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee + .. note:: + Copying a design document does automatically reconstruct the view + indexes. These will be recreated, as with other views, the first + time the new view is accessed. -The return value will be the new revision of the copied document: + .. seealso:: -.. code-block:: javascript + :http:copy:`/{db}/{docid}` - { - "id" : "recipes/_design/recipes" - "rev" : "2-55b6a1b251902a2c249b667dab1c6692", - } .. _api/ddoc/attachment: -.. _api/ddoc/attachment.get: - -``GET /db/_design/design-doc/attachment`` -========================================= - -* **Method**: ``GET /db/_design/design-doc/attachment`` -* **Request**: None -* **Response**: Returns the attachment data -* **Admin Privileges Required**: no - -Returns the file attachment ``attachment`` associated with the design -document ``/_design_/design-doc``. The raw data of the associated -attachment is returned (just as if you were accessing a static file. The -returned HTTP ``Content-type`` will be the same as the content type set -when the document attachment was submitted into the database. - -.. _api/ddoc/attachment.put: - -``PUT /db/_design/design-doc/attachment`` -========================================= - -* **Method**: ``PUT /db/_design/design-doc/attachment`` -* **Request**: Raw document data -* **Response**: JSON document status -* **Admin Privileges Required**: no -* **Query Arguments**: - - * **Argument**: rev - - * **Description**: Current document revision - * **Optional**: no - * **Type**: string - -* **HTTP Headers** - - * **Header**: ``Content-Length`` - - * **Description**: Length (bytes) of the attachment being uploaded - * **Optional**: no - - * **Header**: ``Content-Type`` - * **Description**: MIME type for the uploaded attachment - * **Optional**: no +``/db/_design/design-doc/attachment`` +===================================== - * **Header**: ``If-Match`` +.. http:head:: /{db}/_design/{ddocname}/{attname} - * **Description**: Current revision of the document for validation - * **Optional**: yes + Returns the HTTP headers containing a minimal amount of information + about the specified attachment. -Upload the supplied content as an attachment to the specified design -document (``/_design/design-doc``). The ``attachment`` name provided -must be a URL encoded string. You must also supply either the ``rev`` -query argument or the ``If-Match`` HTTP header for validation, and the -HTTP headers (to set the attachment content type). The content type is -used when the attachment is requested as the corresponding content-type -in the returned document header. + .. seealso:: -For example, you could upload a simple text document using the following -request: + :http:head:`/{db}/{docid}/{attname}` -.. code-block:: http +.. http:get:: /{db}/_design/{ddocname}/{attname} - PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e - Content-Length: 39 - Content-Type: text/plain + Returns the file attachment associated with the design document. + The raw data of the associated attachment is returned (just as if you were + accessing a static file. - div.recipetitle { - font-weight: bold; - } - -Or by using the ``If-Match`` HTTP header: - -.. code-block:: http - - PUT http://couchdb:5984/recipes/FishStew/basic - If-Match: 7-f7114d4d81124b223283f3e89eee043e - Content-Length: 39 - Content-Type: text/plain - - div.recipetitle { - font-weight: bold; - } - -The returned JSON contains the new document information: - -.. code-block:: javascript - - { - "id" : "_design/recipes" - "ok" : true, - "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5", - } - -.. note:: - Uploading an attachment updates the corresponding document revision. - Revisions are tracked for the parent document, not individual attachments. + .. seealso:: -.. _api/ddoc/attachment.delete: + :http:get:`/{db}/{docid}/{attname}` -``DELETE /db/_design/design-doc/attachment`` -============================================ +.. http:put:: /{db}/_design/{ddocname}/{attname} -* **Method**: ``DELETE /db/_design/design-doc/attachment`` -* **Request**: None -* **Response**: JSON status -* **Admin Privileges Required**: no -* **Query Arguments**: + Uploads the supplied content as an attachment to the specified design + document. The attachment name provided must be a URL encoded string. - * **Argument**: rev + .. seealso:: - * **Description**: Current document revision - * **Optional**: no - * **Type**: string + :http:put:`/{db}/{docid}/{attname}` -* **HTTP Headers** +.. http:delete:: /{db}/_design/{ddocname}/{attname} - * **Header**: ``If-Match`` + Deletes the attachment of the specified design document. - * **Description**: Current revision of the document for validation - * **Optional**: yes + .. seealso:: -* **Return Codes**: + :http:delete:`/{db}/{docid}/{attname}` - * **200**: - Attachment deleted successfully - * **409**: - Supplied revision is incorrect or missing -Deletes the attachment ``attachment`` to the specified -``_design/design-doc``. You must supply the ``rev`` argument with the -current revision to delete the attachment. - -For example to delete the attachment ``view.css`` from the design -document ``recipes``: - -.. code-block:: http +.. _api/ddoc/info: - DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a +``/db/_design/design-doc/_info`` +================================ -The returned JSON contains the updated revision information for the -parent document: +.. http:get:: /{db}/_design/{ddocname}/_info -.. code-block:: javascript + Obtains information about the specified design document, including the index, + index size and current status of the design document and associated + index information. - { - "id" : "_design/recipes" - "ok" : true, - "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c", - } + :param db: Database name + :param ddocname: Design document name + :<header Accept: - :mimetype:`application/json` + - :mimetype:`text/plain` + :>header Content-Type: - :mimetype:`application/json` + - :mimetype:`text/plain; charset=utf-8` + :>json string name: Design document name + :>json object view_index: :ref:`api/ddoc/view_index_info` + :code 200: Request completed successfully + **Request**: -.. _api/ddoc/info: -.. _api/ddoc/info.get: + .. code-block:: http -``GET /db/_design/design-doc/_info`` -==================================== + GET /recipes/_design/recipe/_info HTTP/1.1 + Accept: application/json + Host: localhost:5984 -* **Method**: ``GET /db/_design/design-doc/_info`` -* **Request**: None -* **Response**: JSON of the design document information -* **Admin Privileges Required**: no + **Response**: -Obtains information about a given design document, including the index, -index size and current status of the design document and associated -index information. + .. code-block:: http -For example, to get the information for the ``recipes`` design document: - -.. code-block:: http - - GET http://couchdb:5984/recipes/_design/recipes/_info + HTTP/1.1 200 OK + Cache-Control: must-revalidate + Content-Length: 263 Content-Type: application/json - -This returns the following JSON structure: - -.. code-block:: javascript + Date: Sat, 17 Aug 2013 12:54:17 GMT + Server: CouchDB/1.4.0 (Erlang OTP/R16B) { - "name" : "recipes" - "view_index" : { - "compact_running" : false, - "updater_running" : false, - "language" : "javascript", - "purge_seq" : 10, - "waiting_commit" : false, - "waiting_clients" : 0, - "signature" : "fc65594ee76087a3b8c726caf5b40687", - "update_seq" : 375031, - "disk_size" : 16491 - }, + "name": "recipe", + "view_index": { + "compact_running": false, + "data_size": 926691, + "disk_size": 1982704, + "language": "python", + "purge_seq": 0, + "signature": "a59a1bb13fdf8a8a584bc477919c97ac", + "update_seq": 12397, + "updater_running": false, + "waiting_clients": 0, + "waiting_commit": false + } } -The individual fields in the returned JSON structure are detailed below: - -* **name**: Name/ID of Design Document -* **view_index**: View Index - - * **compact_running**: Indicates whether a compaction routine is currently - running on the view - * **disk_size**: Size in bytes of the view as stored on disk - * **language**: Language for the defined views - * **purge_seq**: The purge sequence that has been processed - * **signature**: MD5 signature of the views for the design document - * **update_seq**: The update sequence of the corresponding database that - has been indexed - * **updater_running**: Indicates if the view is currently being updated - * **waiting_clients**: Number of clients waiting on views from this design - document - * **waiting_commit**: Indicates if there are outstanding commits to the - underlying database that need to processed + +.. _api/ddoc/view_index_info: + +View Index Information +---------------------- + +The response from :http:get:`/{db}/_design/{ddocname}/_info` contains +``view_index`` (*object*) field with the next structure: + +* **compact_running** (*boolean*): Indicates whether a compaction routine + is currently running on the view +* **data_size** (*number*): Actual size in bytes of the view +* **disk_size** (*number*): Size in bytes of the view as stored on disk +* **language** (*string*): Language for the defined views +* **purge_seq** (*number*): The purge sequence that has been processed +* **signature** (*string*): MD5 signature of the views for the design document +* **update_seq** (*number*): The update sequence of the corresponding database + that has been indexed +* **updater_running** (*boolean*): Indicates if the view is currently + being updated +* **waiting_clients** (*number*): Number of clients waiting on views from + this design document +* **waiting_commit** (*boolean*): Indicates if there are outstanding commits + to the underlying database that need to processed http://git-wip-us.apache.org/repos/asf/couchdb/blob/9947e588/share/doc/src/query-server/index.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/query-server/index.rst b/share/doc/src/query-server/index.rst index b16e0ac..835ba1b 100644 --- a/share/doc/src/query-server/index.rst +++ b/share/doc/src/query-server/index.rst @@ -10,6 +10,7 @@ .. License for the specific language governing permissions and limitations under .. the License. +.. _query-server: ============ Query Server
