Transactions_

Transactions let you stage multiple database operations and apply them together, atomically. Use transactions to keep related changes consistent, even when they span multiple databases and collections.

How transactions work

1. Call the createTransaction method to create a transaction. This will return a transaction model, including its ID.
2. Stage operations by passing the transactionId parameter to supported document and bulk methods. You can stage many operations at once with the createOperations method.
3. Call the updateTransaction method to commit or roll back.

On commit, Appwrite replays all staged logs in order inside a real database transaction. Staged operations see earlier staged changes (read your own writes). If any affected document changed outside your transaction, the commit fails with a conflict.

Limits

The maximum number of operations you can stage per transaction depends on your plan:

Create a transaction

Call the createTransaction method to begin. It returns a transaction model that includes $id, a status of pending, and an expiresAt timestamp. Pass the ID as transactionId to subsequent operations. A transaction expires 300 seconds after it is created unless you pass a different ttl. Appwrite Server SDKs require an API key.

Stage operations

Add the transactionId parameter to supported methods to stage them instead of immediately persisting.

When you pass transactionId, Appwrite writes the operation to an internal staging area. The target collection is not modified until you commit the transaction.

Stage single operations

Update, upsert, and delete operations accept transactionId, as well as their bulk versions (updateDocuments, upsertDocuments, deleteDocuments). To stage the first write to a brand new document, use upsertDocument with transactionId.

You can read uncommitted changes back inside the same transaction by passing transactionId to getDocument. A plain read without transactionId still returns the committed document.

Stage many with createOperations

Use the createOperations method to stage multiple operations across databases and collections in a single request. Provide an array of operation objects:

[
  {
    "action": "create|update|upsert|delete",
    "databaseId": "<DATABASE_ID>",
    "collectionId": "<COLLECTION_ID>",
    "documentId": "<DOCUMENT_ID>",
    "data": {}
  }
]

Each action takes a different data shape.

Create and upsert

Pass the full document data: an embeddings vector of the collection's dimension and optional metadata.

{ "embeddings": [0.12, -0.08, 0.45, 0.33], "metadata": { "title": "Hamlet" } }

Update

Pass only the fields to change. To replace the vector, pass a new embeddings array of the same length.

{ "metadata": { "title": "Macbeth" } }

Delete

Pass the documentId and omit data.

{ "action": "delete", "databaseId": "<DATABASE_ID>", "collectionId": "<COLLECTION_ID>", "documentId": "<DOCUMENT_ID>" }

Commit or roll back

When you are done staging operations, call the updateTransaction method to finalize the transaction. Set commit to true to apply the staged operations, or rollback to true to discard them. A transaction takes one or the other, so a second call on the same transaction fails with transaction_not_ready.

Inspect and delete transactions

Use getTransaction to check a transaction's status and operation count, listTransactions to list transactions across all databases, and deleteTransaction to discard a transaction without committing it.

Handle conflicts

On commit, Appwrite verifies that documents affected by your transaction haven't changed externally since they were staged. If a conflicting change is detected, the commit fails with a conflict error. Resolve the conflict (for example, refetch and re-stage) and try again.