Sandboxes

A sandbox lets code read a catalog's real tables while every write lands somewhere of its own. Nothing is copied up front and nothing reaches the catalog it shadows. There are two: sandbox mode, which you switch on in a notebook, and the sandbox run a pipeline goes through before it is promoted.

• Why sandboxes exist
• Sandbox mode in a notebook
• What happens to reads and writes
• Switching it off, and expiry
• The sandbox run in a promotion
• Questions

Why sandboxes exist

In a production catalog, people can read tables and change their structure, but they cannot write rows — only pipelines can, running as their environment's service identity. Outside production, a domain's owners and editors can write, but the tables are shared with the rest of the team. A sandbox gives you real data to work against without either problem: you can write freely, and nobody else sees it.

Sandbox mode in a notebook

The Sandbox control sits beside the Engine button at the top of a notebook. It says what it needs before it can be switched on:

It reads	Means
Sandbox: needs a kernel	Attach the notebook to a kernel first. Sandbox mode changes where the kernel's catalog points, so there has to be one.
Sandbox: no catalog	Choose a catalog in the top bar. Sandbox mode shadows the catalog you are working in.
Sandbox: off	Ready. Click it to switch sandbox mode on for the catalog chosen in the top bar.
Sandbox: catalog until date	On. Everything this kernel reads from that catalog comes through your sandbox, until the date shown.

Switching it on restarts the kernel, so anything in memory is lost. You confirm before it happens.

What happens to reads and writes

• Your code does not change. Table names stay the same; what they resolve to changes. There is no name left in the session that reaches the real catalog.
• Reads come from a copy of each table's metadata, made the first time something asks for that table — so the first read of each table takes a moment longer. The data files themselves are not copied.
• Writes land in your own storage. The real table never changes, and nobody else sees what you wrote.
• You can only sandbox what you can read. A table your grants do not reach is not reachable through a sandbox either.
• Shared data products keep the same address from a sandbox as from any environment, so code that reads one needs no edit. See Sharing data.

Switching it off, and expiry

Click the control again to switch sandbox mode off. That restarts the kernel too. Anything you wrote stays in your storage, but a table sandboxed again later starts from whatever the real catalog holds then.

A sandbox retires itself after seven days.

While a sandbox exists, the versions of the real tables it read are held so the sandbox keeps working — table maintenance does not expire them. That keeps storage on those tables from being reclaimed, so switch sandbox mode off when you have finished rather than waiting for it to expire.

The sandbox run in a promotion

A promotion path can require that a pipeline pass a sandbox run before anyone signs it off, and an environment can require one on every path into it. The run answers the question reviewers actually have: what will this version do to the data it will run against?

• It runs the exact version the request pinned.
• It reads the target environment's data, as that environment's service identity — the same access the pipeline will have after promotion.
• Everything it writes goes to a catalog made for that request, which is removed when review ends. It cannot write the target catalog.
• A reviewer starts it, not the author: opening a request starts nothing, so no code from a lower environment runs with the target's access before someone has looked at it.
• It is stopped if it runs past the path's time limit. On failure the path either blocks the request, or records the failure and opens sign-off anyway.
• Sign-off opens once the run has reported. The request shows the run and its output.

See Promoting between environments for the rest of the request.

Questions

Can I use sandbox mode with a SQL notebook?

No. Sandbox mode changes a kernel's catalog, so it is for notebooks attached to a kernel.

Do I get a sandbox per catalog?

Sandbox mode is set per kernel, for the catalog chosen when you switch it on. Two kernels can each have sandbox mode on, over different catalogs.

What if the real table changes while my sandbox is on?

Your sandbox keeps reading the version it copied. Switch sandbox mode off and on again to start from the current one.