Skip to content

Atomic numeric operations

Atomic numeric operations allow you to safely increase or decrease numeric fields without fetching the full document. This eliminates race conditions and reduces bandwidth usage when updating any numeric values that need to be modified atomically, such as counters, scores, balances, and other fast-moving numeric data.

How atomic operations work

Instead of the traditional read-modify-write pattern, atomic numeric operations use dedicated methods to modify values directly on the server. The server applies the change atomically under concurrency control and returns the new value.

Traditional approach:

  1. Fetch document → { likes: 42 }

  2. Update client-side → likes: 43

  3. Write back → { likes: 43 }

Atomic approach:

  1. Call incrementDocumentAttribute() with the attribute name and the value to increment by

  2. Server applies atomically → likes: 43

When to use atomic operations

Atomic numeric operations work well for:

  • Social features: Likes, follows, comment counts

  • Usage metering: API credits, storage quotas, request limits

  • Game state: Scores, lives, currency, experience points

  • E-commerce: Stock counts, inventory levels

  • Workflow tracking: Retry counts, progress indicators

  • Rate limiting: Request counters, usage tracking

Perform atomic operations

Use the incrementDocumentAttribute and decrementDocumentAttribute methods to perform atomic numeric operations. The server will apply these changes atomically under concurrency control.

Increment a field

Decrement a field

Use the decrementDocumentAttribute method to decrease numeric fields:

Set constraints and bounds

You can set minimum and maximum bounds for individual operations to prevent invalid values. Use the optional min and max parameters to ensure the final value stays within acceptable limits:

Example with constraints

Follow best practices

Use for high-concurrency scenarios

Atomic numeric operations are most beneficial when multiple users or processes might update the same numeric field simultaneously.

Combine with regular updates

For complex updates that include both atomic operations and regular field changes, you'll need to use separate API calls:

Explore related features

Was this page helpful?