1
.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
2
.. use this file except in compliance with the License. You may obtain a copy of
5
.. http://www.apache.org/licenses/LICENSE-2.0
7
.. Unless required by applicable law or agreed to in writing, software
8
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
9
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
10
.. License for the specific language governing permissions and limitations under
19
The CouchDB API Server Document methods detail how to create, read,
20
update and delete documents within a database.
22
A list of the available methods and URL paths are provided below:
24
+--------+-------------------------+-------------------------------------------+
25
| Method | Path | Description |
26
+========+=========================+===========================================+
27
| POST | /db | Create a new document |
28
+--------+-------------------------+-------------------------------------------+
29
| GET | /db/doc | Returns the latest revision of the |
31
+--------+-------------------------+-------------------------------------------+
32
| HEAD | /db/doc | Returns bare information in the HTTP |
33
| | | Headers for the document |
34
+--------+-------------------------+-------------------------------------------+
35
| PUT | /db/doc | Inserts a new document, or new version |
36
| | | of an existing document |
37
+--------+-------------------------+-------------------------------------------+
38
| DELETE | /db/doc | Deletes the document |
39
+--------+-------------------------+-------------------------------------------+
40
| COPY | /db/doc | Copies the document |
41
+--------+-------------------------+-------------------------------------------+
42
| GET | /db/doc/attachment | Gets the attachment of a document |
43
+--------+-------------------------+-------------------------------------------+
44
| PUT | /db/doc/attachment | Adds an attachment of a document |
45
+--------+-------------------------+-------------------------------------------+
46
| DELETE | /db/doc/attachment | Deletes an attachment of a document |
47
+--------+-------------------------+-------------------------------------------+
52
* **Method**: ``POST /db``
53
* **Request**: JSON of the new document
54
* **Response**: JSON with the committed document information
55
* **Admin Privileges Required**: no
56
* **Query Arguments**:
60
* **Description**: Allow document store request to be batched with others
63
* **Supported Values**: asd
69
Document has been created successfully
71
Conflict - a document with the specified document ID already exists
73
Create a new document in the specified database, using the supplied JSON
74
document structure. If the JSON structure includes the ``_id`` field,
75
then the document will be created with the specified document ID. If the
76
``_id`` field is not specified, a new unique ID will be generated.
78
For example, you can generate a new document with a generated UUID using
79
the following request:
83
POST http://couchdb:5984/recipes/
84
Content-Type: application/json
88
"subtitle" : "Delicious with fresh bread",
92
The return JSON will specify the automatically generated ID and revision
95
.. code-block:: javascript
98
"id" : "64575eef70ab90a2b8d55fc09e00440d",
100
"rev" : "1-9c65296036141e575d32ba9c034dd3ee"
103
Specifying the Document ID
104
--------------------------
106
The document ID can be specified by including the ``_id`` field in the
107
JSON of the submitted record. The following request will create the same
108
document with the ID ``FishStew``:
112
POST http://couchdb:5984/recipes/
113
Content-Type: application/json
118
"subtitle" : "Delicious with fresh bread",
119
"title" : "Fish Stew"
122
The structure of the submitted document is as shown in the table below:
124
In either case, the returned JSON will specify the document ID, revision
125
ID, and status message:
127
.. code-block:: javascript
132
"rev" : "1-9c65296036141e575d32ba9c034dd3ee"
136
.. _api-batch-writes:
138
UUID generation algorithms
139
--------------------------
141
CouchDB supports a number of different UUID generation algorithms for use
142
in situations where a user-specified UUID does not make sense. These
143
can be set simply by `PUT http://couchdb:5984/_config/uuids/algorithm`.
146
+---------------+---------------------+------------------------------------+
147
| Algorithm | Description | Sample UUID |
148
+===============+=====================+====================================+
149
| random | 128 bits of pure | - 43febce5675468a5467fb5467ce9e6c0 |
150
| | random awesomeness | |
151
+---------------+---------------------+------------------------------------+
152
| sequential | monotonically | - f755c413badf66b22941313f9f001e28 |
153
| | increasing ids with | - f755c413badf66b22941313f9f0024ca |
154
| | random increments | - f755c413badf66b22941313f9f00332c |
155
+---------------+---------------------+------------------------------------+
156
| utc_random | time since start of | - 04cfa405381205204f75100d0241ccc3 |
157
| | epoch, as 14 hex | - 04cfa4059c48e76e7c054bbe033dd8db |
158
| | digits, followed by | - 04cfa405fce10b0df4c08f95e667cd2f |
159
| | 18 random digits. | |
160
+---------------+---------------------+------------------------------------+
161
| utc_id | time since start of | - 04cfa718b00848_i_am_in_yer_couch |
162
| & additional | epoch, as 14 hex | - 04cfa71d377aef_i_am_in_yer_couch |
163
| parameter | digits, followed by | - 04cfa71e0deabd_i_am_in_yer_couch |
164
| | utc_id_suffix. | |
165
+---------------+---------------------+------------------------------------+
167
.. Impact of UUID choices::
168
The choice of UUID has a signficant impact on the layout of the B-tree,
169
prior to compaction. For example, a sequential UUID algorithm during
170
uploading thousands of documents, will avoid the need to rewrite many
171
intermediate B-tree nodes. A random UUID algorithm may require rewriting
172
intermediate nodes on a regular basis, with a corresponding decrease of
173
throughput, and significant wasted space due to the append-only B-tree
174
design. It is generally recommended to set your own UUIDs, or use the
175
sequential algorithm unless you have a specific need and take into account
176
the likely need for compaction to re-balance the B-tree and reclaim wasted
183
You can write documents to the database at a higher rate by using the
184
batch option. This collects document writes together in memory (on a
185
user-by-user basis) before they are committed to disk. This increases
186
the risk of the documents not being stored in the event of a failure,
187
since the documents are not written to disk immediately.
189
To use the batched mode, append the ``batch=ok`` query argument to the
190
URL of the ``PUT`` or ``POST`` request. The CouchDB server will respond
191
with a 202 HTTP response code immediately.
193
Including Attachments
194
---------------------
196
You can include one or more attachments with a given document by
197
incorporating the attachment information within the JSON of the
198
document. This provides a simpler alternative to loading documents with
199
attachments than making a separate call (see :ref:`api-put-attachment`).
201
* **_id** (optional): Document ID
202
* **_rev** (optional): Revision ID (when updating an existing document)
203
* **_attachments** (optional): Document Attachment
205
* **filename**: Attachment information
207
* **content_type**: MIME Content type string
208
* **data**: File attachment content, Base64 encoded
210
The ``filename`` will be the attachment name. For example, when sending
211
the JSON structure below:
213
.. code-block:: javascript
218
"subtitle" : "Delicious with fresh bread",
219
"title" : "Fish Stew"
222
"content-type" : "text/css",
223
"data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=",
229
The attachment ``styling.css`` can be accessed using
230
``/recipes/FishStew/styling.css``. For more information on attachments,
231
see :ref:`api-get-attachment`.
233
The document data embedded in to the structure must be encoded using
241
* **Method**: ``GET /db/doc``
243
* **Response**: Returns the JSON for the document
244
* **Admin Privileges Required**: no
245
* **Query Arguments**:
247
* **Argument**: conflicts
249
* **Description**: Returns the conflict tree for the document.
253
* **Supported Values**:
255
* **true**: Includes the revisions
259
* **Description**: Specify the revision to return
262
* **Supported Values**:
264
* **true**: Includes the revisions
268
* **Description**: Return a list of the revisions for the document
272
* **Argument**: revs_info
274
* **Description**: Return a list of detailed revision information for the
278
* **Supported Values**:
280
* **true**: Includes the revisions
287
The format of the request or revision was invalid
289
The specified document or revision cannot be found, or has been deleted
291
Conflict - a document with the specified document ID already exists
293
Returns the specified ``doc`` from the specified ``db``. For example, to
294
retrieve the document with the id ``FishStew`` you would send the
299
GET http://couchdb:5984/recipes/FishStew
300
Content-Type: application/json
301
Accept: application/json
303
The returned JSON is the JSON of the document, including the document ID
306
.. code-block:: javascript
310
"_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
312
"subtitle" : "Delicious with a green salad",
313
"title" : "Irish Fish Stew"
317
Unless you request a specific revision, the latest revision of the
318
document will always be returned.
323
If the document includes attachments, then the returned structure will
324
contain a summary of the attachments associated with the document, but
325
not the attachment data itself.
327
The JSON for the returned document will include the ``_attachments``
328
field, with one or more attachment definitions. For example:
330
.. code-block:: javascript
335
"subtitle" : "Delicious with fresh bread",
336
"title" : "Fish Stew"
340
"content-type" : "text/css",
346
The format of the returned JSON is shown in the table below:
348
* **_id** (optional): Document ID
349
* **_rev** (optional): Revision ID (when updating an existing document)
350
* **_attachments** (optional): Document Attachment
352
* **filename**: Attachment information
354
* **content_type**: MIME Content type string
355
* **length**: Length (bytes) of the attachment data
356
* **revpos**: Revision where this attachment exists
357
* **stub**: Indicates whether the attachment is a stub
359
Getting a List of Revisions
360
---------------------------
362
You can obtain a list of the revisions for a given document by adding
363
the ``revs=true`` parameter to the request URL. For example:
367
GET http://couchdb:5984/recipes/FishStew?revs=true
368
Accept: application/json
370
The returned JSON structure includes the original document, including a
371
``_revisions`` structure that includes the revision information:
373
.. code-block:: javascript
377
"subtitle" : "Delicious with a green salad",
379
"title" : "Irish Fish Stew",
382
"a1a9b39ee3cc39181b796a69cb48521c",
383
"7c4740b4dcf26683e941d6641c00c39d",
384
"9c65296036141e575d32ba9c034dd3ee"
388
"_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
391
* **_id** (optional): Document ID
392
* **_rev** (optional): Revision ID (when updating an existing document)
393
* **_revisions**: CouchDB Document Revisions
395
* **ids** [array]: Array of valid revision IDs, in reverse order
397
* **start**: Prefix number for the latest revision
399
Obtaining an Extended Revision History
400
--------------------------------------
402
You can get additional information about the revisions for a given
403
document by supplying the ``revs_info`` argument to the query:
407
GET http://couchdb:5984/recipes/FishStew?revs_info=true
408
Accept: application/json
410
This returns extended revision information, including the availability
411
and status of each revision:
413
.. code-block:: javascript
417
"subtitle" : "Delicious with a green salad",
421
"status" : "available",
422
"rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
425
"status" : "available",
426
"rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
429
"status" : "available",
430
"rev" : "1-9c65296036141e575d32ba9c034dd3ee"
433
"title" : "Irish Fish Stew",
434
"_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
437
* **_id** (optional): Document ID
438
* **_rev** (optional): Revision ID (when updating an existing document)
439
* **_revs_info** [array]: CouchDB Document Extended Revision Info
441
* **rev**: Full revision string
442
* **status**: Status of the revision
444
Obtaining a Specific Revision
445
-----------------------------
447
To get a specific revision, use the ``rev`` argument to the request, and
448
specify the full revision number:
452
GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
453
Accept: application/json
455
The specified revision of the document will be returned, including a
456
``_rev`` field specifying the revision that was requested:
458
.. code-block:: javascript
462
"_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
464
"subtitle" : "Delicious with a green salad",
465
"title" : "Fish Stew"
471
* **Method**: ``HEAD /db/doc``
474
* **Admin Privileges Required**: no
475
* **Query Arguments**:
479
* **Description**: Specify the revision to return
485
* **Description**: Return a list of the revisions for the document
489
* **Argument**: revs_info
491
* **Description**: Return a list of detailed revision information for the
499
The specified document or revision cannot be found, or has been deleted
501
Returns the HTTP Headers containing a minimal amount of information
502
about the specified document. The method supports the same query
503
arguments as the ``GET`` method, but only the header information
504
(including document size, and the revision as an ETag), is returned. For
505
example, a simple ``HEAD`` request:
509
HEAD http://couchdb:5984/recipes/FishStew
510
Content-Type: application/json
513
Returns the following HTTP Headers:
515
.. code-block:: javascript
518
Server: CouchDB/1.0.1 (Erlang OTP/R13B)
519
Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
520
Date: Fri, 05 Nov 2010 14:54:43 GMT
521
Content-Type: text/plain;charset=utf-8
523
Cache-Control: must-revalidate
525
The ``Etag`` header shows the current revision for the requested
526
document, and the ``Content-Length`` specifies the length of the data,
527
if the document were requested in full.
529
Adding any of the query arguments (as supported by ```GET```_ method),
530
then the resulting HTTP Headers will correspond to what would be
531
returned. Note that the current revision is not returned when the
532
``refs_info`` argument is used. For example:
537
Server: CouchDB/1.0.1 (Erlang OTP/R13B)
538
Date: Fri, 05 Nov 2010 14:57:16 GMT
539
Content-Type: text/plain;charset=utf-8
541
Cache-Control: must-revalidate
548
* **Method**: ``PUT /db/doc``
549
* **Request**: JSON of the new document, or updated version of the existed
551
* **Response**: JSON of the document ID and revision
552
* **Admin Privileges Required**: no
553
* **Query Arguments**:
555
* **Argument**: batch
557
* **Description**: Allow document store request to be batched with others
560
* **Supported Values**:
566
* **Header**: ``If-Match``
568
* **Description**: Current revision of the document for validation
574
Document has been created successfully
576
Document accepted for writing (batch mode)
579
The ``PUT`` method creates a new named document, or creates a new
580
revision of the existing document. Unlike the ``POST`` method, you
581
must specify the document ID in the request URL.
583
For example, to create the document ``FishStew``, you would send the
588
PUT http://couchdb:5984/recipes/FishStew
589
Content-Type: application/json
593
"subtitle" : "Delicious with fresh bread",
594
"title" : "Fish Stew"
597
The return type is JSON of the status, document ID,and revision number:
599
.. code-block:: javascript
604
"rev" : "1-9c65296036141e575d32ba9c034dd3ee"
607
Updating an Existing Document
608
-----------------------------
610
To update an existing document you must specify the current revision
611
number within the ``_rev`` parameter. For example:
615
PUT http://couchdb:5984/recipes/FishStew
616
Content-Type: application/json
619
"_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
621
"subtitle" : "Delicious with fresh salad",
622
"title" : "Fish Stew"
625
Alternatively, you can supply the current revision number in the
626
``If-Match`` HTTP header of the request. For example:
630
PUT http://couchdb:5984/recipes/FishStew
631
If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
632
Content-Type: application/json
636
"subtitle" : "Delicious with fresh salad",
637
"title" : "Fish Stew"
640
The JSON returned will include the updated revision number:
642
.. code-block:: javascript
647
"rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
650
For information on batched writes, which can provide improved
651
performance, see :ref:`api-batch-writes`.
658
* **Method**: ``DELETE /db/doc``
660
* **Response**: JSON of the deleted revision
661
* **Admin Privileges Required**: no
662
* **Query Arguments**:
666
* **Description**: Current revision of the document for validation
672
* **Header**: ``If-Match``
674
* **Description**: Current revision of the document for validation
680
Revision is missing, invalid or not the latest
682
Deletes the specified document from the database. You must supply the
683
current (latest) revision, either by using the ``rev`` parameter to
684
specify the revision:
688
DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
689
Content-Type: application/json
691
Alternatively, you can use ETags with the ``If-Match`` field:
695
DELETE http://couchdb:5984/recipes/FishStew
696
If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
697
Content-Type: application/json
700
The returned JSON contains the document ID, revision and status:
702
.. code-block:: javascript
707
"rev" : "4-2719fd41187c60762ff584761b714cfb"
710
.. note:: Note that deletion of a record increments the revision number. The
711
use of a revision for deletion of the record allows replication of
712
the database to correctly track the deletion in synchronized copies.
719
* **Method**: ``COPY /db/doc``
721
* **Response**: JSON of the new document and revision
722
* **Admin Privileges Required**: no
723
* **Query Arguments**:
727
* **Description**: Revision to copy from
733
* **Header**: ``Destination``
735
* **Description**: Destination document (and optional revision)
741
Document has been copied and created successfully
743
Revision is missing, invalid or not the latest
745
The ``COPY`` command (which is non-standard HTTP) copies an existing
746
document to a new or existing document.
748
The source document is specified on the request line, with the
749
``Destination`` HTTP Header of the request specifying the target
755
You can copy the latest version of a document to a new document by
756
specifying the current document and target document:
760
COPY http://couchdb:5984/recipes/FishStew
761
Content-Type: application/json
762
Destination: IrishFishStew
764
The above request copies the document ``FishStew`` to the new document
765
``IrishFishStew``. The response is the ID and revision of the new
768
.. code-block:: javascript
771
"id" : "IrishFishStew",
772
"rev" : "1-9c65296036141e575d32ba9c034dd3ee"
775
Copying from a Specific Revision
776
--------------------------------
778
To copy *from* a specific version, use the ``rev`` argument to the query
783
COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
784
Content-Type: application/json
785
Destination: IrishFishStew
787
The new document will be created using the information in the specified
788
revision of the source document.
790
Copying to an Existing Document
791
-------------------------------
793
To copy to an existing document, you must specify the current revision
794
string for the target document, using the ``rev`` parameter to the
795
``Destination`` HTTP Header string. For example:
799
COPY http://couchdb:5984/recipes/FishStew
800
Content-Type: application/json
801
Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee
803
The return value will be the new revision of the copied document:
805
.. code-block:: javascript
808
"id" : "IrishFishStew",
809
"rev" : "2-55b6a1b251902a2c249b667dab1c6692"
812
.. _api-get-attachment:
814
``GET /db/doc/attachment``
815
==========================
817
* **Method**: ``GET /db/doc/attachment``
819
* **Response**: Returns the attachment data
820
* **Admin Privileges Required**: no
822
Returns the file attachment ``attachment`` associated with the document
823
``doc``. The raw data of the associated attachment is returned (just as
824
if you were accessing a static file. The returned HTTP ``Content-type``
825
will be the same as the content type set when the document attachment
826
was submitted into the database.
828
.. _api-put-attachment:
830
``PUT /db/doc/attachment``
831
==========================
833
* **Method**: ``PUT /db/doc/attachment``
834
* **Request**: Raw document data
835
* **Response**: JSON document status
836
* **Admin Privileges Required**: no
837
* **Query Arguments**:
841
* **Description**: Current document revision
847
* **Header**: ``Content-Length``
849
* **Description**: Length (bytes) of the attachment being uploaded
852
* **Header**: ``Content-Type``
854
* **Description**: MIME type for the uploaded attachment
857
* **Header**: ``If-Match``
859
* **Description**: Current revision of the document for validation
865
Attachment has been accepted
867
Upload the supplied content as an attachment to the specified document
868
(``doc``). The ``attachment`` name provided must be a URL encoded
869
string. You must also supply either the ``rev`` query argument or the
870
``If-Match`` HTTP header for validation, and the HTTP headers (to set
871
the attachment content type). The content type is used when the
872
attachment is requested as the corresponding content-type in the
873
returned document header.
875
For example, you could upload a simple text document using the following
880
PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
882
Content-Type: text/plain
886
Or by using the ``If-Match`` HTTP header:
890
PUT http://couchdb:5984/recipes/FishStew/basic
891
If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
893
Content-Type: text/plain
897
The returned JSON contains the new document information:
899
.. code-block:: javascript
904
"rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
907
.. note:: Uploading an attachment updates the corresponding document revision.
908
Revisions are tracked for the parent document, not individual
911
Updating an Existing Attachment
912
-------------------------------
914
Uploading an attachment using an existing attachment name will update
915
the corresponding stored content of the database. Since you must supply
916
the revision information to add an attachment to a document, this serves
917
as validation to update the existing attachment.
919
``DELETE /db/doc/attachment``
920
=============================
922
* **Method**: ``DELETE /db/doc/attachment``
924
* **Response**: JSON status
925
* **Admin Privileges Required**: no
926
* **Query Arguments**:
930
* **Description**: Current document revision
936
* **Header**: ``If-Match``
938
* **Description**: Current revision of the document for validation
944
Attachment deleted successfully
946
Supplied revision is incorrect or missing
948
Deletes the attachment ``attachment`` to the specified ``doc``. You must
949
supply the ``rev`` argument with the current revision to delete the
952
For example to delete the attachment ``basic`` from the recipe
957
DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
958
Content-Type: application/json
962
The returned JSON contains the updated revision information:
964
.. code-block:: javascript
969
"rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
972
.. _JSON object: #table-couchdb-api-db_db-json-changes
973
.. _POST: #couchdb-api-dbdoc_db_post
added
removed
share/doc/build/html/_sources/api/documents.txt
