MarkLogic Server 11.0 Product Documentation
POST /v1/rows/update

Summary

Execute an Optic Update (DSL) pipeline in an update transaction. Use /v1/rows for pure lock-free reading/querying. Use this endpoint only to execute updates. The plan is passed in the request body.

URL Parameters
bind:{name}*	A binding name and value. The request must have a bind variable ({name}) for every named parameter placeholder in the plan. For details, see Passing Parameters into a Plan in the REST Application Developer's Guide.
bind:{name}:{type}*	A binding name, type, and value. The {type} can be any derivation of `xs:anyAtomicType` other than `xs:QName`. For details, see Passing Parameters into a Plan in the REST Application Developer's Guide.
bind:{name}@{lang}*	A binding name, language code, and value. Use this pattern to bind to language-tagged strings. For details, see Passing Parameters into a Plan in the REST Application Developer's Guide.
trace*	The name of a trace event to enable during this operation. Trace event output goes into the server log.
tracelabel	This parameter outputs the query's plan, optimization and execution details in the log while getting results. ID is the identifier to identify the query in the logs.
optimize	Sets the optimization level to use. Levels of 0 (off), 1, and 2 are recognized. The default is 1.
row-format?	Specify the format of a row when request a multipart reponse. Allowed values: `json`, `xml`. Default: `json`. You can only use this parameter when the Accept header is set to `multipart/mixed`. For more details and examples, see Generating a Row Set in the REST Application Developer's Guide.
column-types?	Specify whether to emit column data types on each row (default) or only the column name header. Allowed values: `rows`, `header`. Default: `rows`. Choose `header` if the columns are consistent or data type information is not needed. For more details and examples, see Generating a Row Set in the REST Application Developer's Guide.
node-columns?	Specify whether array, binary, element, object, and text node columns should be serialized inline or as a reference to a separate response part. Allowed values: `inline`, `reference`. Default: `inline`. You can only use this parameter when the Accept header is `multipart/mixed`. For more details and examples, see the Usage Notes below and Handling Complex Column Values in the REST Application Developer's Guide.
output?	Specify the form of output. Allowed values: `none` (do not output the plan results), `object`, `array`, `explain` (return explain output from a plan), `errors` (only returns errors. This is only useful if an Optic error handler is used `op:on-error("continue")`). Default: If the plan contains an error-handler the default is `errors` else `none`. You cannot use `explain` with the `row-format`, `column-types`, or `node-columns` parameters. For more details and examples, see the Usage Notes below and Generating a Row Set in the REST Application Developer's Guide.
database?	Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
schemaName?	The schema name to use when generating a view as the output. You cannot specify `schemaName` for other kinds of output.
viewName?	The view name to use when generating a view as the output. You cannot specify `viewName` for other kinds of output.

Request Headers
Accept*	The expected MIME type of the response. Allowed values: `application/json` (default), `application/json-seq` (also known as line-delimited or concatenated JSON), `application/xml`, `multipart/mixed`, and `text/csv`. See the Usage Notes for which MIME types can be used with which parameters.
Content-type	The MIME type of the request body. Allowed values: `application/json` for an Optic query serialized as an AST (Abstract Syntax Tree) in JSON format `application/vnd.marklogic.querydsl+javascript` for an Optic query represented in JavaScript syntax `application/sql` for an SQL SELECT statement `application/sparql-query` for a SPARQL SELECT statement

Response Headers
Content-type	The MIME type of the data in the response body. The MIME type corresponds to the type requested by the Accept header. A `charset=utf-8` declaration is appended to the response MIME types `application/json`, `application/xml`, and `text/csv`.
ML-Effective-Timestamp	The system timestamp at which this operation was performed. You can use the value in the `timestamp` parameter of a subsequent request. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.

Response

Upon success, MarkLogic Server returns status 200 (OK) and the response body contains the requested data.

Required Privileges

This operation requires the rest-writer role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-writer

Using the trace parameter requires the rest-tracer role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-tracer

Usage Notes

The request body can contain the JSON representation of a plan generated using the export capability of the Optic API. For more details, see Generating a Plan in the REST Application Developer's Guide.

A client can also send the Query DSL representation, which uses a narrow subset of JavaScript syntax -- only the JavaScript statement that builds the query. For more details, see Query DSL for Optic API in the Application Developer's Guide.

When the output parameter value is object, MarkLogic returns each row as an object, with the row column names serving as the property names. When the output parameter value is array, MarkLogic returns each row as an array. The items in the first array are the column names, in the order of the values in the subsequenct arrays.

The choice of object or array as the value of the output request parameter affects the representation of the rows in a JSON response. This choice also affects the input provided to a mapper or reducer function invoked by the plan, regardless of the response MIME type.

If a column has a node value with a format that differs from the row format, the node value is serialized to a string. For example, if you retrieve results as JSON, an XML element value get serialized as a string. If the response MIME type is text/csv, all nodes are serialized.

Binary nodes are represented as "(BINARY)" unless the response MIME type is multipart/mixed.

The multipart/mixed reponse MIME type enables you to retrieve row data as separate parts. If you set the node-columns request parameter to "reference", you can also retrieve non-atomic values such as JSON objects, XML elements, and binary nodes as a separate part. For more details, see Generating a Row Set in the REST Application Developer's Guide and Handling Complex Column Values in the REST Application Developer's Guide.

When the response MIME type is multipart/mixed, the row-format request parameter determines whether each row is represented in JSON or XML. The first part contains the header information. The rest of the response contains a part for each row. The row parts are in sort order sequence.

If you use node-columns=reference with a multipart response, any row that contains a non-atomic column value is followed by a part for each referenced value. Within the referencing row, the column value is a reference to the value part of the form cid:*. In the complex value part, the Content-ID part header contains the same id, enclosed in angle brackets. The content id is based on the column name and row number. The content id uses the standard Content-id/CID format described in https://tools.ietf.org/html/rfc2392. For more details, see Handling Complex Column Values in the REST Application Developer's Guide.

When you use the response MIME type application/json-seq, the response includes one JSON object for the header and one for each row. For more details on this format, see the json-seq RFC at https://tools.ietf.org/html/rfc7464. This reponse type streams the results back from MarkLogic, so the client application does not have to wait for the entire response to begin parsing the output.

Example

Suppose the file plan.js contains the following Optic DSL:

const docDescriptors = [
    {
        uri:"/doc1.json",
        doc:{"hello": "world"}
    }
];

op.fromDocDescriptors(docDescriptors)
   .write()

The following executes the query:

$ curl --anyauth --user user:password -i -X POST -d @./plan.js -H "Content-type: application/vnd.marklogic.querydsl+javascript" -H "Accept: application/json" http://localhost:8000/v1/rows/update

==> The document is inserted/updated. No output is returned:

HTTP/1.1 200 OK
Content-type: text/plain; charset=utf-8
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5