Versioning Tables, Views, and Datasets

Versioning is an essential component of conducting reproducible research. Tables, views, and datasets can be versioned to create a snapshot of your data at a specific point in time. This snapshot can then be referenced and shared. For example, if you are publishing a collection of files in a file view, you may want to share your work with others for analysis. You can use the file view to check that the annotations are correct, then create your first version when it’s ready to share. Later, when you’ve added more files and annotations, you can create a second version to share for additional analysis. You can refer back to previous versions to see what files and annotations were used at each step of your research.

As you refine a table, view, or dataset all changes are saved to a single synID (syn12345678). Unlike files, which are automatically versioned anytime the file is updated, saving changes to a table, view, or dataset will not automatically create a new version. Instead, you decide when to manually create a version for your table, view, or dataset.

Creating a new version adds a number to the parent synID (e.g. syn12345678.2), which can be used to reference or query that version within Synapse. Navigating to the parent synID (syn12345678) will always display the most recent changes to the view, regardless of whether you have included them in a version.

Creating a Version

From a table, view, or dataset, navigate to the Tools menu, then select Create a New Version from the dropdown menu. Add a label and a comment about this version. Any text entered in the label field is appended with the word “Version” in the version history. For example, entering “Final” as a label appears as “Version Final” in your version history.

Selecting and Sharing Versions

Navigate to Tools menu and select Version History to view the version history information.

Click on your desired version number. After the page updates, your selected version is indicated in bold text in the Version History table, and the view is displayed below.

To return to the current version, click Go to the current version in the top left of the version history.

To share a version, copy the URL at the top of the page to share it with other Synapse users, or you can mint a Digital Object Identifier (DOI) for the selected version. Minting a DOI for a specific version can be useful if you want to publish a snapshot of your data at a specific point in time.

Querying a Version

To query a specific version of a table, view, or dataset, append the version number after the synID. For example, to query the second version of syn12345678, enter the following in the Advanced Search box:

SELECT * FROM syn12345678.2

For more information and further instructions, see Querying Tables, Views, and Datasets.

Deleting a Version

To remove a version, navigate to the Tools menu and select Version History. Click on the “x” on the right hand side of the table to delete a specific version. Deleting the most recent version only deletes the record of the version; it does not delete the most recent changes to your table content. Navigating to the parent ID (syn12345678) will always display the most recent updates to a table, view, or dataset, regardless of whether they are included in a version.

Once deleted, a version number cannot be reused. Any URL, wiki links, or DOIs pointing to a deleted version will break.