What is the Appwrite Bulk API?

The Bulk API lets you create, update, upsert, or delete many documents in a single request using `createDocuments`, `updateDocuments`, `upsertDocuments`, and `deleteDocuments`. It is much faster than sending one request per document and reduces network overhead for batch workloads.

Why is the Bulk API restricted to server-side SDKs?

Bulk operations typically involve high-volume data changes that should be authorized by trusted code, not by end users. Restricting the API to server SDKs (which use API keys) prevents clients from issuing mass writes or deletes against your project.

When should I use the Bulk API instead of single-document calls?

Reach for the Bulk API any time you are processing data in batches: importing CSV files, syncing from another database, applying changes from a scheduled job, or cleaning up stale records. For interactive UI writes (one document at a time), the regular methods are usually clearer.

How does Appwrite handle partial failures in a bulk request?

Bulk operations are transactional at the document level, so individual document validations (such as permissions or schema mismatches) are reported alongside successes. Check the response to see which documents were processed and which failed, then retry only the failures.

Are there limits on how many documents I can send in one bulk call?

Yes. There is a maximum batch size per request that depends on payload size and the underlying database engine. The [bulk operations documentation](/docs/products/databases/bulk-operations) lists the current limits and recommended batch sizes for large imports.

Does Bulk API work with self-hosted Appwrite?

Yes. Bulk API is available on both Appwrite Cloud and self-hosted installations that run the supporting version. You call the same methods from your server SDK regardless of where Appwrite is hosted.

Announcing Bulk API: Handle heavy data workloads with ease

We're excited to introduce another Appwrite Databases feature, Bulk API. Explicitly designed to handle heavy write workloads, Bulk API dramatically improves performance by allowing multiple database operations in a single API call.

Faster development with bulk actions

Previously, writing or modifying large amounts of data in Appwrite Databases required sending one request per document. This method was inefficient, slow, and resource-intensive, especially when dealing with thousands of records.

With the new Bulk API, you can create, update, or delete multiple documents in one go, vastly speeding up your workflows and reducing network overhead.

Optimized for server-side workloads

Bulk API is crafted for server-side applications, particularly those with significant data demands. Whether you’re importing large datasets, performing batch updates, or cleaning out old records, Bulk API streamlines your workload, drastically cutting down the number of requests and enhancing your application's performance.

This will have immediate and impactful benefits such as:

Speed improvements: Rapidly handle thousands of operations simultaneously.
Lower network overhead: Significantly fewer API requests needed, making your application faster and more efficient.
Seamless integration: Works effortlessly using Appwrite Cloud or hosting yourself.

Please Note

Bulk operations can only be performed via the server-side SDKs. The client-side SDKs do not support bulk operations.

How it works

Utilizing the Bulk API is straightforward. You can use it to:

Create multiple documents in a single request using the createDocuments method
Update multiple documents in a single request using the updateDocuments method
Delete multiple documents in a single request using the deleteDocuments method
Upsert multiple documents in a single request using the upsertDocuments method

Here is a code example for creating multiple documents in a single request:

Node.js

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

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

const databases = new sdk.Databases(client);

const result = await databases.createDocuments(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    [
        {
            $id: sdk.ID.unique(),
            name: 'Document 1',
        },
        {
            $id: sdk.ID.unique(),
            name: 'Document 2',
        }
    ]
);

Built for intensive data tasks

Bulk API was designed to move large volumes of data in and out of Appwrite. By simplifying and speeding up these tasks, Bulk API unlocks previously challenging use-cases, expanding what's possible with Appwrite.

With Bulk API, your high-performance data operations are faster, simpler, and more efficient.