Announcing the Appwrite OSS Fund, Learn More! 🤑
Docs

Database API


Client integration with  

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

All the data in the database service is stored in structured JSON documents.

Each database document structure in your project is defined using the Appwrite 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 (role:all). You can learn more about how Appwrite handles permissions and access control.

Create Document

POST/v1/database/collections/{collectionId}/documents

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.

HTTP Request

Name Type Description
collectionId required string

Collection ID. You can create a new collection using the Database service server integration. Make sure to define attributes before creating documents.

documentId required string

Document ID. Choose your own unique ID or pass the string "unique()" to auto generate it. 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 required object

Document data as JSON object.

read optional array

An array of strings with read permissions. By default only the current user is granted with read permissions. learn more about permissions and get a full list of available permissions.

write optional array

An array of strings with write permissions. By default only the current user is granted with write permissions. learn more about permissions and get a full list of available permissions.

HTTP Response

Status Code Content Type Payload
201  Created application/json Document Object
Example Request
  • const sdk = new Appwrite();
    
    sdk
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    let promise = sdk.database.createDocument('[COLLECTION_ID]', '[DOCUMENT_ID]', {});
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Database database = Database(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = database.createDocument(
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
        data: {},
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    func main() async throws {
        let client = Client()
          .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
          .setProject("5df5acd0d48c2") // Your project ID
        let database = Database(client)
        let document = try await database.createDocument(
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]",
            data: 
        )
    
        print(String(describing: document)
    }
    
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    class MainActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_main)
    
            val client = Client(applicationContext)
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2") // Your project ID
    
            val database = Database(client)
    
            GlobalScope.launch {
                val response = database.createDocument(
                    collectionId = "[COLLECTION_ID]",
                    documentId = "[DOCUMENT_ID]",
                    data = mapOf( "a" to "b" ),
                )
                val json = response.body?.string()        
            }
        }
    }
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    public class MainActivity extends AppCompatActivity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
    
            Client client = new Client(getApplicationContext())
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2"); // Your project ID
    
            Database database = new Database(client);
    
            database.createDocument(
                "[COLLECTION_ID]", 
                "[DOCUMENT_ID]", 
                mapOf( "a" to "b" ), 
                new Continuation<Object>() {
                    @NotNull
                    @Override
                    public CoroutineContext getContext() {
                        return EmptyCoroutineContext.INSTANCE;
                    }
    
                    @Override
                    public void resumeWith(@NotNull Object o) {
                        String json = "";
                        try {
                            if (o instanceof Result.Failure) {
                                Result.Failure failure = (Result.Failure) o;
                                throw failure.exception;
                            } else {
                                Response response = (Response) o;
                                json = response.body().string();
                            }                    
                        } catch (Throwable th) {
                            Log.e("ERROR", th.toString());
                        }
                    }
                }
            );
        }
    }

List Documents

GET/v1/database/collections/{collectionId}/documents

Get a list of all the user documents. You can use the query params to filter your results. On admin mode, this endpoint will return a list of all of the project's documents. Learn more about different API modes.

HTTP Request

Name Type Description
collectionId required string

Collection ID. You can create a new collection using the Database service server integration.

queries optional 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 128 characters long.

limit optional integer

Maximum number of documents to return in response. By default will return maximum 25 results. Maximum of 100 results allowed per request.

offset optional integer

Offset value. The default value is 0. Use this value to manage pagination. learn more about pagination

cursor optional string

ID of the document used as the starting point for the query, excluding the document itself. Should be used for efficient pagination when working with large sets of data. learn more about pagination

cursorDirection optional string

Direction of the cursor.

orderAttributes optional array

Array of attributes used to sort results. Maximum of 100 order attributes are allowed, each 128 characters long.

orderTypes optional array

Array of order directions for sorting attribtues. Possible values are DESC for descending order, or ASC for ascending order. Maximum of 100 order types are allowed.

HTTP Response

Status Code Content Type Payload
200  OK application/json Documents List Object
Example Request
  • const sdk = new Appwrite();
    
    sdk
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    let promise = sdk.database.listDocuments('[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Database database = Database(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = database.listDocuments(
        collectionId: '[COLLECTION_ID]',
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    func main() async throws {
        let client = Client()
          .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
          .setProject("5df5acd0d48c2") // Your project ID
        let database = Database(client)
        let documentList = try await database.listDocuments(
            collectionId: "[COLLECTION_ID]"
        )
    
        print(String(describing: documentList)
    }
    
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    class MainActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_main)
    
            val client = Client(applicationContext)
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2") // Your project ID
    
            val database = Database(client)
    
            GlobalScope.launch {
                val response = database.listDocuments(
                    collectionId = "[COLLECTION_ID]",
                )
                val json = response.body?.string()        
            }
        }
    }
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    public class MainActivity extends AppCompatActivity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
    
            Client client = new Client(getApplicationContext())
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2"); // Your project ID
    
            Database database = new Database(client);
    
            database.listDocuments(
                "[COLLECTION_ID]", 
                new Continuation<Object>() {
                    @NotNull
                    @Override
                    public CoroutineContext getContext() {
                        return EmptyCoroutineContext.INSTANCE;
                    }
    
                    @Override
                    public void resumeWith(@NotNull Object o) {
                        String json = "";
                        try {
                            if (o instanceof Result.Failure) {
                                Result.Failure failure = (Result.Failure) o;
                                throw failure.exception;
                            } else {
                                Response response = (Response) o;
                                json = response.body().string();
                            }                    
                        } catch (Throwable th) {
                            Log.e("ERROR", th.toString());
                        }
                    }
                }
            );
        }
    }

Get Document

GET/v1/database/collections/{collectionId}/documents/{documentId}

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

HTTP Request

Name Type Description
collectionId required string

Collection ID. You can create a new collection using the Database service server integration.

documentId required string

Document ID.

HTTP Response

Status Code Content Type Payload
200  OK application/json Document Object
Example Request
  • const sdk = new Appwrite();
    
    sdk
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    let promise = sdk.database.getDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Database database = Database(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = database.getDocument(
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    func main() async throws {
        let client = Client()
          .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
          .setProject("5df5acd0d48c2") // Your project ID
        let database = Database(client)
        let document = try await database.getDocument(
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]"
        )
    
        print(String(describing: document)
    }
    
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    class MainActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_main)
    
            val client = Client(applicationContext)
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2") // Your project ID
    
            val database = Database(client)
    
            GlobalScope.launch {
                val response = database.getDocument(
                    collectionId = "[COLLECTION_ID]",
                    documentId = "[DOCUMENT_ID]"
                )
                val json = response.body?.string()        
            }
        }
    }
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    public class MainActivity extends AppCompatActivity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
    
            Client client = new Client(getApplicationContext())
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2"); // Your project ID
    
            Database database = new Database(client);
    
            database.getDocument(
                "[COLLECTION_ID]", 
                "[DOCUMENT_ID]"
                new Continuation<Object>() {
                    @NotNull
                    @Override
                    public CoroutineContext getContext() {
                        return EmptyCoroutineContext.INSTANCE;
                    }
    
                    @Override
                    public void resumeWith(@NotNull Object o) {
                        String json = "";
                        try {
                            if (o instanceof Result.Failure) {
                                Result.Failure failure = (Result.Failure) o;
                                throw failure.exception;
                            } else {
                                Response response = (Response) o;
                                json = response.body().string();
                            }                    
                        } catch (Throwable th) {
                            Log.e("ERROR", th.toString());
                        }
                    }
                }
            );
        }
    }

Update Document

PATCH/v1/database/collections/{collectionId}/documents/{documentId}

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

HTTP Request

Name Type Description
collectionId required string

Collection ID.

documentId required string

Document ID.

data required object

Document data as JSON object. Include only attribute and value pairs to be updated.

read optional array

An array of strings with read permissions. By default inherits the existing read permissions. learn more about permissions and get a full list of available permissions.

write optional array

An array of strings with write permissions. By default inherits the existing write permissions. learn more about permissions and get a full list of available permissions.

HTTP Response

Status Code Content Type Payload
200  OK application/json Document Object
Example Request
  • const sdk = new Appwrite();
    
    sdk
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    let promise = sdk.database.updateDocument('[COLLECTION_ID]', '[DOCUMENT_ID]', {});
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Database database = Database(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = database.updateDocument(
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
        data: {},
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    func main() async throws {
        let client = Client()
          .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
          .setProject("5df5acd0d48c2") // Your project ID
        let database = Database(client)
        let document = try await database.updateDocument(
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]",
            data: 
        )
    
        print(String(describing: document)
    }
    
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    class MainActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_main)
    
            val client = Client(applicationContext)
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2") // Your project ID
    
            val database = Database(client)
    
            GlobalScope.launch {
                val response = database.updateDocument(
                    collectionId = "[COLLECTION_ID]",
                    documentId = "[DOCUMENT_ID]",
                    data = mapOf( "a" to "b" ),
                )
                val json = response.body?.string()        
            }
        }
    }
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    public class MainActivity extends AppCompatActivity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
    
            Client client = new Client(getApplicationContext())
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2"); // Your project ID
    
            Database database = new Database(client);
    
            database.updateDocument(
                "[COLLECTION_ID]", 
                "[DOCUMENT_ID]", 
                mapOf( "a" to "b" ), 
                new Continuation<Object>() {
                    @NotNull
                    @Override
                    public CoroutineContext getContext() {
                        return EmptyCoroutineContext.INSTANCE;
                    }
    
                    @Override
                    public void resumeWith(@NotNull Object o) {
                        String json = "";
                        try {
                            if (o instanceof Result.Failure) {
                                Result.Failure failure = (Result.Failure) o;
                                throw failure.exception;
                            } else {
                                Response response = (Response) o;
                                json = response.body().string();
                            }                    
                        } catch (Throwable th) {
                            Log.e("ERROR", th.toString());
                        }
                    }
                }
            );
        }
    }

Delete Document

DELETE/v1/database/collections/{collectionId}/documents/{documentId}

Delete a document by its unique ID.

HTTP Request

Name Type Description
collectionId required string

Collection ID. You can create a new collection using the Database service server integration.

documentId required string

Document ID.

HTTP Response

Status Code Content Type Payload
204  No Content - -
Example Request
  • const sdk = new Appwrite();
    
    sdk
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    let promise = sdk.database.deleteDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Database database = Database(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = database.deleteDocument(
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    func main() async throws {
        let client = Client()
          .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
          .setProject("5df5acd0d48c2") // Your project ID
        let database = Database(client)
        let result = try await database.deleteDocument(
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]"
        )
    
        print(String(describing: result)
    }
    
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    class MainActivity : AppCompatActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_main)
    
            val client = Client(applicationContext)
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2") // Your project ID
    
            val database = Database(client)
    
            GlobalScope.launch {
                val response = database.deleteDocument(
                    collectionId = "[COLLECTION_ID]",
                    documentId = "[DOCUMENT_ID]"
                )
                val json = response.body?.string()        
            }
        }
    }
  • import androidx.appcompat.app.AppCompatActivity
    import android.os.Bundle
    import kotlinx.coroutines.GlobalScope
    import kotlinx.coroutines.launch
    import io.appwrite.Client
    import io.appwrite.services.Database
    
    public class MainActivity extends AppCompatActivity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
    
            Client client = new Client(getApplicationContext())
                .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
                .setProject("5df5acd0d48c2"); // Your project ID
    
            Database database = new Database(client);
    
            database.deleteDocument(
                "[COLLECTION_ID]", 
                "[DOCUMENT_ID]"
                new Continuation<Object>() {
                    @NotNull
                    @Override
                    public CoroutineContext getContext() {
                        return EmptyCoroutineContext.INSTANCE;
                    }
    
                    @Override
                    public void resumeWith(@NotNull Object o) {
                        String json = "";
                        try {
                            if (o instanceof Result.Failure) {
                                Result.Failure failure = (Result.Failure) o;
                                throw failure.exception;
                            } else {
                                Response response = (Response) o;
                                json = response.body().string();
                            }                    
                        } catch (Throwable th) {
                            Log.e("ERROR", th.toString());
                        }
                    }
                }
            );
        }
    }