Upsert is a database operation that creates a document if it doesn't exist and updates it if it does. It removes the need to check for existence yourself or branch between create and update calls. The server handles both paths atomically in a single request.

How do I use upsert in Appwrite?

Call `upsertDocument` on the [Appwrite Databases](/docs/products/databases) SDK with a database ID, collection ID, document ID, and the data you want to write. If the document with that ID exists, it's updated, otherwise it's created. This works the same across Cloud and self-hosted.

When should I use upsert instead of create or update?

Use upsert when you don't know (or don't care) whether the document already exists, like syncing data from a mobile client, processing a background job, or ingesting events from IoT devices. It removes a round trip and a class of race conditions caused by checking existence before writing.

Is upsert atomic in Appwrite?

Yes, [Appwrite's](/docs/products/databases) upsert is fully atomic: the existence check and the write happen in the same operation on the server. That means two clients calling upsert on the same document ID can't both succeed in creating it, avoiding the classic check-then-write race condition.

Is upsert idempotent?

Calling upsert with the same document ID and payload produces the same final state regardless of how many times the request runs. That makes retries safe, which is useful for unreliable networks, background workers, or anywhere you want at-least-once delivery semantics without duplicate data.

Can I upsert in bulk?

Single-document upsert is available via `upsertDocument`. For larger workloads, look at [Appwrite's Bulk API](/docs/products/databases) and CSV imports, which let you write many documents in one operation. Pick the approach that matches the size and shape of your data.

Announcing Database Upsert: Simplify your database interactions

Working with databases often involves small but repetitive decisions like checking if a document exists, choosing between creating or updating, handling errors that come from guessing wrong. These steps are not difficult on their own, but over time they add complexity to your code and friction to your workflow.

To simplify this, we introduce Database Upsert in Appwrite.

How it works

Upsert allows you to create or update a document using a single API call. If the document does not exist, it is created. If it does, it is updated. You no longer need to write separate logic to check for existence or handle 404 responses. The server handles that for you.

This change removes the need for client-side conditionals, reduces the number of requests between your app and the database, and helps avoid potential race conditions. It is a small shift in how you interact with the database, but one that can make your code cleaner and your application logic easier to follow.

Ideal for multi-client scenarios

Whether you synchronize mobile data, handle background worker processes, or collect data from IoT devices, Database Upsert ensures data consistency. Its fully atomic nature prevents race conditions, keeping your data accurate and consistent, no matter how many clients interact simultaneously.

This brings you immediate benefits such as:

Fewer network calls: Combine GET, POST, and PATCH into a single, efficient API request.
Race-free writes: Ensure atomic operations that prevent conflicts.
Cleaner, simpler code: Reduce branching logic and improve readability.
Idempotency: Safe and easy retries ensure consistent behaviour.

How it works

Implementing Upsert is straightforward and intuitive:

JavaScript

import { Client, Databases } from "appwrite";

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

const databases = new Databases(client);

const result = await databases.upsertDocument(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    '<DOCUMENT_ID>',
    {
        'status': 'succeeded',
        'amount': 4999,
        'currency': 'usd',
        'invoiceId': 'in_1Rd...',
        'checks': ['cvc', 'zip'],
    }
)

Database Upsert was developed to enhance developer productivity and satisfaction, providing a feature that matches or surpasses competitive solutions. Whether using Appwrite Cloud or a self-hosted setup, Database Upsert integrates smoothly into your development workflow.

This feature simplifies your database interactions, enhancing efficiency, reducing complexity, and empowering you to build faster.