Appwrite.Services.Database (appwrite v1.0.0)

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.

Summary

Functions

create_document(database_id, collection_id, document_id, data \\ nil, permissions \\ nil, transaction_id \\ nil)

Create a new Document.

create_operations(transaction_id, operations \\ nil)

Create multiple Operations inside a Transaction in one request.

create_transaction(ttl \\ nil)

Create a new Transaction.

decrement_document_attribute(database_id, collection_id, document_id, attribute, value \\ nil, min \\ nil, transaction_id \\ nil)

Atomically decrement a numeric attribute on a document.

delete_document(database_id, collection_id, document_id, transaction_id \\ nil)

Delete a Document by its unique ID.

delete_transaction(transaction_id)

Delete a Transaction by its unique ID.

get_document(database_id, collection_id, document_id, queries \\ nil, transaction_id \\ nil)

Get a Document by its unique ID.

get_transaction(transaction_id)

Get a Transaction by its unique ID.

increment_document_attribute(database_id, collection_id, document_id, attribute, value \\ nil, max \\ nil, transaction_id \\ nil)

Atomically increment a numeric attribute on a document.

list_documents(database_id, collection_id, queries \\ nil, transaction_id \\ nil, total \\ nil, ttl \\ nil)

List Documents in a collection.

list_transactions(queries \\ nil)

List Transactions across all databases.

update_document(database_id, collection_id, document_id, data \\ nil, permissions \\ nil, transaction_id \\ nil)

Update a Document by its unique ID.

update_transaction(transaction_id, commit \\ nil, rollback \\ nil)

Update (commit or rollback) a Transaction.

upsert_document(database_id, collection_id, document_id, data \\ nil, permissions \\ nil, transaction_id \\ nil)

Upsert a Document (create or update atomically).

Functions

create_document(database_id, collection_id, document_id, data \\ nil, permissions \\ nil, transaction_id \\ nil)

@spec create_document(
  String.t(),
  String.t(),
  String.t(),
  map() | nil,
  [String.t()] | nil,
  String.t() | nil
) :: {:ok, map()} | {:error, any()}

Create a new Document.

Parameters

database_id (required)
collection_id (required)
document_id (required) – use ID.unique() for auto-generation
data (optional) – document payload map
permissions (optional) – list of permission strings
transaction_id (optional) – stage inside an existing transaction

create_operations(transaction_id, operations \\ nil)

@spec create_operations(String.t(), [map()] | nil) :: {:ok, map()} | {:error, any()}

Create multiple Operations inside a Transaction in one request.

Parameters

transaction_id (required)
operations (optional) – list of operation maps

create_transaction(ttl \\ nil)

@spec create_transaction(integer() | nil) :: {:ok, map()} | {:error, any()}

Create a new Transaction.

Parameters

ttl (optional) – seconds before the transaction expires

decrement_document_attribute(database_id, collection_id, document_id, attribute, value \\ nil, min \\ nil, transaction_id \\ nil)

@spec decrement_document_attribute(
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  number() | nil,
  number() | nil,
  String.t() | nil
) :: {:ok, map()} | {:error, any()}

Atomically decrement a numeric attribute on a document.

Parameters

database_id (required)
collection_id (required)
document_id (required)
attribute (required) – the attribute key to decrement
value (optional) – amount to decrement by
min (optional) – lower floor; exception thrown if breached
transaction_id (optional)

delete_document(database_id, collection_id, document_id, transaction_id \\ nil)

@spec delete_document(String.t(), String.t(), String.t(), String.t() | nil) ::
  {:ok, map()} | {:error, any()}

Delete a Document by its unique ID.

Parameters

database_id (required)
collection_id (required)
document_id (required)
transaction_id (optional)

delete_transaction(transaction_id)

@spec delete_transaction(String.t()) :: {:ok, map()} | {:error, any()}

Delete a Transaction by its unique ID.

Parameters

transaction_id (required)

get_document(database_id, collection_id, document_id, queries \\ nil, transaction_id \\ nil)

@spec get_document(
  String.t(),
  String.t(),
  String.t(),
  [String.t()] | nil,
  String.t() | nil
) ::
  {:ok, map()} | {:error, any()}

Get a Document by its unique ID.

Parameters

database_id (required)
collection_id (required)
document_id (required)
queries (optional)
transaction_id (optional) – read uncommitted changes within a transaction

get_transaction(transaction_id)

@spec get_transaction(String.t()) :: {:ok, map()} | {:error, any()}

Get a Transaction by its unique ID.

Parameters

transaction_id (required)

increment_document_attribute(database_id, collection_id, document_id, attribute, value \\ nil, max \\ nil, transaction_id \\ nil)

@spec increment_document_attribute(
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  number() | nil,
  number() | nil,
  String.t() | nil
) :: {:ok, map()} | {:error, any()}

Atomically increment a numeric attribute on a document.

Parameters

database_id (required)
collection_id (required)
document_id (required)
attribute (required) – the attribute key to increment
value (optional) – amount to increment by
max (optional) – upper cap; error thrown if exceeded
transaction_id (optional)

list_documents(database_id, collection_id, queries \\ nil, transaction_id \\ nil, total \\ nil, ttl \\ nil)

@spec list_documents(
  String.t(),
  String.t(),
  [String.t()] | nil,
  String.t() | nil,
  boolean() | nil,
  integer() | nil
) :: {:ok, map()} | {:error, any()}

List Documents in a collection.

Parameters

database_id (required)
collection_id (required)
queries (optional)
transaction_id (optional)
total (optional) – when false, skips count calculation
ttl (optional) – cache TTL in seconds (0–86400) for select queries

list_transactions(queries \\ nil)

@spec list_transactions([String.t()] | nil) :: {:ok, map()} | {:error, any()}

List Transactions across all databases.

Parameters

queries (optional)

update_document(database_id, collection_id, document_id, data \\ nil, permissions \\ nil, transaction_id \\ nil)

@spec update_document(
  String.t(),
  String.t(),
  String.t(),
  map() | nil,
  [String.t()] | nil,
  String.t() | nil
) :: {:ok, map()} | {:error, any()}

Update a Document by its unique ID.

Parameters

database_id (required)
collection_id (required)
document_id (required)
data (optional) – fields to update
permissions (optional)
transaction_id (optional)

update_transaction(transaction_id, commit \\ nil, rollback \\ nil)

@spec update_transaction(String.t(), boolean() | nil, boolean() | nil) ::
  {:ok, map()} | {:error, any()}

Update (commit or rollback) a Transaction.

Parameters

transaction_id (required)
commit (optional) – pass true to commit
rollback (optional) – pass true to rollback

upsert_document(database_id, collection_id, document_id, data \\ nil, permissions \\ nil, transaction_id \\ nil)

@spec upsert_document(
  String.t(),
  String.t(),
  String.t(),
  map() | nil,
  [String.t()] | nil,
  String.t() | nil
) :: {:ok, map()} | {:error, any()}

Upsert a Document (create or update atomically).

Parameters

database_id (required)
collection_id (required)
document_id (required)
data (optional)
permissions (optional)
transaction_id (optional)