Step-by-step instructions for exporting the subset of data in a TDR asset for analysis in a Terra workspace.
Note: currently it is only possible to export a Snapshot of Google-backed TDR datasets, to a Terra workspace linked to a Google billing account. The ability to export to an Azure workspace is forthcoming.
Export the Snapshot in TDR (in a browser)
1. In TDR, go to your Snapshots tab.
2. Click on the Snapshot to export.
3. This will take take you to the page for the Snapshot, where you can click on the Export tab and then Export Snapshot.
If you're listed as a Steward for the workspace, you'll also be able to manage access to the Snapshot from the Roles & Memberships tab on this page.
Steward and reader roles
If you are the creator of the Snapshot, you're automatically granted the role of Steward, which allows you to add other users as either Stewards or Readers. A reader will see the Snapshot listed in their Snapshots tab, and also be able to export the Snapshot to their Terra workspaces, but they won't be able to use any of the access management options.
What to expect
Clicking Export to Workspace will take you to the Import Snapshot page, where you can either select a Terra workspace to which you have owner or writer access or create a new workspace for the Snapshot export.
(Advanced option) Export the Snapshot using the API (Swagger)
Though we recommend exporting snapshots in TDR, you can also use this Rawls API exportSnapshot endpoint. For further help with this approach, use the Contact Us form in the main navigation menu.
Remember to authorize Swagger every time you use it. See How to authenticate/troubleshoot Swagger for TDR for step-by-step instructions.
Exporting protected data
There are additional restrictions involved in exporting a snapshot from a TDR dataset with protected data. If the dataset had secure monitoring enabled, you will only be able to export the data to a workspace that also has secure monitoring enabled. If you do not already have a workspace with secure monitoring enabled, you will need to export the snapshot to a new workspace with secure monitoring enabled.
In addition, the best practice is to export the snapshot to a workspace with an authorization domain, which will help you control who can access the data once it is in Terra. See Overview: Managing access to controlled data with authorization domains and How to set up and use an authorization domain to learn more about using authorization domains.
What to expect
Terra imports TDR Snapshots into your workspace as data tables. Once the export process is complete, you can see the resulting tables in your workspace's Data tab. If your Snapshot includes data from more than one TDR table, the data exported in the Snapshot will remain separated into distinct tables. For example, if your Snapshot included some data from a table called 'sample' and some from a table called 'subject,' exporting this Snapshot would create two tables in your Terra workspace: 'sample' and 'student'.
If you export multiple Snapshots that include data from the same table, Terra will merge the data across the Snapshots. That is, if a row exists in two snapshots, Terra will update the row based on the data in the latest import. Terra identifies matching rows based on their primary keys -- see Overview: Defining your TDR dataset schema to learn more.
Next steps
Once you've exported your Snapshot to a Terra workspace, you can run workflows and interactive analyses on the data in the Snapshot, just like with any Terra data table. To learn more, read How to use TDR Snapshots with workflows.