Aliases

What is an alias?

An alias is a pointer, on the Platform, that refers to a file in a cloud storage repository (AWS S3 bucket, or Google Cloud Storage). Aliases enable files in cloud storage repositories outside the Platform to be manipulated on the Platform, for instance, to input them to computational tasks.

An alias for a file can be used in much the same way as a file on the Platform: you can set its metadata, copy it between projects, download it, and use it as an input to tasks. Operations like these affect the way the target file is used on the Platform, but do not edit the content of the file itself. There are, however, some differences between Platform files, and external files referred to by aliases. These are described in detail below.

Recognizing aliases

In the visual interface of the Platform, files that are aliases are marked with an icon of a bucket and a small black arrow, as shown below:

Creating aliases

Access to cloud storage repositories from the Platform is mediated by volumes: to use a file in your cloud storage on the Platform, you must first create a volume that authorizes the Platform to access the objects in a specific cloud storage repository. Once you've created a volume associated with the cloud storage repository, there are two ways to create an alias: by importing a file from a volume to the Platform, or by exporting a file from the Platform to a volume.

Importing from a volume to the Platform

If the cloud storage account used for your volume contains files, you can import files from the volume to the Platform. Importing a file creates an alias for the file on the Platform, which can then be used in computation. A walk-through of the procedure in the case of Amazon Web Services' cloud storage is given in the AWS Cloud storage tutorial.

Exporting from the Platform to a volume

You can add files from the Platform to your cloud storage by exporting them to a volume created using the cloud storage account. Please note that export to a volume is available only via the API (including API client libraries), and through the Seven Bridges CLI.

The export operation will do the following:

1. Copy the content of the Platform file to the cloud storage that you used to create the volume;
2. Replace the Platform file with an alias that refers to the copied file's content.

In other words, the original project file will become an alias for the newly exported object on the volume; the file will appear in your project as before, but will be only a pointer to the exported file now stored elsewhere.

If there are no copies of the exported file anywhere else on the Platform (for instance, in another project), then the original file will be deleted from the Platform storage, and so will no longer count towards your total storage costs.

Exporting takes advantage of the fastest copying procedure applicable for the cloud storage(s). The copying takes place asynchronously, so you can check on its progress using the API request to list imports.

Differences between aliases and Platform files

Since aliases are pointers to files not hosted on the Platform, there are some differences between their behavior and that of regular Platform files.

Storage charges

Aliases do not count towards your storage costs.

Change tracking

The Platform cannot track changes to the file an alias points to. Since aliases refer to files external to the Platform by their file names (or keys, depending on the cloud service), an alias remains operational as long as there is an object matching the file name (or key) in the cloud storage used to set up the volume. This remains true if the contents of the file in question change.

Consequently, we recommend that you maintain control over the contents of the cloud storage account used for the volume, particularly objects in it that have been brought onto the Platform as aliases. This consideration is essential to guarantee the reproducibility of tasks on the Platform using aliases.

'Broken' aliases

A volume is required to create an alias. If that volume is deleted or made unavailable, an alias will continue to exist on the Platform as a "broken reference" to the file that was stored on it. Although the content of the alias will not be readable by the Platform, the alias will maintain its metadata defined on the Platform as well as its association with tasks in which it was used or created.

Since aliases are defined in terms of the name of the volume that they are stored in, a 'broken' alias may become readable again by creating a new volume that has the same name as the original volume and is associated with the same cloud storage repository as it.

Deleting alises

Deleting an alias on the Platform never results in the corresponding object being deleted from the connected cloud storage. To do so, you must delete objects manually from your cloud storage account, using your cloud account credentials.

Exporting alises

Exporting to a volume is an operation that copies a file hosted on the Platform to the cloud storage account associated with the volume. This operation will not work on a Platform file that is itself an alias.

Updating an alias's bucket, prefix, or location

An alias will always point to the same location on its original cloud storage. Changes to the originating volume, like updating its prefix or the cloud storage account the volume is associated with, do not affect the alias after it has been created.

The only exception to this rule are changes to the volume's access configuration. If a volume is deleted, renamed, made inactive or its credentials have been revoked or invalidated in any way, then any aliases to cease functioning.

Aliases and archiving

Aliases cannot be archived using the Platform's Archive feature.