HTTP Interface for Stream Transactions

Introduced in: v3.5.0

Stream Transactions allow you to perform a multi-document transaction with individual begin and commit / abort commands. This is similar to the way traditional RDBMS do it with BEGIN, COMMIT and ROLLBACK operations.

To use a Stream Transaction a client first sends the configuration of the transaction to the ArangoDB server.

Contrary to the JS-Transaction the definition of this transaction must only contain the collections which are going to be used and (optionally) the various transaction options supported by ArangoDB. No action attribute is supported.

The Stream Transaction API works in conjunction with other APIs in ArangoDB. To use the transaction for a supported operation a client needs to specify the transaction identifier in the x-arango-trx-id header on each request. This will automatically cause these operations to use the specified transaction.

Supported transactional API operations include:

All operations in the Document API
Number of documents via the Collection API
Truncate a collection via the Collection API
Create an AQL cursor via the Cursor API
Handle vertices and edges of managed graphs (General Graph / Gharial API, since v3.5.1)

Note that a client always needs to start the transaction first and it is required to explicitly specify the collections used for write accesses. The client is responsible for making sure that the transaction is committed or aborted when it is no longer needed. This avoids taking up resources on the ArangoDB server.

Transactions will acquire collection locks for write operations in RocksDB. It is therefore advisable to keep the transactions as short as possible.

For a more detailed description of how transactions work in ArangoDB please refer to Transactions.

Also see Limitations.

Begin a Transaction

Begin transaction

begin a server-side transaction

POST /_api/transaction/begin

Request Body

collections (string, required): collections must be a JSON object that can have one or all sub-attributes read, write or exclusive, each being an array of collection names or a single collection name as string. Collections that will be written to in the transaction must be declared with the write or exclusive attribute or it will fail, whereas non-declared collections from which is solely read will be added lazily.
waitForSync (boolean, optional): an optional boolean flag that, if set, will force the transaction to write all data to disk before returning.
allowImplicit (boolean, optional): Allow reading from undeclared collections.
lockTimeout (integer, optional): an optional numeric value that can be used to set a timeout in seconds for waiting on collection locks. This option is only meaningful when using exclusive locks. If not specified, a default value will be used. Setting lockTimeout to 0 will make ArangoDB not time out waiting for a lock.
maxTransactionSize (integer, optional): Transaction size limit in bytes.

The transaction description must be passed in the body of the POST request. If the transaction can be started on the server, HTTP 201 will be returned.

For successfully started transactions, the returned JSON object has the following properties:

error: boolean flag to indicate if an error occurred (false in this case)
code: the HTTP status code
result: result containing
- id: the identifier of the transaction
- status: containing the string ‘running’

If the transaction specification is either missing or malformed, the server will respond with HTTP 400 or HTTP 404.

The body of the response will then contain a JSON object with additional error details. The object has the following attributes:

error: boolean flag to indicate that an error occurred (true in this case)
code: the HTTP status code
errorNum: the server error number
errorMessage: a descriptive error message

Responses

HTTP 201: If the transaction is running on the server, HTTP 201 will be returned.

HTTP 400: If the transaction specification is either missing or malformed, the server will respond with HTTP 400.

HTTP 404: If the transaction specification contains an unknown collection, the server will respond with HTTP 404.

Examples

Executing a transaction on a single collection

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
{ 
  "collections" : { 
    "write" : "products" 
  } 
}
EOF

HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 201, 
  "error" : false, 
  "result" : { 
    "id" : "68980", 
    "status" : "running" 
  } 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
{ 
  "collections" : { 
    "write" : "products" 
  } 
}
EOF

HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Referring to a non-existing collection

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
{ 
  "collections" : { 
    "read" : "products" 
  } 
}
EOF

HTTP/1.1 404 Not Found
content-type: application/json
connection: Keep-Alive
content-length: 97
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "collection or view not found: products", 
  "errorNum" : 1203 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
{ 
  "collections" : { 
    "read" : "products" 
  } 
}
EOF

HTTP/1.1 404 Not Found
content-type: application/json
connection: Keep-Alive
content-length: 97
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Check Status of a Transaction

Get transaction status

Fetch status of a server-side transaction

GET /_api/transaction/{transaction-id}

Path Parameters

transaction-id (string, required): The transaction identifier.

The result is an object describing the status of the transaction. It has at least the following attributes:

id: the identifier of the transaction
status: the status of the transaction. One of “running”, “committed” or “aborted”.

Responses

HTTP 200: If the transaction is fully executed and committed on the server, HTTP 200 will be returned.

HTTP 400: If the transaction identifier specified is either missing or malformed, the server will respond with HTTP 400.

HTTP 404: If the transaction was not found with the specified identifier, the server will respond with HTTP 404.

Examples

Get transaction status

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68988

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 200, 
  "error" : false, 
  "result" : { 
    "id" : "68988", 
    "status" : "running" 
  } 
}

Hide response body

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68988

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Commit or Abort a Transaction

Committing or aborting a running transaction must be done by the client. It is bad practice to not commit or abort a transaction once you are done using it. It will force the server to keep resources and collection locks until the entire transaction times out.

Commit transaction

commit a server-side transaction

PUT /_api/transaction/{transaction-id}

Path Parameters

transaction-id (string, required): The transaction identifier,

Commit a running server-side transaction. Committing is an idempotent operation. It is not an error to commit a transaction more than once.

If the transaction can be committed, HTTP 200 will be returned. The returned JSON object has the following properties:

error: boolean flag to indicate if an error occurred (false in this case)
code: the HTTP status code
result: result containing
- id: the identifier of the transaction
- status: containing the string ‘committed’

If the transaction cannot be found, committing is not allowed or the transaction was aborted, the server will respond with HTTP 400, HTTP 404 or HTTP 409.

The body of the response will then contain a JSON object with additional error details. The object has the following attributes:

error: boolean flag to indicate that an error occurred (true in this case)
code: the HTTP status code
errorNum: the server error number
errorMessage: a descriptive error message

Responses

HTTP 200: If the transaction was committed, HTTP 200 will be returned.

HTTP 400: If the transaction cannot be committed, the server will respond with HTTP 400.

HTTP 404: If the transaction was not found, the server will respond with HTTP 404.

HTTP 409: If the transaction was already aborted, the server will respond with HTTP 409.

Examples

Committing a transaction:

shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68962

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 71
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 200, 
  "error" : false, 
  "result" : { 
    "id" : "68962", 
    "status" : "committed" 
  } 
}

Hide response body

shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68962

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 71
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Abort transaction

abort a server-side transaction

DELETE /_api/transaction/{transaction-id}

Path Parameters

transaction-id (string, required): The transaction identifier,

Abort a running server-side transaction. Aborting is an idempotent operation. It is not an error to abort a transaction more than once.

If the transaction can be aborted, HTTP 200 will be returned. The returned JSON object has the following properties:

error: boolean flag to indicate if an error occurred (false in this case)
code: the HTTP status code
result: result containing
- id: the identifier of the transaction
- status: containing the string ‘aborted’

If the transaction cannot be found, aborting is not allowed or the transaction was already committed, the server will respond with HTTP 400, HTTP 404 or HTTP 409.

The body of the response will then contain a JSON object with additional error details. The object has the following attributes:

error: boolean flag to indicate that an error occurred (true in this case)
code: the HTTP status code
errorNum: the server error number
errorMessage: a descriptive error message

Responses

HTTP 200: If the transaction was aborted, HTTP 200 will be returned.

HTTP 400: If the transaction cannot be aborted, the server will respond with HTTP 400.

HTTP 404: If the transaction was not found, the server will respond with HTTP 404.

HTTP 409: If the transaction was already committed, the server will respond with HTTP 409.

Examples

Aborting a transaction:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68970

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 200, 
  "error" : false, 
  "result" : { 
    "id" : "68970", 
    "status" : "aborted" 
  } 
}

Hide response body

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68970

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

List currently ongoing Transactions

Get currently running transactions

Return the currently running server-side transactions

GET /_api/transaction

The result is an object with the attribute transactions, which contains an array of transactions. In a cluster the array will contain the transactions from all Coordinators.

Each array entry contains an object with the following attributes:

id: the transaction’s id
state: the transaction’s status

Responses

HTTP 200: If the list of transactions can be retrieved successfully, HTTP 200 will be returned.

Examples

Get currently running transactions

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 51
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "transactions" : [ 
    { 
      "id" : "69027", 
      "state" : "running" 
    } 
  ] 
}

Hide response body

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 51
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Limitations

Timeout and transaction size

A maximum lifetime and transaction size for Stream Transactions is enforced on the Coordinator to ensure that abandoned transactions cannot block the cluster from operating properly:

Maximum idle timeout of up to 120 seconds between operations
Maximum transaction size of 128 MB per DB-Server

These limits are also enforced for Stream Transactions on single servers.

The default maximum idle timeout is 60 seconds between operations in a single Stream Transaction. The maximum value can be bumped up to at most 120 seconds by setting the startup option --transaction.streaming-idle-timeout. Posting an operation into a non-expired Stream Transaction will reset the transaction’s timeout to the configured idle timeout.

Enforcing the limit is useful to free up resources used by abandoned transactions, for example from transactions that are abandoned by client applications due to programming errors or that were left over because client connections were interrupted.

Concurrent requests

A given transaction is intended to be used serially. No concurrent requests using the same transaction ID should be issued by the client. The server can make some effort to serialize certain operations (see Streaming Lock Timeout), however this will degrade the server’s performance and may lead to sporadic errors with code 28 (locked).

Batch requests

The Batch API cannot be used in combination with Stream Transactions for submitting batched requests, because the required header x-arango-trx-id is not forwarded.

❮ Transactions JavaScript Transactions ❯