Named objects provide a method to store and retrieve content by user-provided name, rather than by Swarm-assigned UUID. This structure makes it possible to use third-party protocols, such as S3.

A named object refers to a client-named object (such as a video file) contained within a bucket. Using meaningful bucket and object names creates friendly, readable URLs to stored content.

Named versus Unnamed

The illustration below contrasts two data objects-one named and one unnamed-in a cluster domain named cloud.com. The named object is stored in a bucket named photos, and the unnamed object is identified by a UUID at the root of the domain:

A Swarm private or public cloud can have whatever combination of object types needed:

• All unnamed objects

• All named objects (which must be assigned to buckets)

• Both named and unnamed objects in any proportion

Pathnames to named objects must be unique:

• Every object within a bucket must have a unique name.

• Every bucket within a domain must have a unique name.

• Two or more objects in the same cluster may have the same name, if they reside in different buckets or domains.

Accessing Named Objects

Access a named object by combining two strings: a domain name and a pathname to the object, in this form:

In this example:

• cluster.example.com is the domain name.

• marketing is the bucket name. Buckets are required.

• ads/about-object-naming.m4v is the object name (ads/ is part of the name).

Creating Named Objects

The following cURL examples detail creating a bucket and creating named objects within that bucket.

Access to a domain without protection settings set to allow only a specific set of users POST privileges is required to use these examples. Create a domain with the following protection setting if access to a development environment is available:

Contact the cluster administrator or see Resolving Duplicate Domain and Bucket Names if unsure how to create a domain.

The following examples assume the domain is named test.example.com and commands are sent to a node with IP address is 172.16.0.35.

Open a terminal window and execute the following to create a bucket and objects:

1. Create a bucket. (replicate=immediate is the Replicate On Write option.)

2. Create a named object in the bucket.

3. Verify the object in a browser. Enter the following in the Address or Location field: 

4. Change the object by adding data to it. 

5. Refresh the browser to see the updated object.

Overwriting Named Objects

Overwrite a named object that currently exists in a storage cluster using the POST method and an HTTP request.

Include the If-None-Match: * request header to prevent overwriting an existing object.

• Swarm writes the named object if it does not exist.

• Swarm responds with an HTTP 412 Precondition Fail error if the named object exists.

See SCSP WRITE.

Deleting Named Objects

Swarm allows deleting a bucket or domain that still contains content.

Use one of these methods to avoid creating orphans:

• Delete the content first before deleting the bucket or domain.

• Add the recursive query argument when deleting the domain or bucket, which causes the health processor to remove asynchronously any content it finds in the deleted context.

Swarm may generate replication and search indexer warnings in the syslog and Admin Console as attempts are made to access content missing the parent context if one of the above methods is not performed. The logs include error messages displaying the alias UUIDs of the missing bucket or domain:

See Restoring Domains and Buckets for how to delete orphaned content.