Writing Data¶

All writes go through session entry points that return a WriteSegmentBuilder. Chain bin operations, then call .execute().

Write Verbs¶

Method	Behavior	Record must exist?
`upsert()`	Create or update	No
`insert()`	Create only	No (fails if exists)
`update()`	Update only	Yes (fails if missing)
`replace()`	Replace all bins	Yes (fails if missing)
`delete()`	Remove record	No
`touch()`	Reset TTL	Yes
`exists()`	Check existence	No

Bin Chaining¶

Set individual bins with the chainable .bin().set_to() pattern:

users = DataSet.of("test", "users")

await (
    session.upsert(users.id(1))
    .bin("name").set_to("Alice")
    .bin("age").set_to(30)
    .bin("active").set_to(True)
    .execute()
)

Dict Pattern¶

Set multiple bins at once with .put():

await (
    session.upsert(users.id(1))
    .put({"name": "Alice", "age": 30, "active": True})
    .execute()
)

Increment¶

await (
    session.update(users.id(1))
    .bin("login_count").increment_by(1)
    .execute()
)

Insert (Fail if Exists)¶

stream = await (
    session.insert(users.id(99))
    .put({"name": "New User"})
    .execute()
)
result = await stream.first_or_raise()

Replace (Overwrite All Bins)¶

await (
    session.replace(users.id(1))
    .put({"name": "Alice Updated"})
    .execute()
)
# Only "name" bin remains; "age" and "active" are removed

Delete¶

# Single key
await session.delete(users.id(1)).execute()

# Multiple keys
await session.delete(*users.ids(1, 2, 3)).execute()

# Durable delete
await session.delete(users.id(5)).durably_delete().execute()

Conditional Writes¶

Filter writes server-side with .where():

await (
    session.update(users.id(1))
    .where("$.age >= 18")
    .bin("verified").set_to(True)
    .execute()
)

Records that don’t match the filter are skipped. Use .fail_on_filtered_out() to raise an error instead:

await (
    session.update(users.id(1))
    .where("$.age >= 18")
    .fail_on_filtered_out()
    .bin("verified").set_to(True)
    .execute()
)

Generation Check (Optimistic Locking)¶

await (
    session.update(users.id(1))
    .ensure_generation_is(5)
    .bin("balance").set_to(100)
    .execute()
)

TTL / Expiration¶

await (
    session.upsert(users.id(1))
    .expire_record_after_seconds(3600)
    .put({"session_token": "abc123"})
    .execute()
)

Batch Writes¶

Multiple keys with the same operation:

await (
    session.upsert(*users.ids(1, 2, 3))
    .bin("status").set_to("migrated")
    .execute()
)

Mixed operations across different keys are handled automatically when you chain multiple write segments.