GET /v1/rows

Summary

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

URL Parameters
plan Required. A URI-encoded JSON plan definition to invoke. You can generate a plan using the export capability of the Optic API. For details, see Optic API for Multi-Model Data Access in the Application Developer's Guide.
bind:{name}* A binding name and value. The bind variable ({name}) should be a named parameter placeholder in 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 requesting 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 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 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. See the Usage Notes for more details. For details and examples, see 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, 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.
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

To generate a plan for use with this method, use the export capability of the Optic API. For more details, see Generating a Plan in the REST 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

Given the following plan, exported as JSON:

{"$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. Assume the value of the plan request
parameter is the above plan, URI encoded. (Line breaks have been added
to the URI encoded plan for readability. Remove them before you attempt
to run this command.)

$ curl --anyauth --user user:password -i -X GET -H "Accept: application/json" \
    'http://localhost:8000/v1/rows?plan=%7B%22%24optic%22%3A%7B%22ns%22
     %3A%22op%22%2C%20%22fn%22%3A%22operators%22%2C%20%22args%22%3A%5B%7B
     %22ns%22%3A%22op%22%2C%20%22fn%22%3A%22from-view%22%2C%20%22args
     %22%3A%5B%22main%22%2C%20%22employees%22%2C%20null%2C%20null%5D%7D
     %2C%20%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22select%22%2C%20
     %22args%22%3A%5B%5B%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22col%22
     %2C%20%22args%22%3A%5B%22EmployeeID%22%5D%7D%2C%20%7B%22ns%22%3A%22
     op%22%2C%20%22fn%22%3A%22col%22%2C%20%22args%22%3A%5B%22FirstName%22
     %5D%7D%2C%20%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22col%22%2C%20
     %22args%22%3A%5B%22LastName%22%5D%7D%5D%2C%20null%5D%7D%2C%20%7B
     %22ns%22%3A%22op%22%2C%20%22fn%22%3A%22order-by%22%2C%20%22args%22
     %3A%5B%5B%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22col%22%2C%20
     %22args%22%3A%5B%22EmployeeID%22%5D%7D%5D%5D%7D%5D%7D%7D'

==> 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

Given the following plan, exported as JSON:

{"$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 the following command executes the plan and returns the results
as a multipart reponse. Assume the value of the plan request
parameter is the above plan, URI encoded. (Line breaks have been added
to the URI encoded plan for readability. Remove them before you attempt
to run this command.)

$ curl --anyauth --user user:password -i -X GET -H "Accept: application/json" \
    -H "Content-type: multipart/mixed; boundary=BOUNDARY" \
    'http://localhost:8000/v1/rows?plan=%7B%22%24optic%22%3A%7B%22ns%22
     %3A%22op%22%2C%20%22fn%22%3A%22operators%22%2C%20%22args%22%3A%5B%7B
     %22ns%22%3A%22op%22%2C%20%22fn%22%3A%22from-view%22%2C%20%22args
     %22%3A%5B%22main%22%2C%20%22employees%22%2C%20null%2C%20null%5D%7D
     %2C%20%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22select%22%2C%20
     %22args%22%3A%5B%5B%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22col%22
     %2C%20%22args%22%3A%5B%22EmployeeID%22%5D%7D%2C%20%7B%22ns%22%3A%22
     op%22%2C%20%22fn%22%3A%22col%22%2C%20%22args%22%3A%5B%22FirstName%22
     %5D%7D%2C%20%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22col%22%2C%20
     %22args%22%3A%5B%22LastName%22%5D%7D%5D%2C%20null%5D%7D%2C%20%7B
     %22ns%22%3A%22op%22%2C%20%22fn%22%3A%22order-by%22%2C%20%22args%22
     %3A%5B%5B%7B%22ns%22%3A%22op%22%2C%20%22fn%22%3A%22col%22%2C%20
     %22args%22%3A%5B%22EmployeeID%22%5D%7D%5D%5D%7D%5D%7D%7D'

==> 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--
Powered by MarkLogic Server | Terms of Use | Privacy Policy