Docs

Big Data File Storage

Best practices

Best practices for metadata consistency

The data lake mode of CloudFS works by leveraging high-speed storage media to provide read and write acceleration for TOS. In the metadata service, the TOS bucket is mounted, mapping the metadata of CloudFS and TOS to provide a unified metadata view and namespace.

Metadata consistency

CloudFS provides a unified metadata view. If the latest TOS data, rather than an older version, can be read from CloudFS, the data is considered consistent. In what situations should metadata consistency be considered? This is mainly related to how users write data. Write acceleration is a core feature of CloudFS. The main usage scenario is to use write acceleration, where data is written directly to CloudFS and then asynchronously flushed to TOS. In this case, metadata consistency does not need to be considered, as the latest data can always be read. This is also the most recommended usage method. In certain cases, it is necessary to bypass CloudFS and write directly to TOS while still using read acceleration. For these files or directories, the latest data cannot be read, so metadata consistency needs to be considered.

How to fix it

Based on extensive practical experience, CloudFS provides different solutions for metadata consistency according to usage scenarios.

Metadata loading

When data is written to TOS bypassing CloudFS, TOS metadata can be proactively loaded into CloudFS via the CLI to obtain the latest data. Note that CloudFS consumes TOS events and can only consume incremental events after the synchronization feature is enabled. Therefore, if data already exists in the TOS bucket before it is mounted into CloudFS, the existing metadata must be proactively loaded into CloudFS. For details, see the documentation Cache acceleration CLI commands.

Automatically refreshing metadata based on timestamps

CloudFS also supports the ability to automatically refresh metadata based on timestamps. This feature is disabled by default and can be enabled through a client configuration (cfs.filesystem.sync-interval metadata synchronization interval). There are several different configuration methods:

When configured as -1 (default), for a metadata access request to a path, metadata synchronization is triggered only when the path does not exist, loading the metadata into CloudFS (corresponding to process 1 in the diagram). Subsequent accesses will not trigger new synchronization (corresponding to process 4 in the diagram).

When configured as greater than 0, such as 30, this means that during metadata access, the most recent load time of the path or its parent path is compared with the current access time to determine whether the interval is within 30 seconds. If the condition is met, the metadata is considered valid and does not need to be refreshed; otherwise, metadata synchronization is required (corresponding to processes 3 and 5 in the diagram).

warning

The smaller the metadata synchronization interval is configured, the more frequently path metadata synchronization will be triggered. This operation can sometimes be resource-intensive. For example, for List or Rename requests on wide directories, triggering synchronization increases the time required for metadata requests (the duration is related to the directory size) and may also affect other metadata access requests for the directory, resulting in increased latency. Metadata synchronization adds significant overhead for metadata comparison and synchronization. If you need to use this feature, you must tolerate the increased request latency caused by metadata synchronization. For details, please contact Volcano Engine technical support engineers.

Last updated: 2026.02.02 11:22:43