How to add a table to a Terra workspace

Allie Hajian
  • Updated

Whether you want to create a workspace from scratch or use a copy of another workspace, you have multiple options for adding a data table to the workspace. You can import tables of metadata into your workspace by copying from an existing workspace or importing a TSV file

Three ways to add data tables to a workspace

The Terra Data page has dedicated sections for different kinds of data tables; this article goes over how to add tables to the Table section, which is typically dedicated to the data you want to analyze or transform in downstream analysis (input data) and its associated metadata. 

See How to make a data table from scratch or a template to generate a table from scratch.  

Option 1: Copy a table from another workspace

1. Starting in the workspace you want to copy from, select the rows you want to export (or all rows, if you want the entire table).

2. Click Export above the table.

3. Select Export to workspace and follow the instructions.

There is no cost to copying data in a table to a workspaceExporting a data table to another workspace or downloading the TSV metadata does not incur any egress costs because you are not moving/copying the files in the table, merely copying the metadata and references to the new workspace.

Note: Readers of your workspace will need Reader access to the bucket or workspace which actually owns the data to access files linked in the table.

Is the source data workspace protected by an Authorization Domain (AD)? Make sure the destination workspace has the same Authorization Domain(s) as the workspace where the data are stored. If the destination workspace does not have the same AD, links in the table won't work. Your analysis will fail when Terra cannot localize the data. 

1. Go to the data page of the source workspace (that has the data table to copy).

2. Go to the table of metadata to import (i.e., participants, samples, pairs, or sets) and click on the three vertical dots to the right of the table name.

3. Select from the pop-up menu and follow the prompts.
     -To save the entire table to your local machine, use Download TSV.
     - To copy the table to another workspace, use Export to workspace.


Importing sets will bring over all the data required for the setAny dependent data will be imported automatically. For example, if you import a sample set, the sample and participant tables and all data linked to the set will be copied over too.

Option 2: Import from the Data Library or other external servers (i.e., Gen3, HCA)

For external data resources directly connected to Terra, you'll be able to browse and filter, select the data subset you want, and export directly to your workspace.

Data browsing and formatting can vary widely

External repositories each have their own data browser and unique way of exporting data files. When you export data from the Data Library or an external source such as the Gen3 platform (shown in the video below), they may show up as multiple tables of predefined entities.

Option 3: Upload a load (TSV) file 

Want to include a table for data you've just uploaded to your workspace bucket?

Use the Data Uploader to upload data and its associated table at once. See How to use the data uploader for step-by-step instructions. 

No workspace with data in a table to copy?

1. Click the Import Data button at the top left of the workspace data page.

2. Select Upload TSV.

Step-by-step instructions to create a TSV file

See How to make a data table from scratch or a template.

Next steps

If you already have a data table in your workspace, you can modify it to meet your analysis needs. Learn more in Modifying and editing a data table

Adding workspace-level files (e.g., reference files)

Maybe you're ready to perform an analysis but you need some workspace-level metadata like reference files. Read Creating Workspace Data tables to learn how to make a Workspace Data table that can be used in downstream WDL workflows.

Additional resources

Was this article helpful?

1 out of 1 found this helpful



Please sign in to leave a comment.