Docs

Database

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

All the data in the database service is stored in JSON format. The service also allows you to nest child documents and use advanced filters to search and query the database just like you would with a classic graph database.

By leveraging the database permission management you can assign read or write access to the database documents for a specific user, team, user role or even grant public access to all visitors of your project. You can learn more about how Appwrite handles permissions and role access control.

List Collections

GET/database

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

Arguments

Name Type Description
search optional string

Search term to filter your list results.

limit optional integer

Results limit value. By default will return maximum 25 results. Maximum of 100 results allowed per request.

offset optional integer

Results offset. The default value is 0. Use this param to manage pagination.

orderType optional string

Order result by ASC or DESC order.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.listCollections();
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->listCollections();
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.listCollections();
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Get Collection

GET/database/{collectionId}

Get collection by its unique ID. This endpoint response returns a JSON object with the collection metadata.

Arguments

Name Type Description
collectionId required string

Collection unique ID.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.getCollection('[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->getCollection('[COLLECTION_ID]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.getCollection('[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Create Collection

POST/database

Create a new Collection.

Arguments

Name Type Description
name required string

Collection name.

read optional array

An array of strings with read permissions. Learn more about permissions and roles.

write optional array

An array of strings with write permissions. Learn more about permissions and roles.

rules optional array

Array of rule objects. Each rule define a collection field name, data type and validation

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.createCollection('[NAME]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->createCollection('[NAME]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.createCollection('[NAME]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Update Collection

PUT/database/{collectionId}

Update collection by its unique ID.

Arguments

Name Type Description
collectionId required string

Collection unique ID.

name required string

Collection name.

read optional array

An array of strings with read permissions. Learn more about permissions and roles.

write optional array

An array of strings with write permissions. Learn more about permissions and roles.

rules optional array

Array of rule objects. Each rule define a collection field name, data type and validation

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.updateCollection('[COLLECTION_ID]', '[NAME]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->updateCollection('[COLLECTION_ID]', '[NAME]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.updateCollection('[COLLECTION_ID]', '[NAME]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Delete Collection

DELETE/database/{collectionId}

Delete a collection by its unique ID. Only users with write permissions have access to delete this resource.

Arguments

Name Type Description
collectionId required string

Collection unique ID.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.deleteCollection('[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->deleteCollection('[COLLECTION_ID]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.deleteCollection('[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

List Documents

GET/database/{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 documents. Learn more about different API modes.

Arguments

Name Type Description
collectionId required string

Collection unique ID.

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.$uid>=5bed2d152c362'

offset optional integer

Offset value. Use this value to manage pagination.

limit optional integer

Maximum number of documents to return in response. Use this value to manage pagination.

order-field optional string

Document field that results will be sorted by.

order-type optional string

Order direction. Possible values are DESC for descending order, or ASC for ascending order.

order-cast 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.

first optional integer

Return only first document. Pass 1 for true or 0 for false. The default value is 0.

last optional integer

Return only last document. Pass 1 for true or 0 for false. The default value is 0.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.listDocuments('[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->listDocuments('[COLLECTION_ID]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.listDocuments('[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Get Document

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

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

Arguments

Name Type Description
collectionId required string

Collection unique ID

documentId required string

Document unique ID

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.getDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->getDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.getDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Create Document

POST/database/{collectionId}/documents

Create a new Document.

Arguments

Name Type Description
collectionId required string

Collection unique ID.

data required string

Document data as JSON string.

read optional array

An array of strings with read permissions. Learn more about permissions and roles.

write optional array

An array of strings with write permissions. Learn more about permissions and roles.

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.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.createDocument('[COLLECTION_ID]', '{}');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->createDocument('[COLLECTION_ID]', '{}');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.createDocument('[COLLECTION_ID]', '{}');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Update Document

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

Arguments

Name Type Description
collectionId required string

Collection unique ID

documentId required string

Document unique ID

data required string

Document data as JSON string

read optional array

An array of strings with read permissions. Learn more about permissions and roles.

write optional array

An array of strings with write permissions. Learn more about permissions and roles.

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.updateDocument('[COLLECTION_ID]', '[DOCUMENT_ID]', '{}');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->updateDocument('[COLLECTION_ID]', '[DOCUMENT_ID]', '{}');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.updateDocument('[COLLECTION_ID]', '[DOCUMENT_ID]', '{}');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });

Delete Document

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

Delete document by its unique ID. This endpoint deletes only the parent documents, his attributes and relations to other documents. Child documents will not be deleted.

Arguments

Name Type Description
collectionId required string

Collection unique ID

documentId required string

Document unique ID

Example Request
  • let sdk = new Appwrite();
    
    sdk
        setProject('')
    ;
    
    let promise = sdk.database.deleteDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });
  • <?php
    
    use Appwrite\Client;
    use Appwrite\Services\Database;
    
    $client = new Client();
    
    $client
        setProject('')
        setKey('')
    ;
    
    $database = new Database($client);
    
    $result = $database->deleteDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
  • const sdk = require('node-appwrite');
    
    // Init SDK
    let client = new Database.Client();
    
    let database = new sdk.Database(client);
    
    client
        setProject('')
        setKey('')
    ;
    
    let promise = database.deleteDocument('[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response);
    }, function (error) {
        console.log(error);
    });