@startDocuBlock import_document
@brief imports documents from JSON-encoded lists

@RESTHEADER{POST /_api/import#document,imports document values, RestImportHandler#document}

@RESTALLBODYPARAM{documents,string,required}
The body must consist of JSON-encoded arrays of attribute values, with one
line per document. The first row of the request must be a JSON-encoded
array of attribute names. These attribute names are used for the data in the
subsequent lines.

@RESTQUERYPARAMETERS

@RESTQUERYPARAM{collection,string,required}
The collection name.

@RESTQUERYPARAM{fromPrefix,string,optional}
An optional prefix for the values in `_from` attributes. If specified, the
value is automatically prepended to each `_from` input value. This allows
specifying just the keys for `_from`.

@RESTQUERYPARAM{toPrefix,string,optional}
An optional prefix for the values in `_to` attributes. If specified, the
value is automatically prepended to each `_to` input value. This allows
specifying just the keys for `_to`.

@RESTQUERYPARAM{overwrite,boolean,optional}
If this parameter has a value of `true` or `yes`, then all data in the
collection will be removed prior to the import. Note that any existing
index definitions will be preseved.

@RESTQUERYPARAM{waitForSync,boolean,optional}
Wait until documents have been synced to disk before returning.

@RESTQUERYPARAM{onDuplicate,string,optional}
Controls what action is carried out in case of a unique key constraint
violation. Possible values are:

- *error*: this will not import the current document because of the unique
  key constraint violation. This is the default setting.

- *update*: this will update an existing document in the database with the
  data specified in the request. Attributes of the existing document that
  are not present in the request will be preseved.

- *replace*: this will replace an existing document in the database with the
  data specified in the request.

- *ignore*: this will not update an existing document and simply ignore the
  error caused by the unique key constraint violation.

Note that *update*, *replace* and *ignore* will only work when the
import document in the request contains the *_key* attribute. *update* and
*replace* may also fail because of secondary unique key constraint
violations.

@RESTQUERYPARAM{complete,boolean,optional}
If set to `true` or `yes`, it will make the whole import fail if any error
occurs. Otherwise the import will continue even if some documents cannot
be imported.

@RESTQUERYPARAM{details,boolean,optional}
If set to `true` or `yes`, the result will include an attribute `details`
with details about documents that could not be imported.

@RESTDESCRIPTION
**NOTE** Swagger examples won't work due to the anchor.


Creates documents in the collection identified by `collection-name`.
The first line of the request body must contain a JSON-encoded array of
attribute names. All following lines in the request body must contain
JSON-encoded arrays of attribute values. Each line is interpreted as a
separate document, and the values specified will be mapped to the array
of attribute names specified in the first header line.

The response is a JSON object with the following attributes:

- `created`: number of documents imported.

- `errors`: number of documents that were not imported due to an error.

- `empty`: number of empty lines found in the input (will only contain a
  value greater zero for types `documents` or `auto`).

- `updated`: number of updated/replaced documents (in case `onDuplicate`
  was set to either `update` or `replace`).

- `ignored`: number of failed but ignored insert operations (in case
  `onDuplicate` was set to `ignore`).

- `details`: if query parameter `details` is set to true, the result will
  contain a `details` attribute which is an array with more detailed
  information about which documents could not be inserted.

@RESTRETURNCODES

@RESTRETURNCODE{201}
is returned if all documents could be imported successfully.

@RESTRETURNCODE{400}
is returned if `type` contains an invalid value, no `collection` is
specified, the documents are incorrectly encoded, or the request
is malformed.

@RESTRETURNCODE{404}
is returned if `collection` or the `_from` or `_to` attributes of an
imported edge refer to an unknown collection.

@RESTRETURNCODE{409}
is returned if the import would trigger a unique key violation and
`complete` is set to `true`.

@RESTRETURNCODE{500}
is returned if the server cannot auto-generate a document key (out of keys
error) for a document with no user-defined key.

@EXAMPLES

Importing two documents, with attributes `_key`, `value1` and `value2` each. One
line in the import data is empty

@EXAMPLE_ARANGOSH_RUN{RestImportCsvExample}
    var cn = "products";
    db._drop(cn);
    db._create(cn);

    var body = '[ "_key", "value1", "value2" ]\n' + 
               '[ "abc", 25, "test" ]\n\n' + 
               '[ "foo", "bar", "baz" ]';

    var response = logCurlRequestRaw('POST', "/_api/import?collection=" + cn, body);

    assert(response.code === 201);
    var r = JSON.parse(response.body)
    assert(r.created === 2);
    assert(r.errors === 0);
    assert(r.empty === 1);

    logJsonResponse(response);
    db._drop(cn);
@END_EXAMPLE_ARANGOSH_RUN

Importing into an edge collection, with attributes `_from`, `_to` and `name`

@EXAMPLE_ARANGOSH_RUN{RestImportCsvEdge}
    var cn = "links";
    db._drop(cn);
    db._createEdgeCollection(cn);
    db._drop("products");
    db._create("products");

    var body = '[ "_from", "_to", "name" ]\n' + 
               '[ "products/123","products/234", "some name" ]\n' +
               '[ "products/332", "products/abc", "other name" ]';

    var response = logCurlRequestRaw('POST', "/_api/import?collection=" + cn, body);

    assert(response.code === 201);
    var r = JSON.parse(response.body)
    assert(r.created === 2);
    assert(r.errors === 0);
    assert(r.empty === 0);

    logJsonResponse(response);
    db._drop(cn);
    db._drop("products");
@END_EXAMPLE_ARANGOSH_RUN

Importing into an edge collection, omitting `_from` or `_to`

@EXAMPLE_ARANGOSH_RUN{RestImportCsvEdgeInvalid}
    var cn = "links";
    db._drop(cn);
    db._createEdgeCollection(cn);

    var body = '[ "name" ]\n[ "some name" ]\n[ "other name" ]';

    var response = logCurlRequestRaw('POST', "/_api/import?collection=" + cn + "&details=true", body);

    assert(response.code === 201);
    var r = JSON.parse(response.body)
    assert(r.created === 0);
    assert(r.errors === 2);
    assert(r.empty === 0);

    logJsonResponse(response);
    db._drop(cn);
@END_EXAMPLE_ARANGOSH_RUN

Violating a unique constraint, but allow partial imports

@EXAMPLE_ARANGOSH_RUN{RestImportCsvUniqueContinue}
    var cn = "products";
    db._drop(cn);
    db._create(cn);

    var body = '[ "_key", "value1", "value2" ]\n' + 
               '[ "abc", 25, "test" ]\n' +
               '["abc", "bar", "baz" ]';

    var response = logCurlRequestRaw('POST', "/_api/import?collection=" + cn + "&details=true", body);

    assert(response.code === 201);
    var r = JSON.parse(response.body)
    assert(r.created === 1);
    assert(r.errors === 1);
    assert(r.empty === 0);

    logJsonResponse(response);
    db._drop(cn);
@END_EXAMPLE_ARANGOSH_RUN

Violating a unique constraint, not allowing partial imports

@EXAMPLE_ARANGOSH_RUN{RestImportCsvUniqueFail}
    var cn = "products";
    db._drop(cn);
    db._create(cn);

    var body = '[ "_key", "value1", "value2" ]\n' +
               '[ "abc", 25, "test" ]\n' + 
               '["abc", "bar", "baz" ]';

    var response = logCurlRequest('POST', "/_api/import?collection=" + cn + "&complete=true", body);

    assert(response.code === 409);

    logJsonResponse(response);
    db._drop(cn);
@END_EXAMPLE_ARANGOSH_RUN

Using a non-existing collection

@EXAMPLE_ARANGOSH_RUN{RestImportCsvInvalidCollection}
    var cn = "products";
    db._drop(cn);

    var body = '[ "_key", "value1", "value2" ]\n' + 
               '[ "abc", 25, "test" ]\n' + 
               '["foo", "bar", "baz" ]';

    var response = logCurlRequest('POST', "/_api/import?collection=" + cn, body);

    assert(response.code === 404);

    logJsonResponse(response);
@END_EXAMPLE_ARANGOSH_RUN

Using a malformed body

@EXAMPLE_ARANGOSH_RUN{RestImportCsvInvalidBody}
    var cn = "products";
    db._drop(cn);
    db._create(cn);

    var body = '{ "_key": "foo", "value1": "bar" }';

    var response = logCurlRequest('POST', "/_api/import?collection=" + cn, body);

    assert(response.code === 400);

    logJsonResponse(response);
    db._drop(cn);
@END_EXAMPLE_ARANGOSH_RUN
@endDocuBlock