About folders

Cloud Storage offers various ways to organize your data, and folders play an important role in this process. Understanding the different types of folders available can help you choose the most suitable one for your specific needs.

This page provides an overview of the different folder types in Cloud Storage, with a focus on how folders function within buckets when hierarchical namespace is enabled.

Folder types

In Cloud Storage, there are three main types of folders:

• Simulated folders: A typical Cloud Storage bucket organizes objects in a flat namespace. Using the Google Cloud console and Google Cloud CLI, you can simulate folders that mimic the file tree to help you organize data in your bucket. For more information about simulated folders, see Simulated folders.

• Folders: In a bucket with hierarchical namespace enabled, you can create actual folders that contain objects or other folders. You can also perform operations like renaming folders and listing folders. The hierarchical structure and folder management operations improve performance, consistency, and management for file-oriented and data-intensive workloads.

• Managed folders: Managed folders enable you to apply granular access controls to your objects, enhancing security and control over your data. You can use managed folders in buckets with or without hierarchical namespace enabled. For more information about managed folders, see Managed folders.

Folder 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.