MarkLogic Server 11.0 Product Documentation
POST /v1/rows

Summary

Invoke a plan in order to retrieve a list of rows. The plan is passed in the request body. This is read/query only. For Optic Update use /v1/rows/update.

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: `object`, `array`, `explain` (return explain output from a plan), `generateView`(return a view encapsulating the plan for insertion into the schemas database), and `columnInfo`( return columns info in the plan, like schema, view, column, type, hidden and nullable), `errors` (only returns errors. This is only useful if an Optic error handler is used `op:on-error("continue")`). Default: `object`. You cannot use `explain` or `generateView` 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.
timestamp?	A timestamp returned in the `ML-Effective-Timestamp` header of a previous request. Use this parameter to fetch results based on the database contents at a fixed point-in-time. For more details, see Performing Point-in-Time Operations 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-reader role, or the following privilege:

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

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.json contains the following plan:

{"$optic":{
  "ns":"op", 
  "fn":"operators", 
  "args":[
    {"ns":"op", "fn":"from-view", "args":["main", "employees", null, null]}, 
    {"ns":"op", 
     "fn":"select", 
     "args":[[
         {"ns":"op", "fn":"col", "args":["EmployeeID"]}, 
         {"ns":"op", "fn":"col", "args":["FirstName"]}, 
         {"ns":"op", "fn":"col", "args":["LastName"]}
       ], null ]
    }, 
    {"ns":"op", 
     "fn":"order-by", 
     "args":[[{"ns":"op", "fn":"col", "args":["EmployeeID"]}]]
    }
  ]
}}

Then following command executes plan. 

$ curl --anyauth --user user:password -i -X POST -d @./plan.json \
    -H "Content-type: application/json" -H "Accept: application/json" \
    'http://localhost:8000/v1/rows

==> The data requested by the plan, as JSON. Whitespace has been added
    to the example output below to improve readability.

HTTP/1.1 200 OK
ML-Effective-Timestamp: 14910632403388290
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 1472
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "columns": [
    {"name":"main.employees.EmployeeID"},
    {"name":"main.employees.FirstName"},
    {"name":"main.employees.LastName"}
  ],
  "rows":[
    {"main.employees.EmployeeID":{"type":"xs:integer","value":1},
     "main.employees.FirstName":{"type":"xs:string","value":"John"},
     "main.employees.LastName":{"type":"xs:string","value":"Widget"}},
    {"main.employees.EmployeeID":{"type":"xs:integer","value":2},
     "main.employees.FirstName":{"type":"xs:string","value":"Jane"},
     "main.employees.LastName":{"type":"xs:string","value":"Lead"}},
    {"main.employees.EmployeeID":{"type":"xs:integer","value":3},
     "main.employees.FirstName":{"type":"xs:string","value":"Steve"},
     "main.employees.LastName":{"type":"xs:string","value":"Manager"}}
  ]
}

Example

Suppose the file plan.json contains the following plan:

{"$optic":{
  "ns":"op", 
  "fn":"operators", 
  "args":[
    {"ns":"op", "fn":"from-view", "args":["main", "employees", null, null]}, 
    {"ns":"op", 
     "fn":"select", 
     "args":[[
         {"ns":"op", "fn":"col", "args":["EmployeeID"]}, 
         {"ns":"op", "fn":"col", "args":["FirstName"]}, 
         {"ns":"op", "fn":"col", "args":["LastName"]}
       ], null ]
    }, 
    {"ns":"op", 
     "fn":"order-by", 
     "args":[[{"ns":"op", "fn":"col", "args":["EmployeeID"]}]]
    }
  ]
}}

Then following command executes plan and returns a multipart response.

$ curl --anyauth --user user:password -i -X POST -d @./plan.json \
    -H "Content-type: application/json" \
    -H "Accept: multipart/mixed; boundary=BOUNDARY" \
    'http://localhost:8000/v1/rows

==> The requested data, as a multipart response. The first part contains
    the column information. The remaining parts each contain a row.
    Whitespace has been added to improve readability.

HTTP/1.1 200 OK
ML-Effective-Timestamp: 14910641406831460
Content-type: multipart/mixed; boundary=BOUNDARY
Server: MarkLogic
Content-Length: 2278
Connection: Keep-Alive
Keep-Alive: timeout=5

--BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: inline; kind=columns

{"columns":[{"name":"main.employees.EmployeeID"},
            {"name":"main.employees.FirstName"},
            {"name":"main.employees.LastName"}]}
--BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: inline; kind=row

{"main.employees.EmployeeID":{"type":"xs:integer","value":1},
 "main.employees.FirstName":{"type":"xs:string","value":"John"},
 "main.employees.LastName":{"type":"xs:string","value":"Widget"}}
--BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: inline; kind=row

{"main.employees.EmployeeID":{"type":"xs:integer","value":2},
 "main.employees.FirstName":{"type":"xs:string","value":"Jane"},
 "main.employees.LastName":{"type":"xs:string","value":"Lead"}}
--BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: inline; kind=row

{"main.employees.EmployeeID":{"type":"xs:integer","value":3},
 "main.employees.FirstName":{"type":"xs:string","value":"Steve"},
 "main.employees.LastName":{"type":"xs:string","value":"Manager"}}
--BOUNDARY--

Example

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

op.fromView(null, 'expenses')
  .where(op.and(
      op.ge(op.col('date'), xs.date('2020-01-01')),
      op.le(op.col('date'), xs.date('2020-12-31'))
      ))
  .select([op.col('date'), op.col('amount'), op.col('purpose')])
  .orderBy(op.col('date'))

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

==> The data requested by the DSL query, as JSON.

HTTP/1.1 200 OK
ML-Effective-Timestamp: 16137739803087640
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 2378
Connection: Keep-Alive
Keep-Alive: timeout=5

{
"columns": [{"name":"main.expenses.date"},{"name":"main.expenses.amount"},{"name":"main.expenses.purpose"}],
"rows":[
{"main.expenses.date":{"type":"xs:date","value":"2020-01-01"},"main.expenses.amount":{"type":"xs:decimal","value":11.89},"main.expenses.purpose":{"type":"xs:string","value":"pencils"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-02-01"},"main.expenses.amount":{"type":"xs:decimal","value":75.21},"main.expenses.purpose":{"type":"xs:string","value":"lunch"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-03-01"},"main.expenses.amount":{"type":"xs:decimal","value":87.73},"main.expenses.purpose":{"type":"xs:string","value":"entertainment"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-04-01"},"main.expenses.amount":{"type":"xs:decimal","value":63.35},"main.expenses.purpose":{"type":"xs:string","value":"entertainment"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-05-01"},"main.expenses.amount":{"type":"xs:decimal","value":27.99},"main.expenses.purpose":{"type":"xs:string","value":"entertainment"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-06-01"},"main.expenses.amount":{"type":"xs:decimal","value":62.95},"main.expenses.purpose":{"type":"xs:string","value":"lunch"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-07-01"},"main.expenses.amount":{"type":"xs:decimal","value":4.137},"main.expenses.purpose":{"type":"xs:string","value":"entertainment"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-08-01"},"main.expenses.amount":{"type":"xs:decimal","value":97.97},"main.expenses.purpose":{"type":"xs:string","value":"conference"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-09-01"},"main.expenses.amount":{"type":"xs:decimal","value":32.45},"main.expenses.purpose":{"type":"xs:string","value":"travel"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-10-01"},"main.expenses.amount":{"type":"xs:decimal","value":40.96},"main.expenses.purpose":{"type":"xs:string","value":"conference"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-11-01"},"main.expenses.amount":{"type":"xs:decimal","value":27.55},"main.expenses.purpose":{"type":"xs:string","value":"pencils"}},
{"main.expenses.date":{"type":"xs:date","value":"2020-12-01"},"main.expenses.amount":{"type":"xs:decimal","value":61.9},"main.expenses.purpose":{"type":"xs:string","value":"pencils"}}]
}

Stack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.

MarkLogic Server 11.0 Product DocumentationPOST /v1/rows

Summary

Response

Required Privileges

Usage Notes

See Also

Example

Example

Example

MarkLogic Server 11.0 Product Documentation
POST /v1/rows