arangodb/Documentation/DocuBlocks/Rest/Documents/post_create_document.md

@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