Transactions
POST
/_api/database/:db/transaction/begin
Begin a new transaction.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| isolationLevel | string | Isolation level: read_committed (default), read_uncommitted, repeatable_read, serializable. |
No |
Response
200 OK
application/json
{
"tx_id": "transaction_123",
"status": "active",
"isolation_level": "read_committed"
}
POST
/_api/database/:db/transaction/:tx_id/commit
Commit a transaction.
No request body required.
Response
200 OK
application/json
{
"tx_id": "transaction_123",
"status": "committed",
"operations_count": 5
}
POST
/_api/database/:db/transaction/:tx_id/rollback
Rollback a transaction.
No request body required.
Response
200 OK
application/json
{
"tx_id": "transaction_123",
"status": "rolled_back"
}
POST
/_api/database/:db/transaction/:tx_id/document/:collection
Insert a document within a transaction.
{ "_key": "doc1", "name": "Alice", "age": 30 }
Response
201 Created
application/json
{ "_key": "doc1", "tx_id": "transaction_123" }
PUT
/_api/database/:db/transaction/:tx_id/document/:collection/:key
Update a document within a transaction.
{ "name": "Alice Updated", "age": 31 }
Response
200 OK
application/json
{ "_key": "doc1", "tx_id": "transaction_123", "status": "updated" }
DELETE
/_api/database/:db/transaction/:tx_id/document/:collection/:key
Delete a document within a transaction.
Response
204 No Content
POST
/_api/database/:db/transaction/:tx_id/query
Execute a query within a transaction context.
{ "query": "FOR doc IN users FILTER doc.age > 25 RETURN doc" }
Response
200 OK
application/json
{
"result": [ { "_key": "doc1", "name": "Alice", "age": 30 } ],
"tx_id": "transaction_123"
}
Distributed Transactions (Multi-Shard ACID)
Two-Phase Commit (2PC) protocol for atomic operations across shards
POST
/_api/distributed/transaction/begin
Begin a distributed transaction across multiple shards.
Request Body
| Field | Type | Description |
|---|---|---|
| participants | array | List of shard participants |
| participants[].shardId | number | Shard ID (0-based) |
| participants[].nodeId | string | Node identifier |
| participants[].address | string | Node HTTP address (host:port) |
Example Request
{
"participants": [
{"shardId": 0, "nodeId": "node1", "address": "localhost:8001"},
{"shardId": 1, "nodeId": "node2", "address": "localhost:8002"}
]
}
Response
200 OK
application/json
{
"id": "dtx:550e8400-e29b-41d4-a716-446655440000",
"status": "active",
"participantCount": 2
}
POST
/_api/distributed/transaction/:tx_id/prepare
Phase 1 of 2PC: Prepare all participants. Returns success if all participants voted yes.
Response
200 OK
application/json
{
"id": "dtx:550e8400-e29b-41d4-a716-446655440000",
"status": "prepared",
"success": true
}
POST
/_api/distributed/transaction/:tx_id/commit
Phase 2 of 2PC: Commit all participants. Changes become visible.
Response
200 OK
application/json
{
"id": "dtx:550e8400-e29b-41d4-a716-446655440000",
"status": "committed"
}
POST
/_api/distributed/transaction/:tx_id/abort
Abort the distributed transaction. All participants will rollback.
Response
200 OK
application/json
{
"id": "dtx:550e8400-e29b-41d4-a716-446655440000",
"status": "aborted"
}