Databases API Reference - Docs

The Databases service allows you to create structured collection of documents, query and filter lists of documents, and manage an advanced set of read and write access permissions.

All data returned by the Databases service are represented as structured JSON documents.

The Databases service can contain multiple databases, each database can contain multiple collections. A collection is a group of similarly structured documents. The accepted structure of documents is defined by collection attributes. The collection attributes help you ensure all your user-submitted data is validated and stored according to the collection structure.

Using Appwrite permissions architecture, you can assign read or write access to each collection or document in your project for either a specific user, team, user role, or even grant it with public access (any). You can learn more about how Appwrite handles permissions and access control.

Base URL

https://<REGION>.cloud.appwrite.io/v1

Create document

Create a new Document. Before using this route, you should create a new collection resource using either a server integration API or directly from your database console.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID. You can create a new collection using the Database service server integration. Make sure to define attributes before creating documents.
- documentId string
  
  Document ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
- data object
  
  Document data as JSON object.
- permissions array
  
  An array of permissions strings. By default, only the current user is granted all permissions. Learn more about permissions.
- transactionId string
  
  Transaction ID for staging the operation.
Response
- 201 application/json
  
  Document
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

POST /databases/{databaseId}/collections/{collectionId}/documents

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let document = try await databases.createDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    data: [
        "username": "walter.obrien",
        "email": "walter.obrien@example.com",
        "fullName": "Walter O'Brien",
        "age": 30,
        "isAdmin": false
    ],
    permissions: [Permission.read(Role.any())], // optional
    transactionId: "<TRANSACTION_ID>" // optional
)

Get document

Get a document by its unique ID. This endpoint response returns a JSON object with the document data.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID. You can create a new collection using the Database service server integration.
- documentId string
  required
  
  Document ID.
- queries array
  
  Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long.
- transactionId string
  
  Transaction ID to read uncommitted changes within the transaction.
Response
- 200 application/json
  
  Document

Endpoint

GET /databases/{databaseId}/collections/{collectionId}/documents/{documentId}

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let document = try await databases.getDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    queries: [], // optional
    transactionId: "<TRANSACTION_ID>" // optional
)

List documents

Get a list of all the user's documents in a given collection. You can use the query params to filter your results.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID. You can create a new collection using the Database service server integration.
- queries array
  
  Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long.
- transactionId string
  
  Transaction ID to read uncommitted changes within the transaction.
Response
- 200 application/json
  
  Documents List

Endpoint

GET /databases/{databaseId}/collections/{collectionId}/documents

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let documentList = try await databases.listDocuments(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    queries: [], // optional
    transactionId: "<TRANSACTION_ID>" // optional
)

Update document

Update a document by its unique ID. Using the patch method you can pass only specific fields that will get updated.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID.
- documentId string
  required
  
  Document ID.
- data object
  
  Document data as JSON object. Include only attribute and value pairs to be updated.
- permissions array
  
  An array of permissions strings. By default, the current permissions are inherited. Learn more about permissions.
- transactionId string
  
  Transaction ID for staging the operation.
Response
- 200 application/json
  
  Document
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PATCH /databases/{databaseId}/collections/{collectionId}/documents/{documentId}

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let document = try await databases.updateDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    data: [:], // optional
    permissions: [Permission.read(Role.any())], // optional
    transactionId: "<TRANSACTION_ID>" // optional
)

Upsert a document

Create or update a Document. Before using this route, you should create a new collection resource using either a server integration API or directly from your database console.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID.
- documentId string
  required
  
  Document ID.
- data object
  required
  
  Document data as JSON object. Include all required attributes of the document to be created or updated.
- permissions array
  
  An array of permissions strings. By default, the current permissions are inherited. Learn more about permissions.
- transactionId string
  
  Transaction ID for staging the operation.
Response
- 201 application/json
  
  Document
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PUT /databases/{databaseId}/collections/{collectionId}/documents/{documentId}

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let document = try await databases.upsertDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    data: [:],
    permissions: [Permission.read(Role.any())], // optional
    transactionId: "<TRANSACTION_ID>" // optional
)

Delete document

Delete a document by its unique ID.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID. You can create a new collection using the Database service server integration.
- documentId string
  required
  
  Document ID.
- transactionId string
  
  Transaction ID for staging the operation.
Response
- 204 no content
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 60 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	60 requests	IP + METHOD + URL + USER ID

Endpoint

DELETE /databases/{databaseId}/collections/{collectionId}/documents/{documentId}

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let result = try await databases.deleteDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    transactionId: "<TRANSACTION_ID>" // optional
)

Increment document attribute

Increment a specific attribute of a document by a given value.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID.
- documentId string
  required
  
  Document ID.
- attribute string
  required
  
  Attribute key.
- value number
  
  Value to increment the attribute by. The value must be a number.
- max number
  
  Maximum value for the attribute. If the current value is greater than this value, an error will be thrown.
- transactionId string
  
  Transaction ID for staging the operation.
Response
- 200 application/json
  
  Document
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PATCH /databases/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/increment

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let document = try await databases.incrementDocumentAttribute(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    attribute: "",
    value: 0, // optional
    max: 0, // optional
    transactionId: "<TRANSACTION_ID>" // optional
)

Decrement document attribute

Decrement a specific attribute of a document by a given value.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID.
- documentId string
  required
  
  Document ID.
- attribute string
  required
  
  Attribute key.
- value number
  
  Value to increment the attribute by. The value must be a number.
- min number
  
  Minimum value for the attribute. If the current value is lesser than this value, an exception will be thrown.
- transactionId string
  
  Transaction ID for staging the operation.
Response
- 200 application/json
  
  Document
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PATCH /databases/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/decrement

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let document = try await databases.decrementDocumentAttribute(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    attribute: "",
    value: 0, // optional
    min: 0, // optional
    transactionId: "<TRANSACTION_ID>" // optional
)

Create operations

Create multiple operations in a single transaction.

Request
- transactionId string
  required
  
  Transaction ID.
- operations array
  
  Array of staged operations.
Response
- 201 application/json
  
  Transaction

Endpoint

POST /databases/transactions/{transactionId}/operations

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let transaction = try await databases.createOperations(
    transactionId: "<TRANSACTION_ID>",
    operations: [
	    {
	        "action": "create",
	        "databaseId": "<DATABASE_ID>",
	        "collectionId": "<COLLECTION_ID>",
	        "documentId": "<DOCUMENT_ID>",
	        "data": {
	            "name": "Walter O'Brien"
	        }
	    }
	] // optional
)

Create transaction

Create a new transaction.

Request
- ttl integer
  
  Seconds before the transaction expires.
Response
- 201 application/json
  
  Transaction

Endpoint

POST /databases/transactions

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let transaction = try await databases.createTransaction(
    ttl: 60 // optional
)

Get transaction

Get a transaction by its unique ID.

Request
- transactionId string
  required
  
  Transaction ID.
Response
- 200 application/json
  
  Transaction

Endpoint

GET /databases/transactions/{transactionId}

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let transaction = try await databases.getTransaction(
    transactionId: "<TRANSACTION_ID>"
)

List transactions

List transactions across all databases.

Request
- queries array
  
  Array of query strings generated using the Query class provided by the SDK. Learn more about queries.
Response
- 200 application/json
  
  Transaction List

Endpoint

GET /databases/transactions

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let transactionList = try await databases.listTransactions(
    queries: [] // optional
)

Update transaction

Update a transaction, to either commit or roll back its operations.

Request
- transactionId string
  required
  
  Transaction ID.
- commit boolean
  
  Commit transaction?
- rollback boolean
  
  Rollback transaction?
Response
- 200 application/json
  
  Transaction

Endpoint

PATCH /databases/transactions/{transactionId}

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let transaction = try await databases.updateTransaction(
    transactionId: "<TRANSACTION_ID>",
    commit: false, // optional
    rollback: false // optional
)

Delete transaction

Delete a transaction by its unique ID.

Request
- transactionId string
  required
  
  Transaction ID.
Response
- 204 no content

Endpoint

DELETE /databases/transactions/{transactionId}

Apple

import Appwrite

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
    .setProject("<YOUR_PROJECT_ID>") // Your project ID

let databases = Databases(client)

let result = try await databases.deleteTransaction(
    transactionId: "<TRANSACTION_ID>"
)

Recommended