--- title: "Force an immediate flush of a Sheet's pending WAL (\"Sync now\")." method: POST path: "/v1/sheets/{id}/flush" tags: ["sheets"] --- # Force an immediate flush of a Sheet's pending WAL ("Sync now"). `POST /v1/sheets/{id}/flush` ## Request - Base URL: `http://localhost:8080` - URL: `http://localhost:8080/v1/sheets/{id}/flush` - Auth: one of: - API key in cookie `dvt_session` - HTTP bearer Forces an immediate flush of the sheet's pending write-ahead log, ignoring the server-side per-sheet age gate the periodic background flush job otherwise waits out (DVT-3374). Requires `sheet:write` — the same authorization chain as `POST /v1/sheets/{id}/rows`. Concurrent callers are safe: an on-demand flush shares the same per-sheet single-flight advisory lock as the periodic background flush job, so a caller racing an in-progress flush (from another instance, or the background job) receives `busy` rather than double-flushing or blocking. ## Response `200` The flush attempt's outcome. - object - `data` FlushSheetNowResponse, required: Result of POST /v1/sheets/{id}/flush (DVT-3374). - `outcome` 'flushed' | 'nothing_pending' | 'stranded' | 'blocked' | 'busy', required: "flushed" — pending WAL entries were forwarded and marked flushed. "nothing_pending" — there was no pending WAL work to flush. "stranded" — this sheet's folder-derived writeback target collides with another live sheet's already-pinned target; an operator must rename the sheet or its folder to un-collide, retrying alone will never resolve this. "blocked" — a bare retry cannot resolve this; an admin action is needed first. `blocked` specifically means an engine-reported writeback precondition — see `cause` below. Covers more than one condition: the warehouse writeback target may not be provisioned for this in-account writeback connection (the Snowflake `dvt_writeback` database is missing, or its consumer_warehouse grant is not authorized to this application — the same condition `POST /v1/sheets/{id}/rows` surfaces as `X-Dvt-Error-Code: no-warehouse`), or the sheet's warehouse table may have a managed column (`row_uid` / `_dvt_flushed_seq`) dvt cannot use. See `cause` below for which condition applies. "busy" — no forward progress was made and pending work remains. Most commonly a concurrent flush already holds this sheet's single-flight lock, or the process-wide/per-org flush concurrency limits were momentarily saturated — both genuinely transient, a bare retry resolves them. But "busy" is NOT exclusively transient (DVT-3374 fix round 2, G3a): it also covers deterministic, non-retriable conditions this endpoint does not pre-gate for (e.g. a folder tree exceeding the depth cap, a resolved unparseable/zero declared columns) — a caller should retry, but must not assume every "busy" is self-healing. - `cause` string: Set only when `outcome` is "blocked" — the literal `X-Dvt-Error-Code` the engine returned (DVT-3374 fix round 2, G2; widened DVT-3451), passed through verbatim. A plain string, not a closed enum: absent on an older server, and the wire type is deliberately left open — the set of codes a server classifies as "blocked" at all is a closed server-side allowlist, so this field does not need widening client-side just to carry a code the server already recognizes. Five values are documented today: "no-warehouse" (the app's consumer_warehouse reference isn't bound, or isn't granted usage), "writeback-not-provisioned" (the consumer-owned `dvt_writeback` database is missing or not authorized to this application), and "managed-column-conflict" (the sheet's warehouse table has a `row_uid` or `_dvt_flushed_seq` column dvt can't use — wrong type, or a missing `row_uid` that cannot be added), and two set by dvt itself when the sheet's stored target database is not this install's writeback database: "writeback-database-mismatch" (the sheet has already flushed, so its target is pinned) and "writeback-database-unsupported" (not yet pinned; repair with PATCH targetDatabase set to the install's writeback database). Absent when `outcome` is not "blocked", and also absent (rather than a guessed value) if a caller on an older server sees "blocked" with no `cause` at all. A client MUST treat any value it does not recognize — including absent — the same way: render the halt without asserting a specific remedy. Do not assume an unrecognized cause is any one of the documented conditions above. - `meta` Meta, required: Response metadata. - `requestId` string, required: Correlates with the X-Request-Id header. - `total` integer: Item count, present on collection responses. - `nextCursor` string, nullable: Opaque keyset-pagination cursor, present on paginated responses (e.g. GET /v1/dashboards) when more rows exist beyond this page. Pass it back as the `cursor` query param to fetch the next page; absent or null on the last page. - `roleResolveDegraded` boolean: Snowflake mode only (DVT-2260), on GET /v1/dashboards: present and true when the caller's live Snowflake role resolution failed or was unavailable — role-shared dashboards may be missing from this page. Omitted (not merely false) whenever resolution succeeded or the role-share arm does not apply (off snowflake mode, an org admin/owner, or off the ingress listener). ## Other responses - `401`: Missing, invalid, or expired session. - `403`: The caller's role does not permit this action. - `404`: Resource does not exist. - `409`: `https://docs.dvt.dev/errors/sheet-flush-unavailable` (also echoed in the `X-Dvt-Error-Code` response header) — this sheet can never be flushed without a `PATCH` first: it has no bound writeback connection, the bound connection no longer exists or is not writeback-kind, or the bound connection is a Redshift warehouse (not yet supported on the flush path). Bind a non-Redshift writeback `connectionId` via `PATCH /v1/sheets/{id}`, then retry. `https://docs.dvt.dev/errors/writeback-switch-stranded` (also echoed in the `X-Dvt-Error-Code` response header) — flushing is paused because an administrator changed the install's writeback database. A connection `PATCH` does not clear it; an administrator must resolve it. Rows appended meanwhile are kept and flush once it is resolved. - `503`: On-demand sheet flush is not configured on this deployment. --- [API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)