Go to Console
Star on GitHub 45.1K Get started

Databases

CLIENT

The Databases 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 data returned by the Databases service are represented as structured JSON documents.

The Databases service can contain multiple databases, each database can contain multiple collections. A collection is a group of similarly structured documents. The accepted structure of documents is defined by 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 (any). You can learn more about how Appwrite handles permissions and access control.

Base URL
https://cloud.appwrite.io/v1

List Documents

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

  • Request
    • databaseId string
      required

      Database ID.

    • collectionId string
      required

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

    • queries 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 4096 characters long.

    • limit integer

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

    • cursor 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 string

      Direction of the cursor, can be either 'before' or 'after'.

    • orderAttributes array

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

    • orderTypes 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.

  • Response
Endpoint
GET /databases/{databaseId}/collections/{collectionId}/documents
Flutter
import 'package:appwrite/appwrite.dart';

void main() { // Init SDK
  Client client = Client();
  Databases databases = Databases(client, databaseId: '[DATABASE_ID]');

  client
    .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
    .setProject('5df5acd0d48c2') // Your project ID
  ;
  Future result = databases.listDocuments(
    collectionId: '[COLLECTION_ID]',
  );

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

Create Document

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.

  • Request
    • databaseId string
      required

      Database ID.

    • collectionId string
      required

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

    • documentId string
      required

      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 object
      required

      Document data as JSON object.

    • read 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 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.

  • Response
Endpoint
POST /databases/{databaseId}/collections/{collectionId}/documents
Flutter
import 'package:appwrite/appwrite.dart';

void main() { // Init SDK
  Client client = Client();
  Databases databases = Databases(client, databaseId: '[DATABASE_ID]');

  client
    .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
    .setProject('5df5acd0d48c2') // Your project ID
  ;
  Future result = databases.createDocument(
    collectionId: '[COLLECTION_ID]',
    documentId: '[DOCUMENT_ID]',
    data: {},
  );

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

Get Document

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

  • Request
    • databaseId string
      required

      Database ID.

    • collectionId string
      required

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

    • documentId string
      required

      Document ID.

  • Response
Endpoint
GET /databases/{databaseId}/collections/{collectionId}/documents/{documentId}
Flutter
import 'package:appwrite/appwrite.dart';

void main() { // Init SDK
  Client client = Client();
  Databases databases = Databases(client, databaseId: '[DATABASE_ID]');

  client
    .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
    .setProject('5df5acd0d48c2') // Your project ID
  ;
  Future result = databases.getDocument(
    collectionId: '[COLLECTION_ID]',
    documentId: '[DOCUMENT_ID]',
  );

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

Update Document

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

  • Request
    • databaseId string
      required

      Database ID.

    • collectionId string
      required

      Collection ID.

    • documentId string
      required

      Document ID.

    • data object

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

    • read 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 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
Endpoint
PATCH /databases/{databaseId}/collections/{collectionId}/documents/{documentId}
Flutter
import 'package:appwrite/appwrite.dart';

void main() { // Init SDK
  Client client = Client();
  Databases databases = Databases(client, databaseId: '[DATABASE_ID]');

  client
    .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
    .setProject('5df5acd0d48c2') // Your project ID
  ;
  Future result = databases.updateDocument(
    collectionId: '[COLLECTION_ID]',
    documentId: '[DOCUMENT_ID]',
  );

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

Delete Document

Delete a document by its unique ID.

  • Request
    • databaseId string
      required

      Database ID.

    • collectionId string
      required

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

    • documentId string
      required

      Document ID.

  • Response
    • 204 application/json
Endpoint
DELETE /databases/{databaseId}/collections/{collectionId}/documents/{documentId}
Flutter
import 'package:appwrite/appwrite.dart';

void main() { // Init SDK
  Client client = Client();
  Databases databases = Databases(client, databaseId: '[DATABASE_ID]');

  client
    .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
    .setProject('5df5acd0d48c2') // Your project ID
  ;
  Future result = databases.deleteDocument(
    collectionId: '[COLLECTION_ID]',
    documentId: '[DOCUMENT_ID]',
  );

  result
    .then((response) {
      print(response);
    }).catchError((error) {
      print(error.response);
  });
}
Copyright © 2024 Appwrite