Database operators

Database operators let you update fields directly on the server without fetching the full row. Instead of sending new values, you describe the action you want: increment, append, replace, or adjust. This eliminates race conditions and reduces bandwidth usage when updating any values that need to be modified atomically. The operation is applied atomically at the storage layer for safe, concurrent updates.

• Atomic by field: Each operation is applied safely at the storage layer to prevent lost updates under concurrency.
• Multi-field updates: Apply multiple operations across different fields in a single request or transaction.
• Type-safe: Operators are exposed through typed SDK methods for clarity and safety.
• Transaction-ready: Operators can be staged and committed alongside other database actions for consistent writes.

How database operators work

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

Let's take an example of appending a value to an array field.

Traditional approach:

1. Fetch row → { letters: ['a', 'b' ] }
2. Update client-side → letters: ['a', 'b', 'c']
3. Write back → { letters: ['a', 'b', 'c'] }

Operator approach:

1. Update/upsert the row with the appropriate value to append
2. Server applies atomically → letters: ['a', 'b', 'c']

Here's how you can do so programmatically:

When to use database operators

Use operators when you need to:

• Update fields frequently under concurrency (likes, scores, credits, inventory)
• Edit lists/tags without rewriting whole arrays
• Make small text changes in-place
• Adjust dates for lifecycle events or scheduling

This keeps payloads small, avoids race conditions, and reduces round-trips.

Operator categories

The following operators are available, grouped by field type. Each operator updates the given column atomically on the server.

Numeric operators

Perform arithmetic on numeric fields without reading the row first.

increment

Increase a numeric field by a specified value. Optionally cap the result at a maximum value.

decrement

Decrease a numeric field by a specified value. Optionally cap the result at a minimum value.

multiply

Multiply a numeric field by a specified factor. Optionally cap the result at a maximum value.

divide

Divide a numeric field by a specified divisor. Optionally cap the result at a minimum value. Divisor cannot be zero.

modulo

Set a numeric field to the remainder of itself divided by a specified value.

power

Raise a numeric field to a specified exponent. Optionally cap the result at a maximum value.

Array operators

Edit lists in place: append, remove, or modify array items atomically.

arrayAppend

Add one or more elements to the end of an array.

arrayPrepend

Add one or more elements to the beginning of an array.

arrayInsert

Insert an element at a specific index in an array.

arrayRemove

Remove a specified element from an array.

arrayUnique

Remove duplicate elements from an array.

arrayIntersect

Keep only elements that exist in both arrays.

arrayDiff

Return elements that exist in the current array but not in the provided array.

arrayFilter

Filter array elements based on a condition.

String operators

Make lightweight text changes without rewriting the whole row.

stringConcat

Concatenate a value to a string or array field.

stringReplace

Replace occurrences of a substring with a new string.

Date operators

Adjust time-based fields for lifecycle and scheduling logic.

dateAddDays

Add a specified number of days to a date field.

dateSubDays

Subtract a specified number of days from a date field.

dateSetNow

Set a date field to the current time on the server.

Boolean operators

Toggle boolean values in place.

toggle

Toggle a boolean field between true and false.