mirror of https://gitee.com/bigwinds/arangodb
242 lines
7.4 KiB
Markdown
242 lines
7.4 KiB
Markdown
@startDocuBlock post_create_document
|
|
@brief creates documents
|
|
|
|
@RESTHEADER{POST /_api/document/{collection}, Create document, insertDocument}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{collection,string,required}
|
|
The *collection* in which the collection is to be created.
|
|
|
|
@RESTALLBODYPARAM{data,json,required}
|
|
A JSON representation of a single document.
|
|
|
|
@RESTQUERYPARAMETERS
|
|
|
|
@RESTQUERYPARAM{collection,string,optional}
|
|
The name of the collection. This is only for backward compatibility.
|
|
In ArangoDB versions < 3.0, the URL path was */_api/document* and
|
|
this query parameter was required. This combination still works, but
|
|
the recommended way is to specify the collection in the URL path.
|
|
|
|
@RESTQUERYPARAM{waitForSync,boolean,optional}
|
|
Wait until document has been synced to disk.
|
|
|
|
@RESTQUERYPARAM{returnNew,boolean,optional}
|
|
Additionally return the complete new document under the attribute *new*
|
|
in the result.
|
|
|
|
@RESTQUERYPARAM{returnOld,boolean,optional}
|
|
Additionally return the complete old document under the attribute *old*
|
|
in the result. Only available if the overwrite option is used.
|
|
|
|
@RESTQUERYPARAM{silent,boolean,optional}
|
|
If set to *true*, an empty object will be returned as response. No meta-data
|
|
will be returned for the created document. This option can be used to
|
|
save some network traffic.
|
|
|
|
@RESTQUERYPARAM{overwrite,boolean,optional}
|
|
If set to *true*, the insert becomes a replace-insert. If a document with the
|
|
same *_key* already exists the new document is not rejected with unique
|
|
constraint violated but will replace the old document.
|
|
|
|
@RESTDESCRIPTION
|
|
Creates a new document from the document given in the body, unless there
|
|
is already a document with the *_key* given. If no *_key* is given, a new
|
|
unique *_key* is generated automatically.
|
|
|
|
Possibly given *_id* and *_rev* attributes in the body are always ignored,
|
|
the URL part or the query parameter collection respectively counts.
|
|
|
|
If the document was created successfully, then the *Location* header
|
|
contains the path to the newly created document. The *Etag* header field
|
|
contains the revision of the document. Both are only set in the single
|
|
document case.
|
|
|
|
If *silent* is not set to *true*, the body of the response contains a
|
|
JSON object with the following attributes:
|
|
|
|
- *_id* contains the document handle of the newly created document
|
|
- *_key* contains the document key
|
|
- *_rev* contains the document revision
|
|
|
|
If the collection parameter *waitForSync* is *false*, then the call
|
|
returns as soon as the document has been accepted. It will not wait
|
|
until the documents have been synced to disk.
|
|
|
|
Optionally, the query parameter *waitForSync* can be used to force
|
|
synchronization of the document creation operation to disk even in
|
|
case that the *waitForSync* flag had been disabled for the entire
|
|
collection. Thus, the *waitForSync* query parameter can be used to
|
|
force synchronization of just this specific operations. To use this,
|
|
set the *waitForSync* parameter to *true*. If the *waitForSync*
|
|
parameter is not specified or set to *false*, then the collection's
|
|
default *waitForSync* behavior is applied. The *waitForSync* query
|
|
parameter cannot be used to disable synchronization for collections
|
|
that have a default *waitForSync* value of *true*.
|
|
|
|
If the query parameter *returnNew* is *true*, then, for each
|
|
generated document, the complete new document is returned under
|
|
the *new* attribute in the result.
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{201}
|
|
is returned if the documents were created successfully and
|
|
*waitForSync* was *true*.
|
|
|
|
@RESTRETURNCODE{202}
|
|
is returned if the documents were created successfully and
|
|
*waitForSync* was *false*.
|
|
|
|
@RESTRETURNCODE{400}
|
|
is returned if the body does not contain a valid JSON representation
|
|
of one document. The response body contains
|
|
an error document in this case.
|
|
|
|
@RESTRETURNCODE{404}
|
|
is returned if the collection specified by *collection* is unknown.
|
|
The response body contains an error document in this case.
|
|
|
|
@RESTRETURNCODE{409}
|
|
is returned in the single document case if a document with the
|
|
same qualifiers in an indexed attribute conflicts with an already
|
|
existing document and thus violates that unique constraint. The
|
|
response body contains an error document in this case.
|
|
|
|
@EXAMPLES
|
|
|
|
Create a document in a collection named *products*. Note that the
|
|
revision identifier might or might not by equal to the auto-generated
|
|
key.
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostCreate1}
|
|
var cn = "products";
|
|
db._drop(cn);
|
|
db._create(cn, { waitForSync: true });
|
|
|
|
var url = "/_api/document/" + cn;
|
|
var body = '{ "Hello": "World" }';
|
|
|
|
var response = logCurlRequest('POST', url, body);
|
|
|
|
assert(response.code === 201);
|
|
|
|
logJsonResponse(response);
|
|
db._drop(cn);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Create a document in a collection named *products* with a collection-level
|
|
*waitForSync* value of *false*.
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostAccept1}
|
|
var cn = "products";
|
|
db._drop(cn);
|
|
db._create(cn, { waitForSync: false });
|
|
|
|
var url = "/_api/document/" + cn;
|
|
var body = '{ "Hello": "World" }';
|
|
|
|
var response = logCurlRequest('POST', url, body);
|
|
|
|
assert(response.code === 202);
|
|
|
|
logJsonResponse(response);
|
|
db._drop(cn);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Create a document in a collection with a collection-level *waitForSync*
|
|
value of *false*, but using the *waitForSync* query parameter.
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostWait1}
|
|
var cn = "products";
|
|
db._drop(cn);
|
|
db._create(cn, { waitForSync: false });
|
|
|
|
var url = "/_api/document/" + cn + "?waitForSync=true";
|
|
var body = '{ "Hello": "World" }';
|
|
|
|
var response = logCurlRequest('POST', url, body);
|
|
|
|
assert(response.code === 201);
|
|
|
|
logJsonResponse(response);
|
|
db._drop(cn);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Unknown collection name
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostUnknownCollection1}
|
|
var cn = "products";
|
|
|
|
var url = "/_api/document/" + cn;
|
|
var body = '{ "Hello": "World" }';
|
|
|
|
var response = logCurlRequest('POST', url, body);
|
|
|
|
assert(response.code === 404);
|
|
|
|
logJsonResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Illegal document
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostBadJson1}
|
|
var cn = "products";
|
|
db._drop(cn);
|
|
db._create(cn);
|
|
|
|
var url = "/_api/document/" + cn;
|
|
var body = '{ 1: "World" }';
|
|
|
|
var response = logCurlRequest('POST', url, body);
|
|
|
|
assert(response.code === 400);
|
|
|
|
logJsonResponse(response);
|
|
db._drop(cn);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Use of returnNew:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostReturnNew}
|
|
var cn = "products";
|
|
db._drop(cn);
|
|
db._create(cn);
|
|
|
|
var url = "/_api/document/" + cn + "?returnNew=true";
|
|
var body = '{"Hello":"World"}';
|
|
|
|
var response = logCurlRequest('POST', url, body);
|
|
|
|
assert(response.code === 202);
|
|
|
|
logJsonResponse(response);
|
|
db._drop(cn);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostOverwrite}
|
|
var cn = "products";
|
|
db._drop(cn);
|
|
db._create(cn, { waitForSync: true });
|
|
|
|
var url = "/_api/document/" + cn;
|
|
var body = '{ "Hello": "World", "_key" : "lock" }';
|
|
var response = logCurlRequest('POST', url, body);
|
|
// insert
|
|
assert(response.code === 201);
|
|
logJsonResponse(response);
|
|
|
|
body = '{ "Hello": "Universe", "_key" : "lock" }';
|
|
url = "/_api/document/" + cn + "?overwrite=true";
|
|
response = logCurlRequest('POST', url, body);
|
|
// insert same key
|
|
assert(response.code === 201);
|
|
logJsonResponse(response);
|
|
|
|
db._drop(cn);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
@endDocuBlock
|
|
|