ossfs metadata cache stores object metadata in client memory to reduce request latency to OSS. It improves performance for workloads with high read/write IOPS (input/output operations per second) on a single server — such as AI training data reads, big data queries, and hot-data access patterns.
Metadata cache trades consistency for performance. Avoid enabling it in scenarios that require up-to-date metadata at all times.
How it works
ossfs uses client memory to cache object metadata fetched from OSS.
First access: When you access an object or directory under the ossfs mount point for the first time, ossfs fetches the metadata from OSS and stores it in the local cache.
Subsequent access: If the cache deletion policy is disabled or the cache has not expired, ossfs reads metadata directly from the local cache — no OSS request is sent.
Cache updates: ossfs updates the local cache based on two policies: cache expiration (controlled by
stat_cache_expire) and cache capacity (controlled bymax_stat_cache_size).Single-server scope: The metadata cache is local to a single server. You cannot synchronize cache state between multiple servers or mount multiple buckets to multiple local file systems simultaneously.
Use cases
ossfs metadata cache is well-suited for:
Single-server high-IOPS workloads: Any server that reads OSS data at high frequency benefits from reduced per-request latency.
Read-heavy distributed workloads: In distributed environments where data changes infrequently — such as AI training datasets, AI model files, and big data queries — caching reduces OSS API calls and lowers QPS (queries per second).
Mode comparison
The following table shows how stat and ls behave with and without metadata cache.
| State | Command | Requests sent | Source of metadata | Performance |
|---|---|---|---|---|
| Cache disabled | stat | HeadObject per object | OSS bucket | Slower |
| Cache disabled | ls | ListObject + HeadObject per object | OSS bucket | Slower |
| Cache enabled, not expired | stat | None | Local memory | Faster |
| Cache enabled, not expired | ls | ListObject only | Local memory (for individual objects) | Faster |
Parameters
Configuring these parameters relaxes metadata consistency. If other clients write to the same bucket, ossfs may serve stale metadata until the cache expires.
| Parameter | Description | Default |
|---|---|---|
max_stat_cache_size | Maximum number of objects or directories to cache in memory. Set to 0 to disable metadata cache. If memory is sufficient, set a larger value to improve performance. For example, -omax_stat_cache_size=1000000 uses approximately 400 MB. | 100000 (~40 MB) |
stat_cache_expire | Time-to-live (TTL) in seconds for each cache entry. Set to -1 to disable the cache deletion policy (entries never expire). Only disable expiry if objects in the mounted bucket are never updated after mounting. For example, -ostat_cache_expire=1800 sets a 30-minute TTL. | 900 seconds |
readdir_optimize | When enabled, ossfs skips HeadObject requests for gid and uid when running ls, which reduces API calls significantly. HeadObject is still sent when an object's size is 0. However, a specific number of HeadObject requests may still be sent due to reasons such as permission checks. To enable, specify -oreaddir_optimize. | false |
Disabling expiry (-1) means ossfs never refreshes cached metadata from OSS. If other processes modify objects in the bucket, ossfs will serve stale metadata until the process restarts.
Cache management mechanism
ossfs manages cache entries according to the following rules.
| Cache status | Action |
|---|---|
| Cached; eviction policy disabled, or cache not expired | Read directly from cache |
| Cached; cache expired | Update the cache from OSS |
| Not cached; capacity available | Add to cache |
| Not cached; capacity full; eviction policy enabled | Scan cache and remove expired entries |
| Not cached; capacity full; eviction policy disabled | Remove the least recently used (LRU) entries |
Usage notes
Enabling `readdir_optimize`
Specify -oreaddir_optimize to speed up list and find operations. This is effective when gid and uid metadata is not required by your application.
Enabling metadata cache disables symbolic link support.
Multi-client environments
In environments where multiple clients write to the same bucket, enabling metadata cache can cause stale reads. To maintain data consistency, disable the cache with -omax_stat_cache_size=0. Disabling the cache increases OSS API calls and may incur additional costs.
For workloads that require strong consistency across multiple clients, use Cloud Storage Gateway (CSG) or Cloud Parallel File Storage (CPFS) instead of ossfs.
Large object sets
If the number of frequently accessed objects exceeds max_stat_cache_size, the cache evicts entries continuously, degrading performance. Increase max_stat_cache_size to cover your working set.
If the total number of objects is large and server memory is insufficient to cache them, use ossutil or OSS SDKs for bulk operations, or mount with CSG or CPFS.
Multiple mount points
If your workload accesses a large number of frequently used objects, create separate ossfs mount points for different subdirectories. This distributes cache pressure across multiple instances.