---
title: "Atomic Field Update"
method: PATCH
path: "/v0/logs/{log_id}/fields/{field_name}/atomic"
tags: ["Logs"]
---

# Atomic Field Update

`PATCH /v0/logs/{log_id}/fields/{field_name}/atomic`

Apply an atomic operation to a numeric field in a log entry.

This endpoint performs race-safe atomic updates directly in PostgreSQL,
ensuring correct results even under high concurrent load.

Supported operations:
- `+N`: Add N to the current value
- `-N`: Subtract N from the current value
- `*N`: Multiply the current value by N
- `/N`: Divide the current value by N

If the field doesn't exist or is NULL, it is treated as 0 before the operation.

## Path parameters

- `log_id` integer, required — The ID of the log to update
- `field_name` string, required — The name of the field to update atomically

## Request body

- AtomicFieldUpdateRequest — Request model for atomic field operations that are race-safe under concurrent updates. This endpoint supports two modes: 1. Update mode (default): Updates an existing log entry by log_id 2. Upsert mode: When project/context/unique_keys/initial_data are provided, finds or creates a log entry by unique keys, then applies the atomic operation. Upsert mode uses advisory locks to handle concurrent first inserts safely.
  - `operation` string, required — Atomic operation to apply. Supported formats: +N, -N, *N, /N where N is a number.
  - `field` string, nullable — (Upsert mode) Name of the numeric field to update atomically.
  - `project` string, nullable — (Upsert mode) Name of the project.
  - `context` string, nullable — (Upsert mode) Context path for the log.
  - `unique_keys` object, nullable — (Upsert mode) Unique key configuration for the context. Maps key names to types (str, int, float).
  - `initial_data` object, nullable — (Upsert mode) Data to use when creating a new log entry. Must include all unique key values.
  - `add_to_all_context` boolean — (Upsert mode) If true, also adds the log to the 'All/*' archive context.

## Response `200`

Atomic operation applied successfully

- AtomicFieldUpdateResponse — Response from atomic field update operation.
  - `new_value` number, required — The new value of the field after the operation.
  - `log_id` integer, nullable — ID of the log entry (included in upsert mode).
  - `created` boolean, nullable — True if a new log was created (upsert mode only).
  - `mirrored_contexts` string[], nullable — List of archive contexts the log was mirrored to (upsert mode only).

## Other responses

- `400` — Invalid operation format
- `404` — Log not found
- `422` — Validation Error

---

[API](https://skmtc.dev/unify/apis/unifyai-http-api-reference.md) · [All operations](https://skmtc.dev/unify/apis/unifyai-http-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/unify/unifyai-http-api-reference/revisions/900377f918b6/schema)