All Products
Search

This Product

    MaxCompute:External Volume operations

    Document Center

    MaxCompute:External Volume operations

    Last Updated:Mar 26, 2026

    An external volume is a distributed file system and unstructured data storage solution provided by MaxCompute that maps an OSS directory to a MaxCompute project, letting you query and process files stored in Object Storage Service (OSS) directly — without importing data into MaxCompute tables. This reduces data redundancy and transmission overhead.

    Common operations

    Operation Description Who can perform
    Create an external volume Creates an external volume in a project External volume owner; project owner; users with the Super_Administrator or Admin role
    List external volumes and view directory structure Lists all external volumes or views the directory structure of a specific volume —
    Delete an external volume Deletes an external volume —

    Prerequisites

    Before you begin, ensure that you have:

    • MaxCompute client (odpscmd) V0.43.0 or later. For installation instructions, see MaxCompute client (odpscmd).

      To run commands on the DataStudio page or SQL Query page of the DataWorks console, the integrated MaxCompute client must be V0.43.2 or later. Run Show version; to check the version. For more information, see Use MaxCompute in DataWorks.

    • SDK for Java V0.43.0 or later, if you use the Java SDK.

    • An Alibaba Cloud account or RAM user with access permissions on OSS. For authorization steps, see STS authorization for OSS.

    Create an external volume

    Syntax

    vfs -create <volume_name>
    -storage_provider oss
    -url <oss://oss_endpoint/bucket_name/directory_name>
    [-acd <true|false>]
    -role_arn <arn:aliyun:xxx/aliyunodpsdefaultrole>

    Parameters enclosed in [ ] are optional.

    Parameter Required Description
    volume_name Yes Name of the external volume to create.
    storage_provider Yes Storage provider. Set to oss. OSS is the only supported provider.
    url Yes OSS directory where data files are stored. Format: oss://<oss_endpoint>/<bucket_name>/<directory_name>. Both the bucket name and the level-2 directory name are required. See the notes below for endpoint requirements.
    acd No Whether to auto-create the OSS directory if it does not exist. Default: false. See the notes below for behavior details.
    role_arn Yes Alibaba Cloud Resource Name (ARN) of the RAM role that has OSS access permissions. To get the ARN, see Use temporary credentials provided by STS to access OSS.

    Notes on the `url` parameter:

    • Use an OSS internal endpoint to avoid extra charges for internet traffic — for example, oss://oss-cn-beijing-internal.aliyuncs.com/my-bucket/my-dir. For a full list of internal endpoints, see Regions and endpoints.

    • Deploy the OSS bucket in the same region as your MaxCompute project to avoid cross-region connectivity issues.

    Notes on the `acd` parameter:

    • false (default): If the specified directory does not exist, the command fails with an error.

    • true: If the directory does not exist, MaxCompute automatically creates it using the permissions granted via role_arn. If the directory already exists, MaxCompute uses it directly.

    Important

    When acd is set to true and the directory is auto-created, MaxCompute does not delete the directory if the external volume creation subsequently fails.

    After the external volume is created, its path follows the format odps://<project_name>/<volume_name>. This path can be used by the Spark engine and MapReduce tasks.

    Example

    Create an external volume named test_ext_l:

    vfs -create test_ext_l -storage_provider oss -url oss://oss-cn-hangzhou-internal.aliyuncs.com/test/ex_volume/ -role_arn acs:ram::xxxxxxx:role/aliyunodpsdefaultrole;

    List external volumes and view directory structure

    Syntax

    -- List all external volumes in the project
vfs -ls /;

-- View the directory structure of a specific external volume
vfs -ls [-R] /<volume_name>;
    Parameter Required Description
    volume_name Yes Name of the external volume.
    -R No Recursively lists subdirectories.

    Examples

    List all external volumes:

    vfs -ls /;

    Expected output:

    Found 2 items
drwxrwxrwx - 0 2023-03-11 12:06 /test_ext_l -> oss://oss-cn-shanghai-internal.aliyuncs.com/test/ex_volume
drwxrwxrwx - 0 2023-03-21 07:33 /myfirst_volume4 -> oss://oss-cn-shanghai-internal.aliyuncs.com/paristech/data
    External volumes you do not have permission to access are not displayed in the output. To grant a user access, run the following command. The available permissions are Read, Write, and CreateVolume.
    grant Read on volume myfirst_volume4 to RAM$xxxxxx:dev01;

    View the directory structure of `test_ext_l`:

    vfs -ls -R /test_ext_l;

    Expected output:

    drwxrwxrwx - 0 2023-03-27 07:31 /test_ext_l/test -> oss://oss-cn-hangzhou-internal.aliyuncs.com/test/ex_volume/test

    Delete an external volume

    Syntax

    -- Syntax 1
vfs -rm -r /<volume_name>;

-- Syntax 2
vfs -rmv /<volume_name>;
    Parameter Required Description
    volume_name Yes Name of the external volume to delete.

    Example

    Delete the external volume named test_ext_l:

    vfs -rm -r /test_ext_l;

    What's next