Docs

Database API

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. The Appwrite database service also allows you to nest child documents in parent documents and use deep filters to both search and query your data.

Each database document structure in your project is defined using the Appwrite collection rules. The collections rules 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 document in your project for either a specific user, team, user role, or even grant it with public access (*). You can learn more about how Appwrite handles permissions and access control.

Edit on GitHub

In this page

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.

Edit on GitHub

Request

Name		Type	Description
collectionId	required	string	Collection unique ID. You can create a new collection with validation rules using the Database service server integration.
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.
parentDocument	optional	string	Parent document unique ID. Use when you want your new document to be a child of a parent document.
parentProperty	optional	string	Parent document property name. Use when you want your new document to be a child of a parent document.
parentPropertyType	optional	string	Parent document property connection type. You can set this value to assign, append or prepend, default value is assign. Use when you want your new document to be a child of a parent document.

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]', {});

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]',
    data: {},
  );

  result
    .then((response) {
      print(response);
    }).catchError((error) {
      print(error.response);
  });
}

import Appwrite

func main() {
    let client = Client()
      .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
      .setProject("5df5acd0d48c2") // Your project ID

    let database = Database(client)
    database.createDocument(
        collectionId: "[COLLECTION_ID]",
        data: 
    ) { result in
        switch result {
        case .failure(let error):
            print(error.message)
        case .success(let document):
            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]",
                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]", 
            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.

Edit on GitHub

Request

Name		Type	Description
collectionId	required	string	Collection unique ID. You can create a new collection with validation rules using the Database service server integration.
filters	optional	array	Array of filter strings. Each filter is constructed from a key name, comparison operator (=, !=, >, <, <=, >=) and a value. You can also use a dot (.) separator in attribute names to filter by child document attributes. Examples: 'name=John Doe' or 'category.$id>=5bed2d152c362'.
limit	optional	integer	Maximum number of documents to return in response. Use this value to manage pagination. 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 param to manage pagination.
orderField	optional	string	Document field that results will be sorted by.
orderType	optional	string	Order direction. Possible values are DESC for descending order, or ASC for ascending order.
orderCast	optional	string	Order field type casting. Possible values are int, string, date, time or datetime. The database will attempt to cast the order field to the value you pass here. The default value is a string.
search	optional	string	Search query. Enter any free text search. The database will try to find a match against all document attributes and children. Max length: 256 chars.

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() {
    let client = Client()
      .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
      .setProject("5df5acd0d48c2") // Your project ID

    let database = Database(client)
    database.listDocuments(
        collectionId: "[COLLECTION_ID]"
    ) { result in
        switch result {
        case .failure(let error):
            print(error.message)
        case .success(let documentList):
            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.

Edit on GitHub

Request

Name		Type	Description
collectionId	required	string	Collection unique ID. You can create a new collection with validation rules using the Database service server integration.
documentId	required	string	Document unique ID.

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() {
    let client = Client()
      .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
      .setProject("5df5acd0d48c2") // Your project ID

    let database = Database(client)
    database.getDocument(
        collectionId: "[COLLECTION_ID]",
        documentId: "[DOCUMENT_ID]"
    ) { result in
        switch result {
        case .failure(let error):
            print(error.message)
        case .success(let document):
            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.

Edit on GitHub

Request

Name		Type	Description
collectionId	required	string	Collection unique ID. You can create a new collection with validation rules using the Database service server integration.
documentId	required	string	Document unique ID.
data	required	object	Document data as JSON object.
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.

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() {
    let client = Client()
      .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
      .setProject("5df5acd0d48c2") // Your project ID

    let database = Database(client)
    database.updateDocument(
        collectionId: "[COLLECTION_ID]",
        documentId: "[DOCUMENT_ID]",
        data: 
    ) { result in
        switch result {
        case .failure(let error):
            print(error.message)
        case .success(let document):
            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. This endpoint deletes only the parent documents, its attributes and relations to other documents. Child documents will not be deleted.

Edit on GitHub

Request

Name		Type	Description
collectionId	required	string	Collection unique ID. You can create a new collection with validation rules using the Database service server integration.
documentId	required	string	Document unique ID.

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() {
    let client = Client()
      .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
      .setProject("5df5acd0d48c2") // Your project ID

    let database = Database(client)
    database.deleteDocument(
        collectionId: "[COLLECTION_ID]",
        documentId: "[DOCUMENT_ID]"
    ) { result in
        switch result {
        case .failure(let error):
            print(error.message)
        case .success(let ):
            print(String(describing: )
        }
    }
}

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());
                    }
                }
            }
        );
    }
}