Attention: Notebook cloud environments created before August 1, 2019 are incompatible with the new "Edit" and "Playground" modes. Further action is required. Please keep reading for next steps. Otherwise, please skip ahead to the "What is a notebook "lock"?" section to learn about the new features!
There are two modes of running Notebooks in Terra: "Edit" and "playground". Both allow you to run an analysis, and generate data, which is stored in the notebook cloud environment VM disk. Edit mode allows you to save the notebook, including the output logs. In Playground mode, you can run code but not save the notebook or any output logs. This article explains the differences between the two modes.
Incompatible Cloud Environment - Overview
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" mode where you can access and copy any previously generated outputs to a permanent location before deleting and re-creating cloud environments (see below for full details of Playground mode). 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. If you have outputs generated in an old runtime that need to be saved, you can access them from Playground mode and copy them to a permanent location using the steps in the "Copying Notebook output to a Google bucket" document. Once you've saved the data, you can delete and re-create the incompatible runtime to access "Edit" mode.
What is a notebook "Lock"?
When multiple users have access to the same notebook in a single workspace, the "lock" prevents multiple users from editing and overwriting each others’ work. In order to protect users from this problem, we have developed a feature to make it possible for one user to edit the version of the notebook that persists (and is autosaved frequently), and others to confidently interact with the same code without harming the persistent version.
"Lock" mode protects Notebook users from overwriting each other
When a user with “Writer” access opens a notebook in “Edit” Mode, the notebook becomes "locked". When locked, a second user cannot open the notebook in Edit mode. You will know a notebook is locked by the presence of the lock icon in the corner of the notebook's title card, as shown below.
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 options are available 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:
- Preview (Read Only) option allows you to open a notebook in read-only mode, based on the last saved version. This is the same as preview mode - shown while a notebook is starting up and available whether the notebook is locked or unlocked.
- Playground Mode allows you to open and use/edit 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. We encourage users to use Playground Mode in situations when a notebook needs to be run, but not edited.
- Copying the notebook allows you to create a duplicate of the desired notebook and access Edit Mode of the copy.
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.
1. Preview (read only) mode
In a "Preview (Read Only)" state, you can view, but not edit, the notebook. This is useful for quick review of the notebook contents:
Above: The notebook is in Preview (Read Only) mode and trenders as simple text that can't be modified.
2. Playground mode
Locked notebooks can be accessed in "Playground," mode where you can modify code and execute cells, but you cannot save changes to the original copy. However you can save edits made in Playground mode by downloading the notebook from the "File" -> "Download" menu.
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.
Getting Back to "Edit" mode
Once the user who locked the notebook closes their Edit mode instance, the lock icon will disappear to show the notebook is unlocked and other users are now free to edit. The tabs along the top of the notebook provide a quick way to toggle between Edit, Playground, and Preview modes.
