ArangoDB v4.x is under development and not released yet.

This documentation is not final and potentially incomplete.

Stream Transaction HTTP API

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.

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 automatically causes these operations to use the specified transaction.

Supported transactional API operations include:

All operations in the Document API
Get the number of documents via the Collection API
Truncate a collection via the Collection API
Create an AQL cursor via the Cursor API
Handle nodes and edges of managed graphs (General Graph / Gharial API)

Begin a Stream Transaction

POST http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/transaction/begin

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.

Path Parameters

database-name string
The name of the database.
Example: _system

Query Parameters

HTTP Headers

x-arango-allow-dirty-read boolean
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 application/json object

allowImplicit boolean (default: true)
Allow reading from undeclared collections.
collections object, required
Must be a JSON object that can have the sub-attributes read, write, and 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 the respective write operations will fail (but not automatically abort the Stream Transaction), whereas non-declared collections from which is solely read will be added lazily.
- exclusive
  A single collection or a list of collections to acquire exclusive write access for.
- read
  A single collection or a list of collections to use in the transaction in read-only mode.
- write
  A single collection or a list of collections to use in the transaction in write or read mode.
lockTimeout integer (default: 900)
The timeout in seconds for waiting on collection locks. This option is only meaningful when using exclusive locks. Set lockTimeout to 0 to make ArangoDB not time out waiting for a lock.
maxTransactionSize integer
Transaction size limit in bytes.
Default: Controlled by the --transaction.streaming-max-transaction-size startup option.
skipFastLockRound boolean (default: false)
Whether to disable fast locking for write operations.
Skipping the fast lock round can be faster overall if there are many concurrent Stream Transactions queued that all try to lock the same collection exclusively. It avoids deadlocking and retrying which can occur with the fast locking by guaranteeing a deterministic locking order at the expense of each actual locking operation taking longer.
Fast locking should not be skipped for read-only Stream Transactions because it degrades performance if there are no concurrent transactions that use exclusive locks on the same collection.
waitForSync boolean
An optional boolean flag that, if set, forces the transaction to write all data to disk before returning.

Responses

201 Created
The transaction has been started on the server.
- code integer
  The HTTP response status code.
  Example: 201
- error boolean
  A flag indicating that no error occurred.
  Example: false
- result object
  An object describing the started transaction.
  id string
  The identifier of the transaction.
  status string
  The value is always: "running"
  The status of the transaction. Always running for a successfully started transaction.
400 Bad Request
The transaction specification is either missing or malformed.
- code integer
  The HTTP response status code.
  Example: 400
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
404 Not Found
The transaction specification contains an unknown collection.
- code integer
  The HTTP response status code.
  Example: 404
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Examples

Executing a transaction on a single collection

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

Show output

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

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

Referring to a non-existing collection

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

Show output

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

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

Get the status of a Stream Transaction

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/transaction/:transaction-id

Retrieve the status of a Stream Transaction by its identifier.

After a transaction is committed or aborted, the server remembers its final state for a limited time. During this window, querying the transaction returns its final status (committed or aborted). Once the server garbage-collects this record, the same identifier becomes unknown and the endpoint returns 404.

Path Parameters

database-name string
The name of the database.
Example: _system
transaction-id string
The transaction identifier.

Query Parameters

HTTP Headers

Responses

200 OK
The transaction is found and its status returned.
- code integer
  The HTTP response status code.
  Example: 200
- error boolean
  A flag indicating that no error occurred.
  Example: false
- result object
  An object describing the status of the transaction.
  id string
  The identifier of the transaction.
  status string
  Possible values: "running", "committed", "aborted"
  The status of the transaction.
400 Bad Request
The transaction identifier is either missing or malformed.
- code integer
  The HTTP response status code.
  Example: 400
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
404 Not Found
No transaction was found with the specified identifier.
- code integer
  The HTTP response status code.
  Example: 404
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Examples

Get transaction status

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

Show output

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

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

Commit a Stream Transaction

PUT http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/transaction/:transaction-id

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

The server remembers a transaction’s final state for a limited time after it ends. As a result, the response can vary depending on when you call this endpoint:

While the transaction is still tracked: committing an already-committed transaction returns 200 (idempotent), and committing an already-aborted transaction returns 400.
Once the server has garbage-collected the transaction’s record, the identifier is no longer known and the endpoint returns 404.

Path Parameters

database-name string
The name of the database.
Example: _system
transaction-id string
The transaction identifier,

Query Parameters

HTTP Headers

Responses

200 OK
The transaction has been committed.
- code integer
  The HTTP response status code.
  Example: 200
- error boolean
  A flag indicating that no error occurred.
  Example: false
- result object
  An object describing the committed transaction.
  id string
  The identifier of the transaction.
  status string
  The value is always: "committed"
  The status of the transaction. Always committed for a successfully committed transaction.
400 Bad Request
The transaction identifier is malformed, or the transaction is in a state that does not allow committing (for example, it was already aborted).
- code integer
  The HTTP response status code.
  Example: 400
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
404 Not Found
No transaction is known under the specified identifier.
- code integer
  The HTTP response status code.
  Example: 404
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Examples

Committing a transaction:

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

Show output

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

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

Abort a Stream Transaction

DELETE http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/transaction/:transaction-id

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

The server remembers a transaction’s final state for a limited time after it ends. As a result, the response can vary depending on when you call this endpoint:

While the transaction is still tracked: aborting an already-aborted transaction returns 200 (idempotent), and aborting an already-committed transaction returns 400.
The first abort against an unknown identifier returns 404 and records it as aborted. Subsequent aborts for the same identifier return 200 until the record is garbage-collected, after which the identifier is again unknown and the next abort once more returns 404.

Path Parameters

database-name string
The name of the database.
Example: _system
transaction-id string
The transaction identifier,

Query Parameters

HTTP Headers

Responses

200 OK
The transaction has been aborted.
- code integer
  The HTTP response status code.
  Example: 200
- error boolean
  A flag indicating that no error occurred.
  Example: false
- result object
  An object describing the aborted transaction.
  id string
  The identifier of the transaction.
  status string
  The value is always: "aborted"
  The status of the transaction. Always aborted for a successfully aborted transaction.
400 Bad Request
The transaction identifier is malformed, or the transaction is in a state that does not allow aborting (for example, it was already committed).
- code integer
  The HTTP response status code.
  Example: 400
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
404 Not Found
No transaction is known under the specified identifier.
- code integer
  The HTTP response status code.
  Example: 404
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Examples

Aborting a transaction:

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

Show output

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

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

List the running Stream Transactions

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/transaction

List the currently running Stream Transactions. In a cluster, the list contains the transactions from all Coordinators.

Path Parameters

database-name string
The name of the database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
The list of transactions can be retrieved successfully.
- transactions array of objects
  An array of currently running transactions. In a cluster, this contains the transactions from all Coordinators.
  id string
  The identifier of the transaction.
  state string
  The value is always: "running"
  The status of the transaction. Always running if it’s in the list of running transactions.

Examples

Get currently running transactions

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

Show output

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

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