HTTP interface for Stream Transactions
Stream Transactions allow you to perform a multi-document transaction with individual begin and commit/abort commands
For an introduction to this transaction type, see Stream Transactions.
To use a Stream Transaction, a client first sends the configuration of the transaction to the ArangoDB server.
Contrary to JavaScript Transactions, the definition of Stream Transaction must only contain the collections that 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
HTTP 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)
Begin transaction
begin a server-side transaction
POST /_api/transaction/begin
Header Parameters
-
x-arango-allow-dirty-read (boolean, optional): Set this header to
true
to allow the Coordinator to ask any shard replica for the data, not only the shard leader. This may result in “dirty reads”.This header decides about dirty reads for the entire transaction. Individual read operations, that are performed as part of the transaction, cannot override it.
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.
Begin a Stream Transaction that allows clients to call selected APIs over a short period of time, referencing the transaction ID, and have the server execute the operations transactionally.
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 forces the server to keep resources and collection locks until the entire transaction times out.
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
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 69
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
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
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 97
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
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/70824
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 69
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
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/70798
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 71
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
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/70806
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 69
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
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
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 51
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff