Create a Location
Name an external storage root in Studio, read through a Connection.
In development
Name a folder of recordings once, and everyone in the Project can find its files by that name. The Location keeps an inventory of the files, so readers do not list the bucket again, and a pinned commit keeps the same file list.
Before you start
- Spiral Studio.
- Permission to create Locations and Tables in the Project.
- A Connection that you can bind, whose URI contains the root. Connect Amazon S3, Cloudflare R2, Ceph, or Hugging Face first.
Create the Location in Studio
- Select the branch in the top bar.
- Select Create resource → Location.
- Enter a name, for example
recordings. - Enter the root in URI. A root ends with
/. See Roots by provider. - Select the Connection whose credentials read the root in Connection. The URI must lie inside the Connection URI. Selecting a Connection with an empty URI fills in the Connection URI, which you can then extend. Spiral reads no storage without credentials, so a public bucket or repository also needs a Connection.
- Create the Location.
The new Location has an empty inventory.
Roots by provider
| Storage | Root | Connection |
|---|---|---|
| Amazon S3 | s3://example-robotics/recordings/ | An aws Connection |
| Cloudflare R2 | s3://example-robotics/recordings/ | An r2 Connection |
| Ceph | s3://example-robotics/recordings/ | A ceph Connection, which names the gateway's endpoint |
| Hugging Face | hf://datasets/example-robotics/robot-runs@main/data/ | A hugging_face Connection |
A Hugging Face root names a branch, a tag, or a commit after the repository. Reading a Location through a Google Cloud Storage Connection is planned.
Verify the result
The Location appears in the Project tree, and its Definition tab shows the root and the Connection. Its inventory stays empty until you refresh the Location, which lists the root and publishes the inventory and a new Location version in one commit.
Troubleshooting
| Problem | Cause |
|---|---|
| The URI is outside the Connection URI | The root must lie under the Connection URI: the same bucket and a prefix that starts with the Connection's prefix, or the Connection's repository. |
| The URI is rejected | A root is absolute and ends with /. Each segment must be a plain name: not empty, not . or .., and without an encoded /, a ?, or a #. A Hugging Face root names a revision, as @main/. |
| The Connection is not in the list | You do not hold connection:bind on it, or it is in another Project. |
Found a problem? Edit this page or report an issue.