sheets

Update a Sheet (optimistic concurrency).

Updates any subset of the Sheet's definitional fields. kind is immutable. Requires the current version; a stale version returns 409. Every successful update writes a new revision. If connectionId is provided it must reference a connection with kind: writeback; a pushdown connection is rejected with 400 (DVT-904). In the Snowflake Native App a sheet created without connectionId is already auto-bound to the boot-provisioned Host Snowflake Writeback connection (ADR-0077 r2, DVT-2905); patching connectionId there is only needed to point at a different connection.

Changed 2026-08-10: a columns array whose names are not unique when matched case-insensitively is rejected with 400 (DVT-2476) — the same rule POST /v1/sheets now applies, described in full there. This is also the endpoint used to repair a sheet created before the rule existed: drop one of the colliding columns and appends will be accepted again.

Note that changing a column's declared type does NOT re-check edits already sitting in the write-ahead log — their payloads are sealed (ADR-0012) and only the engine can read them. An edit appended while a column was undeclared, or declared with a different type, is checked at flush against the definition in force then, and a failure there blocks every subsequent flush of the sheet.

patch/v1/sheets/{id}

Request

  • Base URL: http://localhost:8080
  • URL: http://localhost:8080/v1/sheets/{id}
  • Auth: one of:
    • API key in cookie dvt_session
    • HTTP bearer

Query parameters

reasonstring

Optional change note recorded as this revision's summary (≤280 chars); when absent the server writes a default summary. May also be supplied via the X-Dvt-Change-Reason header. Over-cap values return 400.

Request body

versioninteger required

The current version, from the latest GET. Required for optimistic concurrency.

namestring
visibility'private' | 'shared' | 'public'

For kind='linked', 'public' is rejected with 400 — only 'private' or 'shared' are allowed, same as create (ADR-0078 D1/sec-M1). Unrestricted for kind='standard'.

connectionIdstring uuid nullable
targetDatabasestring

The install's writeback database (DVT_WRITEBACK by default on the native app; dvt_writeback elsewhere); any other value is rejected with writeback-database-unsupported (400). Use it to repair an unpinned sheet that stores a different database. On a sheet whose writeback target is already pinned (it has flushed), a value differing from the stored one (compared case-insensitively) is rejected with 409 writeback-target-pinned.

columnsobject[]

Updatable for kind='standard'. For kind='linked', immutable from create unconditionally (pr-review round-1 fix, H2/H3) — sending this key at all, even byte-identical to the sheet's current columns, is rejected with 400 regardless of whether the sheet has flushed yet; omit it entirely on a linked PATCH (see this schema's top-level description).

primaryKeystring[]

Updatable for kind='standard'. For kind='linked', immutable from create unconditionally (pr-review round-1 fix, H2/H3) — sending this key at all, even byte-identical to the sheet's current primary key, is rejected with 400 regardless of whether the sheet has flushed yet; omit it entirely on a linked PATCH (see this schema's top-level description). For either kind, no entry may use the reserved 'dvt' prefix (dvt-managed columns) — rejected with 400, same rule as create's 'primaryKey'.

seedQuerystring nullable

RETIRED (DVT-2928). A non-empty value is rejected with 400 — seed-copy linked sheets are no longer supported. Omit it.

descriptionstring nullable

Response

Sheet updated.

Changes

No recorded changes to this operation across all 1 revision of this API.