What this page is for#
The Bulk data page (/bulk) moves a namespace's state in and out as a file. Download saves everything the chosen key can read as one TERSL file. Upload a TERSL file sends a file into the namespace; the service cuts it into batches and applies them one at a time, reporting each batch as it goes. Use the download for a backup or to move state elsewhere, and the upload for files too large to send as one Issue.
Who can see it#
Every signed-in user who holds a key that some active namespace grants. The page is not limited to administrators: what the download contains and what the upload may change are decided by the chosen key's grants, as for any request.
What is on the page#
The pickers and the wiring line#
Namespace and Key choose the namespace and the key to act as; press Open. They behave as described in the namespace and key pickers. A line then names the namespace, the key and the path the requests go through, with the caption "The portal attaches the key on the far side of /proxy. This browser never holds it."
All state#
The All state panel says what the download will contain: "Everything this key can read in" the namespace "as one TERSL file", and the file's name, which is the Namespace Id and the CSN it was read at, such as 74XEEJ5-4096.terse. Download starts it. The note "Your browser's downloads show its progress and can cancel it." applies: the browser saves the file directly, so the download works for large namespaces and with JavaScript off.
The file begins with a comment line naming the namespace, the CSN and the time, and ends with a comment line that starts // TERSL export complete and counts what it contains. A file without that closing line was cut short. Both lines are comments, so loading the file back loads the state and nothing else.
Upload a TERSL file#
The upload panel's caption says the file is sent through the portal up to the size it states, and that each batch is applied as one Issue and answered with one line. Its controls are:
| Control | What it does |
|---|---|
| The file picker | Chooses a .terse or plain-text file. |
| batch MiB | The size each batch is cut at, from 1 to 32 MiB (8 by default). The service keeps each batch within the plan's request-size limit. |
| exclusive | What the namespace is closed to while the upload runs: none, writes or all. |
| dry run | Plan the upload and report the batches without applying anything. |
| Pause on error | Stop at the first batch the service refuses (ticked by default). Untick it to skip a refused batch and continue. |
| Start / Cancel | Start the upload, or stop it. |
While an upload runs, Status moves through uploading, sending, spooling and loading. The Log shows every line the service sent, newest at the bottom; progress lines are dimmed. Refusals are listed under Errors with their line numbers in your file. clear log empties the log.
The upload needs JavaScript; the download does not.
At a moment#
If the page is opened at a moment of the record (for example /bulk?ns=74XEEJ5@4096), a bar says the download reads that moment and that "there is no upload here, because a load writes the present". Live returns to the current state.
Actions#
Download the state#
Choose a namespace and key and press Download. The file holds what the key can read, so a key granted only part of the namespace downloads only that part.
Upload a file#
Choose a file, set the options and press Start. The service first reads the whole file and plans its batches. If the plan finds a problem, such as invalid UTF-8 or an unclosed block, nothing is applied and every problem is reported at its line. Otherwise it checks that the key can write under each top-level part the file names, then applies the batches in order.
An upload adds and modifies what the file names and leaves everything else in the namespace as it was; it never deletes unless the file itself contains a removal. Each batch is applied as a unit, and if the upload stops part-way, the batches before the stop stay applied. The summary ends with "committed through line N", the last line of your file that was applied.
Keep the page open until the upload finishes. The page warns "Please keep this page during upload as leaving will result in a partial upload." and, if you try to leave, "An upload is running. Cancel it first, or wait."
The service paces a large upload to the plan's rates; it may pause between batches with a line that begins paused 30 s: tenant throughput limit. Only one upload runs in a namespace at a time, and a read-only namespace refuses an upload with a 409.
Choose an exclusive mode#
none lets other reads and writes continue between batches; a read sees the namespace after a whole number of batches. writes refuses other writes to the namespace with a 503 and a Retry-After while the upload runs, and lets reads continue. all refuses every other request to the namespace the same way.
Do a dry run#
Tick dry run and press Start. The log shows the plan, with its totals, every batch and any refusals, and nothing is applied.
Recover from a refused batch#
With Pause on error ticked, the upload stops at the first refused batch and two buttons appear: one retries the refused batch and the other skips it. "Either one sends the whole file again; the service applies nothing at or before the line." With Pause on error unticked, a batch refused for its own content (a value over a content limit, or declarations the store would not apply) is skipped and named, and the upload continues. A refusal about the namespace or the service, such as the plan's namespace-size limit, stops the upload in either mode.
Cancel#
Cancel stops the upload. Batches already applied stay applied.
Related#
- Writing with declarations describes what an uploaded file contains.
- The wire describes the load and export routes the page uses.
- Status codes and Diagnostic codes list the refusals an upload can report.
- Plans, rates and limits describes the request-size and rate limits that shape batches and pacing.
- Keys, grants and visibility explains why a download contains only what the key can read.