> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Data Store

> Creates or atomically patches one durable structured record of a configured record type.

Creates or atomically patches one durable structured record of a configured record type.

## Authentication and enablement

This native tool is off by default. Add it as a configured tool on an agent and select:

* a workspace Data Store record type
* `agent` scope for records shared across that logical agent's task runs and versions, or
  `workspace` scope for records shared with other explicitly configured agents
* whether the write result may return fields marked sensitive

Record type and scope are configuration-only values. The agent cannot redirect a call to another
record type, logical agent, or workspace. A configured record-type contract specializes the record
fields shown to the agent. The contract is resolved live for each decision, so record-type edits
apply to existing configured tools without re-saving them.

## Inputs

* `record`: top-level fields to create or patch for a contract-backed record type; the configured
  tool exposes the contract's typed fields. Contract fields declared as an open `object` are
  presented to function-calling models as JSON-encoded strings and decoded before validation;
  object fields with declared nested properties remain structured objects.
* `record_json`: a non-empty JSON object encoded as a string; required instead of `record` for a
  contract-free record type so function-calling models can reliably provide arbitrary fields
* `key`: required only for a contract-free record type; contract-backed record types derive the key
  from their configured identity fields
* `expected_version` (optional): apply the write only while the stored record is still at this
  version, taken from an earlier read or write result. Use for read-modify-write updates that must
  not overwrite a concurrent change. `0` means the record must not exist yet (create-only). A
  conditional write with a version ≥ 1 never creates a new record: with no stored record to match,
  it is refused.

Identity fields must be present on every contract-backed write. Fields present in the patch are
type-checked. Missing readiness-required fields are accepted.

## Output

Returns the key, merged JSON value, monotonic version, changed field names, `ready`, and
`missing_required_fields`. Sensitive values are replaced with `[REDACTED]` unless sensitive-read
access is enabled. Preserve the returned key for later exact `get` or `readiness` calls,
particularly when a contract uses multiple identity fields or a non-string identity.

A refused `expected_version` write is reported as an outcome, not an error: `write_applied: false`,
`precondition_failed: true`, and `current_record` holding the record that stands. The refusal is
final — the condition not holding means keeping the stored record is the correct result — and the
agent is instructed to continue without asking the user, retrying only when its own instructions
explicitly require overwriting the newer value.

## Limits and side effects

* maximum patch size: 256 KiB
* maximum accumulated record size: 256 KiB
* maximum top-level fields per patch: 100
* omitted fields remain unchanged with the default `merge` write mode — the agent is instructed
  to send only the fields it is changing, never an empty value for a field it does not intend
  to overwrite; a record type configured
  with the `replace` write mode stores the supplied document as the whole record, removing
  omitted fields — omission is how a field is deleted. The agent is instructed to send exactly
  the fields the record should contain afterwards, and to read-and-copy kept fields only when
  the request changes some fields but clearly intends to keep the rest (never from conversation
  memory, which may be stale)
* explicit `null` is stored as JSON null by default; a record type configured with `clear_nulls`
  removes the field instead (identity and readiness-required fields are refused)
* object and array fields replace their complete previous value; patches do not deep-merge nested data
* disjoint concurrent patches merge atomically
* concurrent writes to the same field are last-write-wins unless the write passes
  `expected_version`, which refuses the write when the stored version no longer matches
* records persist until their record type or workspace is deleted, or an operator deletes the
  record from the Data Store record browser; there is no agent-facing deletion or retention timer

The tool writes one PostgreSQL record and does not launch tasks or emit readiness triggers.

## Expected errors

* record type not found
* base tool enabled without first creating a configured instance
* missing or invalid identity field
* undeclared field or configured type mismatch
* merged record exceeds the accumulated size limit
* explicit key missing for a contract-free record type
* configured scope is invalid or agent execution identity is unavailable
* database operation failed