Limits on OSS directory levels
Object Storage Service (OSS) uses a flat storage model rather than the hierarchical structure of traditional file systems. You can include forward slashes (/) in an object name to simulate directories, similar to folders in a file system. The following constraints apply when designing a simulated directory structure.
Number of directory levels
OSS places no limit on the number of simulated directory levels. You can include any number of forward slashes (/) in an object name. For example, the object name folder1/subfolderA/subfolderB/document.txt represents an object named document.txt stored three levels deep under folder1/subfolderA/subfolderB/.
Object name length
While the number of directory levels is unlimited, the total length of an object name—including all simulated directory segments—cannot exceed 1,024 characters. This is the practical constraint on directory depth: each additional level consumes characters from that limit. When designing deep directory structures, keep the full object name within 1,024 characters.
API operations and performance
Deeply nested simulated directories can cause management and performance problems. Avoid overly granular directory structures for the following reasons:
Higher management complexity. Batch operations such as moving, copying, and deleting objects require each directory level to be explicitly specified. More levels increase complexity and the chance of errors.
Slower query performance. API operations use prefixes and delimiters to filter objects. Long path prefixes increase the compute cost of each query and may trigger deeper recursive searches, degrading performance.
Longer API response times. More directory levels require more processing before OSS can return results. Under high data volumes or poor network conditions, this adds noticeable latency.
Greater network bandwidth consumption. Each API response includes the full object key—all directory segments plus the object name. Deeper structures produce longer keys, which increases the total data transferred per response and amplifies the impact during large-scale data migrations.
Design recommendations
Design your directory structure around actual business needs, balancing operational convenience, query performance, and resource efficiency. Prefer a flat or moderately nested structure, and use meaningful naming conventions and object tags to organize and retrieve objects without adding unnecessary directory depth.