There are two ways to run Notebooks in Terra: You can open the notebook (run, edit and save) or use Playground (run only). Both allow you to run an analysis and generate data, which is stored in the Cloud Environment persistent disk. In Playground mode, however, you cannot save the notebook or any output logs (and the .jpynb file will not be autosaved to workspace storage). This article explains the differences between the two modes, how to toggle between them, and how to save data and the notebook when you run in Playground mode.
Notebook cloud environments created before August 1, 2019?These are incompatible with "Playground" mode. To see if you have any incompatible cloud environments, check the "Created" column in your Cloud Environments page. Further action is required. See instructions below for next steps.
Protecting shared notebooks
To protect users from overwriting each others' notebook edits when running the same notebook in the same workspace at the same time, Terra includes a playground Jupyter mode. When you open a notebook in your Notebook or Analyses tab, you will see a preview and two options for running the notebook.
- Open the notebook to run and save the notebook, including output logs.
- Use Playground to run code but not save the notebook or output logs.
Only one user at a time is allowed to open a notebook. Any other users in a shared workspace can only access the same notebook in Playground mode. The two modes allow collaborators in a shared workspace to interact with the same code without overwriting the persistent version.
How "Lock" mode protects Notebook users from overwriting each otherWhen a user with Writer access opens a notebook, the notebook becomes "locked". When locked, a second user cannot open the notebook.
The lock keeps multiple users with access to the same notebook from editing and overwriting each others’ work. You will know a notebook is locked by the lock icon in the corner of the notebook's title card.
-
Above: The lock icon indicates that another user is currently using the Notebook in "Edit" mode. Hovering over the icon shows the email of the user currently editing the notebook.
-
Above: The lock icon indicates that another user is currently using the Notebook in "Edit" mode. Hovering over the icon shows the email of the user currently editing the notebook.
What can you do when a notebook is locked?
Just because a notebook is locked does NOT mean the next user cannot open or interact with the notebook! There are three options for opening the notebook, even while it is locked by another user.
1. Preview the notebook (read only)
This option allows you to open a notebook in read-only mode, based on the last saved version. This is the same preview mode shown while a notebook is starting up. It's available whether the notebook is locked or unlocked.
Above: The notebook is in Preview (Read Only) mode and trenders as simple text that can't be modified.
2. Use Playground mode
Opening in playground allows you to run a notebook, but not save changes. Whatever you generate in playground mode will be lost, unless you download a copy from the "File" -> "Download" menu. Playground mode is available whether the notebook is locked or unlocked.
Above: A Notebook opened in "Playground" mode will have notation in orange warning that the notebook is in transient mode where changes are not saved.
We encourage users to use Playground Mode in situations when you need to run, but not edit, a notebook. It's useful for quick review of the notebook contents. And if you decide you do need to keep it, you can always make a copy (see #3).
3. Copy the notebook
Copying allows you to create and open a duplicate of the notebook. You can make a copy from a notebook you are running in Playground at any time. Notice that until you make a copy, however, Terra will not autosave the notebook.
If you try to open a locked notebook, a pop-up will prompt you to either launch the notebook in Playground Mode, or to make a new copy of the notebook, which will open in regular Edit Mode. If you click "Cancel" in the pop-up, you'll remain in "Preview” mode.
Above: Clicking on "Edit (In Use)" will give current activity and also prompt between the option to "Make a Copy" and "Run in Playground Mode". You can open the notebook copy with regular Edit.
Getting back to standard mode ("open")
Once the user who locked the notebook closes it, the lock icon will disappear to show the notebook is unlocked and other users are now free to open the notebook so they can edit and save their work.
The tabs along the top of the notebook provide a quick way to toggle between Preview, Open, and Playground.
Cloud Environments created before August 1, 2019
These cloud environments are incompatible with "Playground" mode. Further action is required. Please keep reading for next steps.
When you open a notebook in an incompatible Cloud Environment, the edit functionality is disabled (shown below in screenshot). Selecting "Edit (Disabled)" will reveal a prompt to choose between "Recreate Notebook Runtime" and "Run in Playground Mode". The former will delete the old cloud environment and create a new compatible one. The latter will open the notebook in Playground, where you can access and copy any previously generated outputs to a permanent location before deleting and re-creating Cloud Environments. To open notebooks in full edit mode requires a compatible Cloud Environment.
When opening a Notebook in "Playground" mode (from an incompatible Cloud Environment) you'll see a banner prompting to re-create the Cloud Environment.
Save generated data before re-creating the Cloud Environment If you have outputs generated in an old Cloud Environment that need to be saved, you can access them from Playground mode and copy them to a permanent location using the steps in Copying notebook output to a Google bucket.
Once you've saved the data, you can delete and re-create the incompatible Cloud Environment to open the notebook in edit mode.