Kotlin: Set bucket

setBucket writes values into the bucket parameters of the tables configured with KizunaSyncBucket.ByColumn, so a pull can ask for the rows of one team or project. It fills the keys the configuration declares as bucket columns and refuses the whole call when any key is not one of them. A table configured with KizunaSyncBucket.ByOwner needs no call: the engine fills its bucket with the user the session token names, as Set access token describes.

Examples#

After the open#

// app/src/main/kotlin/com/example/todo/TodoSync.kt (excerpt)
kizunasync.setBucket(mapOf("team_id" to teamId))

This example assumes a todos table configured with bucket = KizunaSyncBucket.ByColumn("team_id"), and teamId is the app's own value, such as the team the signed-in user belongs to. The engine restores no ByColumn value when it opens, so the app sets it after every create and before it starts the Host scheduler.

Switching to another team#

// app/src/main/kotlin/com/example/todo/TodoScreen.kt (excerpt)
kizunasync.setBucket(mapOf("team_id" to nextTeamId))
syncScheduler.wake()

A nextTeamId that differs from the one this device already kept for that key replaces the local scope: the run the wake starts re-bootstraps every table sharing the key, and its closing pull boundary drops every row the new value does not carry. Queued writes survive the switch. Reset is a heavier, separate operation: it also empties the outbox and the rejection and overwrite journals, and mints a new client identity.

Parameters#

Returns#

Unit. The values live in the open engine, not in the database, so each Initializing call starts without them: the app sets them again after every open rather than restoring them from the file. An owner bucket is the exception, because the engine fills it from the owner the database keeps.

Errors#

Every code in the table is the code on a thrown KizunaSyncError.Engine; message reads "CODE: message", but match on code rather than parsing the string.

A value org.json refuses never reaches the engine: the client raises a JSONException while encoding, so it surfaces as that exception rather than an engine code.

Notes#

The store keeps, per table, the last non-empty value it saw for each key, across restarts. A call that replaces one of those kept values with a different non-empty value arms a re-bootstrap: the next pull restarts every table's keyset from "0", and its closing boundary replaces the local snapshot, dropping the rows the new scope does not carry, while every queued write stays untouched. Filling a key the store keeps no value for, clearing it to "", or setting the same value again arms nothing. The kept value only decides whether a call re-bootstraps; the engine restores no KizunaSyncBucket.ByColumn value at open, which is why an app calls setBucket again after every create.

A KizunaSyncBucket.ByColumn bucket whose value is still unset, or was cleared to "", makes the next pull throw BUCKET_UNSET rather than asking for every row, which is the failure BUCKET_UNSET explains. A table provisioned without a bucket column and declared with no bucket is a shared table: it pulls every row Row Level Security permits. On the other tables, Kizuna adds the bucket only as a second, coarser filter on top of the policy. A table provisioned with a bucket column refuses an unscoped pull with KZL01.

On a KizunaSyncBucket.ByOwner table, a value set here holds until the next open, when the engine fills the bucket from the owner again, or until Reset, which clears it. The first token that records an owner overwrites a value set before it.

Sync rules and buckets explains which column to scope a table by, and Set access token covers the other half of a sign-in.

Related reference#

• Sync
• Pull once
• Set access token
• Reset
• Swift: Set bucket
• JavaScript: Set bucket