---
layout: article
title: Start with DocumentsDB
description: Get started with Appwrite DocumentsDB. Follow a step-by-step guide to create your first database, add a collection, and perform basic document operations.
---

## 1. Create database

Head to your [Appwrite Console](https://cloud.appwrite.io/console/) and click **Create database**. Name it `Oscar` and choose **DocumentsDB** as the database type.
Optionally, add a custom database ID. Select your preferred tier, then click **Create database**.

## 2. Create collection

![Create collection dialog](/images/docs/databases/documentsdb/create-collection.avif)
In the `Oscar` database, click **Create collection** and name it `My books`. Optionally, add a custom collection ID.

Collections are schemaless, so there are no columns to define. Each document holds its own fields as flexible JSON.

Open the collection's **Security** tab. Under **Permissions**, add a new role **Any** and check **Create** and **Read**, so anyone can create and read documents. Click **Update** to save.

## 3. Create documents

To create a document use the `createDocument` method.

In the **Settings** menu, find your project ID and replace `<PROJECT_ID>` in the example.

Navigate to the `Oscar` database, copy the database ID, and replace `<DATABASE_ID>`.
Then, in the `My books` collection, copy the collection ID, and replace `<COLLECTION_ID>`.

```client-web
import { Client, ID, DocumentsDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const documentsDB = new DocumentsDB(client);

const promise = documentsDB.createDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: ID.unique(),
    data: { title: "Hamlet" }
});

promise.then(function (response) {
    console.log(response);
}, function (error) {
    console.log(error);
});
```
```client-flutter
import 'package:appwrite/appwrite.dart';

void main() async {
    final client = Client()
        .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
        .setProject('<PROJECT_ID>');

    final documentsDB = DocumentsDB(client);

    try {
        final document = documentsDB.createDocument(
            databaseId: '<DATABASE_ID>',
            collectionId: '<COLLECTION_ID>',
            documentId: ID.unique(),
            data: { "title": "Hamlet" }
        );
    } on AppwriteException catch(e) {
        print(e);
    }
}
```
```client-apple
import Appwrite
import AppwriteModels

func main() async throws {
    let client = Client()
        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
        .setProject("<PROJECT_ID>")

    let documentsDB = DocumentsDB(client)

    do {
        let document = try await documentsDB.createDocument(
            databaseId: "<DATABASE_ID>",
            collectionId: "<COLLECTION_ID>",
            documentId: ID.unique(),
            data: ["title": "Hamlet"]
        )
    } catch {
        print(error.localizedDescription)
    }
}
```
```client-android-kotlin
import io.appwrite.Client
import io.appwrite.ID
import io.appwrite.services.DocumentsDB

suspend fun main() {
    val client = Client(applicationContext)
        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
        .setProject("<PROJECT_ID>")

    val documentsDB = DocumentsDB(client)

    try {
        val document = documentsDB.createDocument(
            databaseId = "<DATABASE_ID>",
            collectionId = "<COLLECTION_ID>",
            documentId = ID.unique(),
            data = mapOf("title" to "Hamlet"),
        )
    } catch (e: Exception) {
        Log.e("Appwrite", "Error: " + e.message)
    }
}
```

The response should look similar to this.

```json
{
    "title": "Hamlet",
    "$id": "6a423aa70000c39da0be",
    "$sequence": "019f12b5-1c89-7094-8d12-5b7e7a09f025",
    "$permissions": [],
    "$createdAt": "2026-06-29T09:28:07.047+00:00",
    "$updatedAt": "2026-06-29T09:28:07.047+00:00",
    "$databaseId": "650125c64b3c25ce4bc4",
    "$collectionId": "650125cff227cf9f95ad"
}
```

![The My books collection with a document selected](/images/docs/databases/documentsdb/collection-documents.avif)

## 4. List documents

To read and query data from your collection, use the `listDocuments` endpoint.

Like the previous step, replace `<PROJECT_ID>`, `<DATABASE_ID>`, and `<COLLECTION_ID>` with their respective IDs.

```client-web
import { Client, Query, DocumentsDB } from "appwrite";

const client = new Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<PROJECT_ID>")

const documentsDB = new DocumentsDB(client);

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

promise.then(function (response) {
    console.log(response);
}, function (error) {
    console.log(error);
});
```
```client-flutter
import 'package:appwrite/appwrite.dart';

void main() async {
    final client = Client()
        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
        .setProject("<PROJECT_ID>")

    final documentsDB = DocumentsDB(client);

    try {
        final documents = await documentsDB.listDocuments(
            databaseId: '<DATABASE_ID>',
            collectionId: '<COLLECTION_ID>',
            queries: [
                Query.equal('title', 'Hamlet')
            ]
        );
    } on AppwriteException catch(e) {
        print(e);
    }
}
```
```client-apple
import Appwrite
import AppwriteModels

func main() async throws{
    let client = Client()
        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
        .setProject("<PROJECT_ID>")

    let documentsDB = DocumentsDB(client)

    do {
        let documents = try await documentsDB.listDocuments(
            databaseId: "<DATABASE_ID>",
            collectionId: "<COLLECTION_ID>",
            queries: [
                Query.equal("title", value: "Hamlet")
            ]
        )
    } catch {
        print(error.localizedDescription)
    }
}
```
```client-android-kotlin
import io.appwrite.Client
import io.appwrite.Query
import io.appwrite.services.DocumentsDB

suspend fun main() {
    val client = Client(applicationContext)
        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
        .setProject("<PROJECT_ID>")

    val documentsDB = DocumentsDB(client)

    try {
        val documents = documentsDB.listDocuments(
            databaseId = "<DATABASE_ID>",
            collectionId = "<COLLECTION_ID>",
            queries = listOf(
                Query.equal("title", "Hamlet")
            )
        )
    } catch (e: AppwriteException) {
        Log.e("Appwrite", "Error: " + e.message)
    }
}
```