This page was generated
January  28,  2016
4:07  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API - Transaction Management Functions

Use the /transactions service to manage transactions using the REST API. You can create, commit, rollback, and query the status of transactions. Use these features if your application requires multiple REST API requests to execute within the same transaction context. For details, see 'Managing Transactions' in the REST Application Developer's Guide.
REST Resource Summary
POST /v1/transactions Create a multi-statement transaction.
GET /v1/transactions/{txid} Retrieve status information for the transaction whose id matches the txid given in the request URI.
POST /v1/transactions/{txid} Commit or rollback the transaction whose id matches the txid given in the request URI.
REST Resource Detail
POST /v1/transactions
Summary:

Create a multi-statement transaction. The resulting transaction id may be used in the txid request parameter on subsequent requests to force evaluation to take place in the context of the created transaction.

Parameters:
name : A symbolic name for the transaction. Default: client-txn.
timeLimit : The transaction time limit to apply to this transaction, in seconds. Default: The request timeout configured for the App Server. If the transaction is not committed or rolled back within this time limit, the transaction is automatically rolled back. You may not set the limit to a value greater than the default request timeout configured for the App Server. For details, see xdmp:set-transaction-time-limit.

Response Headers:
Location: Upon success, the Location header contains a transaction URI of the form /transactions/txid, where txid is a concatenation of the host id and transaction id. Use the txid in the txid parameter or URI of subsequent requests.

Required Privilege:

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

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

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


Response:

Upon success, MarkLogic Server returns a status 303 (See Created Transaction) and returns the transaction id in the Location response header.

Usage Notes:

By default, each REST request is serviced in a single transaction. The transaction is committed (or rolled back, in the case of error) automatically before the response sent. Use this request to create a transaction that can service multiple requests. Pass the transaction id in the txid parameter of subsequent requests to service a request in the created transaction.

Transactions created in this way should be explicitly committed or rolled back using the /transactions service. Transactions which are not explicitly committed are rolled back when the session or request times out.

For more details, see 'Understanding Transactions in MarkLogic Server' in the Application Developer's Guide and 'Creating a Transaction' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X POST -d "" -i \
    -H "Content-type: text/plain" \
    http://localhost:8004/v1/transactions

==> A transaction is created. MarkLogic Server returns the 
    transaction ID is returned in the Location header of the
    response. Use the contents of the Location header as the
    value of the "txid" parameter in other methods. The transaction
    ID is of the form /transactions/hostid_transactionid. For
    example, the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 303 See Created Transaction
Location: /transactions/9146583258914468644_3148548124558550433
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/transactions/{txid}
Summary:

Retrieve status information for the transaction whose id matches the txid given in the request URI.

Parameters:
format? : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml. This value takes precedence over the Accept headers.

Request Headers:
Accept*: The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.

Response Headers:
Content-Type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

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

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

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


Response:

Upon success, MarkLogic Server returns status 200 (OK) and returns the transaction status details in the response body. If the transaction no longer exists, MarkLogic Server responds with 410 (Gone).

Usage Notes:

The txid component of the request URI is of the form hostid_transactionid, as is returned by creating a transaction with a POST request on the /transactions service.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.

For more details, see 'Checking Transaction Status' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i \
  http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087

==> Transaction status information for the requested transaction, as XML.
    For example:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 1011
Connection: close

<rapi:transaction-status xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:host>
    <rapi:host-id>15127489353049502680</rapi:host-id>
    <rapi:host-name>host-3.marklogic.com</rapi:host-name>
  </rapi:host>
  <rapi:server>
    <rapi:server-id>16702373622226553017</rapi:server-id>
    <rapi:server-name>RESTstop</rapi:server-name>
  </rapi:server>
  <rapi:database>
    <rapi:database-id>6332900397030137722</rapi:database-id>
    <rapi:database-name>bill</rapi:database-name>
  </rapi:database>
  <rapi:transaction-id>1602843393196055927</rapi:transaction-id>
  <rapi:transaction-name>client-txn</rapi:transaction-name>
  <rapi:transaction-mode>update</rapi:transaction-mode>
  <rapi:transaction-timestamp>0</rapi:transaction-timestamp>
  <rapi:transaction-state>idle</rapi:transaction-state>
  <rapi:canceled>false</rapi:canceled>
  <rapi:start-time>2012-05-07T16:32:42-07:00</rapi:start-time>
  <rapi:time-limit>600</rapi:time-limit>
  <rapi:max-time-limit>3600</rapi:max-time-limit>
  <rapi:user>7071164303237443533</rapi:user>
  <rapi:admin>true</rapi:admin>
</rapi:transaction-status>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
  -H "Accept: application/json" \
  http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087

==> Transaction status information for the requested transaction, as JSON.
    For example:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 647
Connection: close

{
  "transaction-status": {
    "host": {
      "host-id": "15127489353049502680",
      "host-name": "host-3.marklogic.com"
    },
    "server": {
      "server-id": "16702373622226553017",
      "server-name": "RESTstop"
    },
    "database": {
      "database-id": "6332900397030137722",
      "database-name": "bill"
    },
    "transaction-id": "27981556736957754",
    "transaction-name": "client-txn",
    "transaction-mode": "update",
    "transaction-timestamp": "0",
    "transaction-state": "idle",
    "canceled": "false",
    "start-time": "2012-05-07T16:53:00-07:00",
    "time-limit": "600",
    "max-time-limit": "3600",
    "user": "7071164303237443533",
    "admin": "true"
  }
}
  

POST /v1/transactions/{txid}
Summary:

Commit or rollback the transaction whose id matches the txid given in the request URI.

Parameters:
result : Specifies the desired outcome of the transaction. Allowed values: commit, rollback.

Required Privilege:

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

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

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


Response:

MarkLogic Server responds with status 204 (Committed or Rolled Back). If the transaction does not exist, MarkLogic Server responds with status 400 (Bad Request).

Usage Notes:

The txid component of the request URI is of the form hostid_transactionid, as is returned by creating a transaction with a POST request on the /transactions service.

This method marks a transaction for commit, but commit does not occur until any currently executing statements in the transaction complete. For more details, see xdmp:commit.

For more details, see 'Committing or Rolling Back a Transaction' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X POST -d "" -i \
  -H "Content-type: text/plain" \
  http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087?result=commit

==> The requested transaction is committed. MarkLogic Server returns
    the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 204 Committed
Server: MarkLogic
Content-Length: 0
Connection: close