Loading TOC...

MarkLogic 10 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.

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.
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). 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.

See Also

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 iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.