This page provides information about folders in buckets withhierarchical namespace enabled.

Overview

Folders exist as a resource in buckets withhierarchical namespaceenabled. You can organize objects within folders in a file system-likestructure. Cloud Storage provides folder management APIs that enableoperations such as creating, deleting, renaming, and listing folders, as well asretrieving folder metadata.

Folder metadata

A folder's metadata contains structured information about the folder. Fordetailed information about folder metadata, see theFolder resource inthe 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 alwaysstorage#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 validobject names, includingthose with leading, trailing slashes (/) or consecutive slashes. Eachforward slash (/) in an object name represents a folder.The following table shows examples of the relationship between object namesand their corresponding location in the folder hierarchy:

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

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

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

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

• Sensitive or personally identifiable information (PII): Folder names aremore broadly visible than folder metadata. For example, folder names appearin URLs and when listing folders or objects in a bucket. Don't includesensitive information or PII in folder names.

What's next

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