Loading TOC...

GET /v1/rows

Summary

Invoke a plan in order to retrieve a list of rows.

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 Relational Operations 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 Parameterizing a Plan in the 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 Parameterizing a Plan in the 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 Parameterizing a Plan in the 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 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.
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.
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.
output? Specify the form of output. Allowed values: object, array, explain. Default: object. explain, which returns explain output from the plan, cannot be used with the row-format, column-types, or node-columns parameters. See the Usage Notes for more details.
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.
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

Usage Notes

To generate a plan for use with this method, use the export capability of the Optic API. For more details, see Optic API for Relational Operations 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 JSON objects, XML elements, text documents, and binary documents.

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, immediately followed by a part for each node value within the row. The row parts are in sort order sequence.

Within a row, the column for a node has a cid:* URL value with the content id for the node. In the node part, the Content-ID part header contains the same URL, 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. A node part also contains a Content-Disposition header.

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

Comments

    Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy