updateQuery

PATCH-style write. Persists payload under the resolved cache key for the given query, wrapped in a synthetic 200 OK envelope. Returns the resolved cache key, or null if any placeholder in template couldn't be resolved.

Each metadata parameter has null-means-preserve semantics:

• contentType = null → keep the existing entry's Content-Type (or "application/json" if no entry exists yet).

• maxAgeMs = null → keep the existing entry's TTL. 0L → no explicit expiry. >0 → use it.

• tags = null → keep the existing entry's tags. emptyList() → explicitly clear. Non-empty → resolve as tag templates against bindings / bodyBytes and replace.

The freshness window restarts on every patch (a new write resets createdAt).

Common recipes for the byte payload:

// Optimistic update with kotlinx.serialization — preserve tags from the original
// @CacheQuery write
val payload = Json.encodeToString(updatedUser).encodeToByteArray()
bridge.cache.updateQuery(
    UserApi::class.java,
    template = "users/{id}",
    bindings = mapOf("id" to "42"),
    payload = payload,
    // contentType, maxAgeMs, tags omitted → all preserved
)

// Explicitly replace tags
bridge.cache.updateQuery(
    ...,
    payload = payload,
    tags = listOf("user:{id}", "tenant:{tenantId}"),
)

// From a Retrofit Response<ResponseBody>
val payload = response.body()?.bytes() ?: return

Footgun: if the bytes you write here drift from what the server would return, every read after this updateQuery lies until the next mutation/invalidation refreshes the entry.