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 operators work

Instead of the traditional read-modify-write pattern, 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 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.

Available operators

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

Numeric

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

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

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

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

Toggle boolean values in place.

toggle

Toggle a boolean field between true and false.

Examples

The following examples will demonstrate how you can use operators in different situations

Update the count of upvotes on a post

This example demonstrates using the increment operator to atomically increase the upvote count on a post.

Add a book to a list

This example demonstrates using the arrayAppend operator to add a new book to an existing array of books.

Update the date field in a deletion table

This example demonstrates using the dateAddDays operator to set a scheduled deletion date 30 days from now.

Update a single row in a transaction

This example demonstrates combining multiple operators (increment and dateSetNow) in a single transaction to ensure atomic updates.

Update multiple rows in a transaction

This example demonstrates using createOperations to update multiple rows across different tables atomically, combining date and array operators in a single transaction.