About folders in buckets with hierarchical namespace enabled

This page provides information about folders in buckets with hierarchical namespace enabled.

Overview

Folders exist as a resource in buckets with hierarchical namespace enabled. You can organize objects within folders in a file system-like structure. Cloud Storage provides folder management APIs that enable operations such as creating, deleting, renaming, and listing folders, as well as retrieving folder metadata.

Folder metadata

A folder's metadata contains structured information about the folder. For detailed information about folder metadata, see the Folder resource in the Cloud Storage JSON API reference documentation.

The key components of a folder metadata are as follows:

• bucket: The name of the bucket where the folder resides. For example, my-bucket.
• id: A unique identifier for the folder within the bucket. For example, hns-bucket/dir1/.
• kind: The resource type. For a folder, this value is always storage#folder.
• name: The name of the folder. For example, dir1/.
• selfLink: A URL that references the folder in the Cloud Storage API.
• timeCreated: The timestamp when the folder was created. For example, 2023-05-05T16:32:08.878000+00:00.
• updated: The timestamp when the folder was last updated. For example, 2024-05-06T16:32:08.878000+00:00.

Considerations

When creating folders, consider the following:

• Object and folder names: Buckets with hierarchical namespace enabled, support all valid object names, including those with leading, trailing slashes (/) or consecutive slashes. Each forward slash (/) in an object name represents a folder. The following table shows examples of the relationship between object names and their corresponding location in the folder hierarchy:

  Object name	Location in the folder hierarchy
  foo.txt	Every bucket includes a root folder. Object foo.txt resides under the root folder of the bucket.
  dir1/foo.txt	Object foo.txt resides within a top-level folder named dir1/. The top-level folder is distinct from the root folder.
  dir1/	The trailing slash in object names like dir1/ indicates that the object resides within the folder. In this example, the object name dir1/ is the same as the parent folder name dir1/.
  dir1//foo.txt	Object foo.txt resides in a second-level folder named dir1//, a child folder of dir1/.

• Maximum folder depth: Buckets with hierarchical namespace enabled support a maximum folder depth of 50. As a result, object names cannot have more than 50 slashes (/).

• Maximum folder name size: 512 bytes (UTF-8 encoded).

• Automatic folder creation: Creating a new object automatically creates any non-existent folders specified in the object's path. For example, creating an object named dir1/foo.txt automatically creates the folder dir1/ if it doesn't already exist.

What's next

• Create and manage folders.
• Rename a folder.
• Optimize folder management.