Documents_

Create, read, update, and delete documents in Appwrite DocumentsDB. Learn how to work with schemaless JSON documents in your collections.

2 min read

Raw

Each piece of data in Appwrite DocumentsDB is a document. Documents are schemaless JSON, so each document in a collection can hold its own set of fields.

Create documents

Permissions required

You must grant create permissions to users at the collection level before users can create documents. Learn more about permissions

Use the createDocument method to add a document to a collection. Appwrite Server SDKs require an API key.

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const documentsDB = new sdk.DocumentsDB(client);

const result = await documentsDB.createDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: sdk.ID.unique(),
    data: { title: 'Hamlet', year: 1601 },
    permissions: [sdk.Permission.read(sdk.Role.any())] // optional
});

Get document

Use the getDocument method to read a single document by its ID.

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const documentsDB = new sdk.DocumentsDB(client);

const result = await documentsDB.getDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>'
});

List documents

Use the listDocuments method to read documents from a collection. Pass queries to filter, order, and paginate the results.

Cache list responses

Pass a ttl value in seconds (1 to 86400) to cache the response. Identical requests return the cached result until the TTL expires, and the X-Appwrite-Cache header reports hit or miss. See cache list responses.

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const documentsDB = new sdk.DocumentsDB(client);

const result = await documentsDB.listDocuments({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    queries: [
        sdk.Query.equal('title', 'Hamlet')
    ]
});

Update document

Use the updateDocument method to update a document. With the patch behavior, you only pass the fields you want to change.

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const documentsDB = new sdk.DocumentsDB(client);

const result = await documentsDB.updateDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    data: { year: 1602 }
});

Upsert documents

Use the upsertDocument method to create a document if it doesn't exist, or update it if it does.

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const documentsDB = new sdk.DocumentsDB(client);

const result = await documentsDB.upsertDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    data: { title: 'Hamlet', year: 1603 }
});

Delete document

Use the deleteDocument method to remove a document from a collection.

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const documentsDB = new sdk.DocumentsDB(client);

const result = await documentsDB.deleteDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>'
});

Permissions

To access documents through a Client SDK, you must grant the relevant permissions. By default, Appwrite doesn't grant any user permissions when a new collection is created.

You can configure permissions at the collection level, or enable documentSecurity on the collection to also set permissions on individual documents.

Learn about configuring permissions.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.