CLI reference-Data Lake Formation(DLF)-阿里云帮助中心

This document describes how to install, configure, and use the DLF CLI to efficiently manage data in DLF.

Prerequisites

Your ECS instance must meet the following requirements:

The ECS and DLF instances must be in the same region. For a list of supported regions, see Endpoints and public network access.
The ECS instance must be in a VPC that has been authorized for DLF. If authorization is not configured, see Configure a VPC whitelist.
The ECS instance must have JDK 11 or later installed.

Installation

Download the dlf-cli-20250818163820.tar.gz.
Use the scp command to upload the tar package to a destination directory on your ECS instance.
```
scp dlf-cli-20250818163820.tar.gz username@ecs-ip:/path/to/destination
```
Log in to your ECS instance, navigate to the destination directory, and run the following command to extract the package.
```
tar -xzvf dlf-cli-20250818163820.tar.gz
```

Use the vim command to edit the dlf-cli/conf/dlf-cli.properties configuration file, and configure the following parameters.

vim dlf-cli/conf/dlf-cli.properties

Parameter	Description	Example
`uri`	The URI of the DLF REST Catalog Server. The format is `http://[region-id]-vpc.dlf.aliyuncs.com`. For more information about the region ID, see Endpoints and public network access.	http://cn-hangzhou-vpc.dlf.aliyuncs.com
`dlf.region`	The region ID. For more information, see Endpoints and public network access.	cn-hangzhou
`dlf.access-key-id`	The AccessKey ID of your Alibaba Cloud account or RAM user. Note The RAM user or RAM role must have the required API permissions. For more information, see RAM authorization action reference.	-
`dlf.access-key-secret`	The AccessKey Secret of your Alibaba Cloud account or RAM user.	-
`dlf.open-api-endpoint`	The DLF OpenAPI endpoint. For more information, see Endpoints. If you leave this parameter empty, its value is derived from the uri parameter.	dlfnext.cn-hangzhou.aliyuncs.com

(Optional) Run the echo $JAVA_HOME command to verify the JAVA_HOME environment variable. If the output is empty or the variable is not set to your JDK 11 installation path, you must reconfigure the JAVA_HOME variable.
```
export JAVA_HOME=<JDK_11_PATH>
```
For example:
```
[root@iZxxxZ lib]# export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-11.0.25.0.9-2.0.1.1.al8.x86_64
[root@iZxxxZ lib]# echo $JAVA_HOME
/usr/lib/jvm/java-11-openjdk-11.0.25.0.9-2.0.1.1.al8.x86_64
```

Authorization information

RAM access control

The following table describes the authorization information for each API. Use this information in the Action element of a Resource Access Management (RAM) policy statement to grant a RAM user or RAM role the permissions to call these APIs.

Column	Description
Operation	The specific permission.
Access level	The access level: Write, Read, or List.
Resource type	The resource type that supports authorization. An asterisk (\*) indicates a required resource type. For operations that do not support resource-level authorization, the value is `All resources`.
Condition key	The condition keys defined by the cloud product.
Associated operation	Other permissions required to call the operation successfully.

Operation	Access level	Resource type	Condition key	Associated operation
dlf:See the specific API	See the specific API	\*All resources	None	None

RAM access control updates typically take about one minute to take effect.

ACL permission management

For more information, see Authorization management.

Role command

list - Role list

Retrieves a list of all role names and supports pagination and filtering.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:ListRoles

get

All resources

*

None

Usage

./dlf-cli/bin/dlf role list \
[--max_results <max_results>] \
[--page_token <page_token>] \
[--role_name <role_name>]

Parameters

Parameter	Type	Required	Description
`--max_results`	integer	No	The maximum number of results to return per page. If you omit this parameter, the system's default value is used.
`--page_token`	string	No	The pagination token used to retrieve the next page of results. Omit this parameter for the first request. For subsequent requests, use the token from the previous response.
`--role_name`	string	No	Filters results by role name. Supports fuzzy matching.

Example

./dlf-cli/bin/dlf role list

Result

2025-07-07 17:12:02 : {
  "nextPageToken" : null,
  "roles" : [{
    "createdAt" : 1744428101414,
    "createdBy" : "xxxx",
    "description" : "super_administrator(system role)",
    "displayName" : "super_administrator",
    "isPredefined" : "true",
    "roleName" : "super_administrator",
    "rolePrincipal" : "xxxx",
    "updatedAt" : 1744428101414,
    "updatedBy" : "xxxx",
    "users" : [{
      "createdAt" : 1747744999611,
      "createdBy" : "xxx",
      "displayName" : "xxx",
      "type" : "RAM_USER",
      "updatedAt" : 1747744999611,
      "updatedBy" : "xxxx",
      "userId" : "207384147744632137",
      "userName" : "xxxx",
      "userPrincipal" : "xxxx"
    }]
  }]
}

get - Get a role

Retrieves the details of a specified role by its role principal.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:GetRole

get

*All resources

*

None

Usage

./dlf-cli/bin/dlf role get \
--role_principal <role_principal>

Parameters

Parameter	Type	Required	Description
`--role_principal`	String	Yes	The role principal, which uniquely identifies the role.

Example

./dlf-cli/bin/dlf role get \
--role_principal 'acs:dlf::104568******:role/engineer'

Response:

2025-07-07 17:12:02 : {
  "createdAt" : 1749435901626,
  "createdBy" : "xxxx",
  "description" : null,
  "displayName" : null,
  "isPredefined" : "false",
  "roleName" : "engineer",
  "rolePrincipal" : "xxxx",
  "updatedAt" : 1750404792198,
  "updatedBy" : "xxxx",
  "users" : [ {
    "createdAt" : 1744428101252,
    "createdBy" : "",
    "displayName" : "xxxx",
    "type" : "RAM_USER",
    "updatedAt" : 1744428101252,
    "updatedBy" : "",
    "userId" : "xxxx",
    "userName" : "xxxx",
    "userPrincipal" : "xxxx"
  }]
}

Create role

Creates a new role. You can specify a role name, a display name, and a description.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:CreateRole

create

all resources

*

None

Synopsis

./dlf-cli/bin/dlf role create \
--role_name <role_name> \
--display_name <display_name> \
[--description <description>]

Parameters

Parameter	Type	Required	Description
`--role_name`	string	Yes	The unique identifier of the role.
`--display_name`	string	Yes	The display name of the role, shown in the user interface.
`--description`	string	No	A description of the role's purpose or permission scope.

Example

./dlf-cli/bin/dlf role create \
--role_name 'test_viewer' \
--display_name 'test viewer' \
--description 'test for viewer'

Output

2025-07-07 17:14:30 : success

alter - Update role

Updates the display name or description for a specified role.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:UpdateRole

update

All resources

*

None

Synopsis

./dlf-cli/bin/dlf role alter \
--role_principal <role_principal> \
--display_name <display_name> \
[--description <description>]

Parameters

Parameter	Type	Required	Description
`--role_principal`	string	Yes	The principal identifier of the role to update.
`--display_name`	string	Yes	The new display name for the role.
`--description`	string	No	The new description for the role, outlining its purpose or permission scope.

Example

./dlf-cli/bin/dlf role alter \
--role_principal 'acs:dlf::104568******:role/engineer' \
--display_name 'engineer role'

Output

2025-07-08 10:00:54 : success

drop: Delete a role

Deletes the specified role.

RAM access control

Actions

Access level

Resource type

Condition key

Associated actions

dlf:DeleteRole

delete

*All resources

*

None

Usage

./dlf-cli/bin/dlf role drop \
--role_principal <role_principal>

Parameters

Parameter	Type	Required	Description
`--role_principal`	String	Yes	The principal that uniquely identifies the role.

Example

./dlf-cli/bin/dlf role drop \
--role_principal 'acs:dlf::104568******:role/test_viewer'

Output

2025-07-08 10:00:54 : success

list_users - List users associated with a role

Retrieves a paginated list of users associated with a specified role.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:ListRoleUsers

get

*All resources

*

None

Usage

./dlf-cli/bin/dlf role list_users \
--role_principal <role_principal> \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--role_principal`	String	Yes	The role principal that uniquely identifies the target role.
`--max_results`	Integer	No	The maximum number of results to return per page. If you omit this parameter, the system uses a default value.
`--page_token`	String	No	The token that specifies the next page of results to return. Omit this parameter to retrieve the first page. For subsequent pages, use the `nextPageToken` value from the previous response.

Example

./dlf-cli/bin/dlf role list_users \
--role_principal 'acs:dlf::1045689747920334:role/engineer'

Output

2025-07-08 09:59:58 : {
  "nextPageToken" : null,
  "users" : [ {
    "createdAt" : 1744428101252,
    "createdBy" : "",
    "displayName" : "dw_test",
    "type" : "RAM_USER",
    "updatedAt" : 1744428101252,
    "updatedBy" : "",
    "userId" : "205775142194523069",
    "userName" : "dw_test",
    "userPrincipal" : "acs:ram::1045689747920334:user/dw_test"
  } ]
}

Grant a role to users

Grants a role to one or more users.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:GrantRoleToUsers

create

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf role grant_users \
--role_principal <role_principal> \
--user_principals <user_principals>

Parameters

Parameter	Type	Required	Description
`--role_principal`	string	Yes	The unique principal of the target role.
`--user_principals`	string	Yes	A string containing a JSON array of user principals. For example, `'["user1","user2","user3"]'`.

Example

./dlf-cli/bin/dlf role grant_users \
--role_principal 'acs:dlf::1045689747920334:role/engineer' \
--user_principals '["acs:ram::104568******:user/starrocks_test"]'

Output

2025-07-08 10:00:54 : success

Revoke users from a role

Disassociates the specified users from a role.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:RevokeRoleFromUsers

*All resources

*

None

Usage

./dlf-cli/bin/dlf role revoke_users \
--role_principal <role_principal> \
--user_principals <user_principals>

Parameters

Parameter	Type	Required	Description
`--role_principal`	string	Yes	The principal that uniquely identifies the target role.
`--user_principals`	string	Yes	A string containing a JSON array of user principals. For example: `'["user1","user2","user3"]'`.

Example

./dlf-cli/bin/dlf role revoke_users \
--role_principal 'acs:dlf::1045689747920334:role/engineer' \
--user_principals '["acs:ram::1045689747920334:user/starrocks_test"]'

Output

2025-07-08 10:14:37 : success

User commands

list

Lists users. You can filter the list based on criteria such as username and user type. This command supports pagination.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:ListUsers

get

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf user list \
[--user_name <user_name>] \
[--user_type <user_type>] \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--user_name`	String	No	Filters the results by username. Supports fuzzy matching.
`--user_type`	String	No	Filters the results by user type, such as `RAM_USER` or `RAM_ROLE`.
`--max_results`	Integer	No	The maximum number of results to return per page. If omitted, the system uses a default value.
`--page_token`	String	No	The pagination token from a previous response to retrieve the next page of results. Omit this parameter for the first request.

Example

./dlf-cli/bin/dlf user list \
--user_name 'starrocks_test' \
--user_type 'RAM_USER'

Output

2025-07-08 10:24:00 : {
  "nextPageToken" : null,
  "users" : [ {
    "createdAt" : 1744428101252,
    "createdBy" : "",
    "displayName" : "starrocks_test",
    "type" : "RAM_USER",
    "updatedAt" : 1744428101252,
    "updatedBy" : "",
    "userId" : "xxxxx",
    "userName" : "starrocks_test",
    "userPrincipal" : "acs:ram::104568******:user/starrocks_test"
  } ]
}

list_role

Lists the roles associated with a specified user.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:ListUserRoles

get

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf user list_role \
--user_principal <user_principal> \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--user_principal`	String	Yes	The user principal of the target user.
`--max_results`	Integer	No	The maximum number of results to return per page. If omitted, the system uses a default value.
`--page_token`	String	No	The pagination token from a previous response to retrieve the next page of results. Omit this parameter for the first request.

Example

./dlf-cli/bin/dlf user list_role \
--user_principal 'acs:ram::104568******:user/starrocks_test'

Output

2025-07-15 13:18:45 : {
  "nextPageToken" : null,
  "roles" : [{
    "createdAt" : 1749435901626,
    "createdBy" : "acs:ram::104568******:root",
    "description" : null,
    "displayName" : "enginer role",
    "isPredefined" : "false",
    "roleName" : "engineer",
    "rolePrincipal" : "acs:dlf::104568******:role/engineer",
    "updatedAt" : 1751960724469,
    "updatedBy" : "acs:ram::104568******:root",
    "users" : null
  }]
}

Permission commands

list - List permissions

Lists permissions for a specified resource type. You can filter results by criteria such as resource type (for example, catalog, database, or table) and other conditions. The command also supports pagination.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListPermissions

get

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf permission list \
--catalog <catalogName>  \
--resource_type <resource_type> \
[--database <database>] \
[--table <table>] \
[--principal <principal>] \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--catalog`	String	Yes	The name of the catalog that contains the permissions.
`--resource_type`	String	Yes	The resource type to filter by. Valid values are `catalog`, `database`, `table`, `function`, and `view`.
`--database`	String	No	The name of the database. This parameter is required only if the `resource_type` is `database` or one of its sub-resources.
`--table`	String	No	The name of the table. This parameter is required only if the `resource_type` is `table` or one of its sub-resources.
`--principal`	String	No	The principal (user or role) by which to filter permissions.
`--max_results`	Integer	No	The maximum number of results to return per page. Defaults to the system default.
`--page_token`	String	No	The pagination token for retrieving the next page of results. Omit this parameter for the first call. For subsequent calls, use the token from the previous response.

Example

./dlf-cli/bin/dlf permission list \
--catalog test_paimon \
--resource_type database \
--database default

Output

2025-07-08 10:51:31 : {
  "nextPageToken" : null,
  "permissions" : [ {
    "access" : "ALTER",
    "columns" : null,
    "database" : "default",
    "function" : null,
    "principal" : "acs:ram::104568******:user/bennett-test",
    "resourceType" : "DATABASE",
    "table" : null,
    "view" : null
  }, {
    "access" : "SELECT",
    "columns" : null,
    "database" : "default",
    "function" : null,
    "principal" : "acs:ram::104568******:user/bennett-test",
    "resourceType" : "DATABASE_ALL",
    "table" : null,
    "view" : null
  } ]
}

grant - Grant permissions

Grants permissions to a specified principal (user or role).

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:BatchGrantPermissions

create

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf permission grant \
--catalog <catalogName>  \
--permissions '<json_array>'

Parameters

Parameter

Type

Required

Description

--catalog

String

Yes

The name of the catalog that contains the permissions.

--permissions

JSON string

Yes

A JSON array of permission objects. Each object specifies a permission to grant and includes the access type (access), database name (database), principal (principal), and resource type (resourceType). For more information, see Permission.

{"access" : "SELECT", "database" : "default", "principal" : "acs:ram::104568******:user/starrocks_test", "resourceType" : "DATABASE"}

Example

./dlf-cli/bin/dlf permission grant \
--catalog test_paimon  \
--permissions '[{"access" : "SELECT", "database" : "default", "principal" : "acs:ram::104568******:user/starrocks_test", "resourceType" : "DATABASE"}]'

Output

2025-07-08 10:53:41 : success

revoke - Revoke permissions

Revokes resource permissions from a specified principal (user or role).

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:BatchRevokePermissions

delete

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf permission revoke \
--catalog <catalogName>  \
--permissions '<json_array>'

Parameters

Parameter	Type	Required	Description
`--catalog`	String	Yes	The name of the catalog that contains the permissions.
`--permissions`	JSON string	Yes	A JSON array of permission objects. Each object specifies a permission to revoke and includes details such as the principal, resource type, resource name, and access type.

Example

./dlf-cli/bin/dlf permission revoke \
--catalog test_paimon  \
--permissions '[{"access" : "SELECT", "database" : "default", "principal" : "acs:ram::104568******:user/starrocks_test", "resourceType" : "DATABASE"}]'

Output

2025-07-08 10:53:41 : success

Catalog commands

help - List supported catalog commands

./dlf-cli/bin/dlf catalog help

list - Lists catalogs

Lists all catalogs. Pagination is supported.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:ListCatalogs

get

*All resources

*

None

Usage

./dlf-cli/bin/dlf catalog list \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--max_results`	Integer	No	Maximum number of results to return per page. If omitted, the default value is used.
`--page_token`	String	No	The token for retrieving the next page of results. To retrieve the first page, do not specify this parameter. For subsequent requests, use the nextPageToken value from the previous response.

Example

./dlf-cli/bin/dlf catalog list

Response

2025-07-07 17:24:47 : {
  "catalogs" : [ {
    "createdAt" : 1748335426553,
    "createdBy" : "xxxx",
    "id" : "xxxxx",
    "name" : "xxxx",
    "options" : {
      "storage.data.redundancy.type" : "LRS",
      "comment" : "xxxx"
    },
    "owner" : "xxxx",
    "status" : "RUNNING",
    "type" : "PAIMON",
    "updatedAt" : 1748350097424,
    "updatedBy" : "xxxx"
  }, {
    "createdAt" : 1747885240095,
    "createdBy" : "xxxx",
    "id" : "xxxx",
    "name" : "xxxx",
    "options" : {
      "catalog.data.token.minExpireSeconds" : "43200",
      "storage.data.redundancy.type" : "LRS",
      "comment" : "xxxx",
      "catalog.data.token.isTable" : "true",
      "catalog.data.token.maxExpireSeconds" : "43200"
    },
    "owner" : "xxxx",
    "status" : "RUNNING",
    "type" : "PAIMON",
    "updatedAt" : 1751846858724,
    "updatedBy" : "acs:ram::104568******:root"
  } ],
  "nextPageToken" : null
}

get - Retrieve catalog details

Retrieves the details for the specified catalog.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:GetCatalog

get

*All resources

*

None

Usage

./dlf-cli/bin/dlf catalog get \
--catalog <catalog name>

Parameters

Parameter	Type	Required	Description
`--catalog`	String	Yes	The name of the catalog to retrieve.

Example

./dlf-cli/bin/dlf catalog get \
--catalog test_paimon

Response

2025-07-08 10:56:51 : {
  "createdAt" : 1747982344641,
  "createdBy" : "acs:ram::104568******:root",
  "id" : "clg-paimon-802dcc2xxxxx",
  "name" : "test_paimon",
  "options" : {
    "storage.data.redundancy.type" : "LRS",
    "comment" : ""
  },
  "owner" : "acs:ram::104568******:root",
  "status" : "RUNNING",
  "type" : "PAIMON",
  "updatedAt" : 1747982348385,
  "updatedBy" : "acs:ram::104568******:root"
}

create - Creates a catalog

Creates a new catalog with the specified name and options.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:CreateCatalog

create

*All resources

*

None

Usage

./dlf-cli/bin/dlf catalog create \
--catalog <catalog name> \
--options '{}'

Parameters

Parameter	Type	Required	Description
`--catalog`	String	Yes	The name of the catalog to create.
`--options`	JSON string	Yes	The configuration options for the catalog, provided as a JSON string. These options can include properties such as a comment.

Example

./dlf-cli/bin/dlf catalog create \
--catalog test-cli \
--options '{"comment": "test"}'

Response

2025-07-07 17:45:04 : success

alter - Updates a catalog

Updates the properties of a specified catalog.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:AlterCatalog

update

*All resources

*

None

Usage

./dlf-cli/bin/dlf catalog alter \
--catalog <catalog name> \
--removals '[]' \
--updates '{}'

Parameters

Parameter	Type	Required	Description
`--catalog`	String	Yes	The name of the catalog to update.
`--removals`	JSON string	No	A list of property names to remove, provided as a JSON array (e.g., `'["key1", "key2"]'`).
`--updates`	JSON string	No	The properties and their new values to add or update, provided as a JSON object (e.g., `'{"key1": "value1"}'`).

Example

./dlf-cli/bin/dlf catalog alter \
--catalog test-cli \
--removals '[]' \
--updates '{"comment": "new comment", "k1": "v1"}'

Response

2025-07-07 17:45:04 : success

drop - Deletes a catalog

The following conditions must be met. Otherwise, the drop operation fails:

All tables and user-created databases in the catalog are deleted.
At least 24 hours have passed since the tables and databases were deleted.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:DropCatalog

delete

*All resources

*

None

Usage

./dlf-cli/bin/dlf catalog drop \
--catalog <catalog name>

Parameters

Parameter	Type	Required	Description
`--catalog`	String	Yes	The name of the catalog to delete.

Example

./dlf-cli/bin/dlf catalog drop \
--catalog test-cli

Response

2025-07-07 17:45:04 : success

get_token - Get temporary access credential

Retrieves a temporary access credential for the specified catalog.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:GetCatalogToken

get

*All resources

*

None

Usage

./dlf-cli/bin/dlf catalog get_token \
--catalog <catalog name>

Parameters

Parameter	Type	Required	Description
`--catalog`	String	Yes	The name of the catalog to retrieve a token for.

Example

./dlf-cli/bin/dlf catalog get_token \
--catalog test_paimon

Response

2025-08-18 16:58:38 : {
  "expiresAtMillis" : 1755550718000,
  "token" : {
    "fs.oss.accessKeyId" : "STS.xxx",
    "fs.oss.accessKeySecret" : "xxx",
    "fs.oss.securityToken" : "xxx",
    "fs.oss.endpoint" : "xxx",
    "fs.oss.bucket.name" : "clg-paimon-xxx"
  }
}

Database commands

help - List database commands

./dlf-cli/bin/dlf database help

list - List databases

Lists the names of databases in a specified catalog. This command supports pagination.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListDatabases

List

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf database list \
--catalog [catalogName] \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--catalog`	string	Yes	The name of the catalog.
`--max_results`	integer	No	The maximum number of results to return per page. If unspecified, the system default is used.
`--page_token`	string	No	The pagination token. Omit this parameter for the first request. For subsequent requests, use the `nextPageToken` value from the previous response to retrieve the next page of results.

Example

./dlf-cli/bin/dlf database list \
--catalog test-cli

Output

2025-07-08 10:59:26 : {
  "elements" : [ "default", "system", "test_db" ],
  "nextPageToken" : null
}

get - Get database details

Gets the details of a specified database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:GetDatabase

Read

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf database get \
--full_name <catalogName.databaseName>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified database name, in the format `<catalogName>.<databaseName>`.

Example

./dlf-cli/bin/dlf database get \
--full_name test-cli.default

Output

2025-07-08 11:03:51 : {
  "id" : "db-9605ccda-cf07-4a74-a137-3c166590177e",
  "name" : "default",
  "location" : "oss://clg-paimon-b1af75fab07c4dfb9c0e2205a41740c6/db-9605ccda-cf07-4a74-a137-3c166590177e.db",
  "options" : { },
  "owner" : "acs:ram::1045689747920334:root",
  "createdAt" : 1751882013752,
  "createdBy" : "acs:ram::1045689747920334:root",
  "updatedAt" : 1751882013752,
  "updatedBy" : "acs:ram::1045689747920334:root"
}

create - Create a database

Creates a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:CreateDatabase

Write

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf database create \
--full_name <catalogName.databaseName> \
--options <options>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified database name for the new database, in the format `<catalogName>.<databaseName>`.
`--options`	JSON string	Yes	The database configuration properties, specified as a JSON string. These properties can include storage location and description.

Example

./dlf-cli/bin/dlf database create \
--full_name test-cli.test_db \
--options '{"k1":"v1","k2":"v2"}'

Output

2025-07-08 11:07:34 : success

alter - Update database properties

Updates the properties of a specified database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:AlterDatabase

Write

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf database alter \
--full_name <catalogName.databaseName> \
--removals <removals> \
--updates <updates>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified database name, in the format `<catalogName>.<databaseName>`.
`--removals`	JSON string	No	A JSON array of property keys to remove. For example: `'["key1", "key2"]'`.
`--updates`	JSON string	No	A JSON object of key-value pairs to add or update. For example: `'{"key1": "value1"}'`.

Example

./dlf-cli/bin/dlf database alter \
--full_name test-cli.test_db \
--removals '["k1"]' \
--updates '{"k2":"v3"}'

Output

2025-07-08 11:08:26 : success

drop - Drop a database

Drops a specified database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:DropDatabase

Write

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf database drop \
--full_name <catalogName.databaseName>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified name of the database to drop, in the format `<catalogName>.<databaseName>`.

Example

./dlf-cli/bin/dlf database drop \
--full_name test-cli.test_db

Output

2025-07-08 11:09:26 : success

Table commands

help - Lists table subcommands

./dlf-cli/bin/dlf table help

list - List tables

Lists the names of tables in a specified database. This operation supports pagination.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:ListTables

list

*All resources

*

None

Usage

./dlf-cli/bin/dlf table list \
--catalog <catalogName> \
--database <databaseName> \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--catalog`	string	Yes	The name of the catalog.
`--database`	string	Yes	The name of the database.
`--max_results`	integer	No	The maximum number of results to return per page. If this parameter is not specified, a default value is used.
`--page_token`	string	No	The token used to retrieve the next page of results. Leave this parameter empty for the first call. For subsequent calls, use the token from the previous response.

Example

./dlf-cli/bin/dlf table list \
--catalog test-cli \
--database test_db

Output

2025-07-08 11:27:39 : {
  "elements" : [ "test_table" ],
  "nextPageToken" : null
}

get - Get table

Gets the details of a specified table.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:GetTable

get

*All resources

*

None

Usage

./dlf-cli/bin/dlf table get \
--full_name <catalogName.databaseName.tableName>

Parameters

Parameter	Type	Required	Description
`--full_name`	String	Yes	The fully qualified table name in the format `<catalogName>.<databaseName>.<tableName>`.

Example

./dlf-cli/bin/dlf table get \
--full_name test-cli.test_db.test_table

Output:

2025-07-08 11:29:13 : {
  "id" : "tbl-d2a8e203-xxxxxx",
  "name" : "test_table",
  "path" : "oss://clg-paimon-b1af75xxxxxx/db-2788b0b9-xxxxxx.db/tbl-d2a8e203-xxxxxx",
  "isExternal" : false,
  "schemaId" : 0,
  "schema" : {
    "fields" : [ {
      "id" : 0,
      "name" : "f0",
      "type" : "INT NOT NULL"
    }, {
      "id" : 1,
      "name" : "f1",
      "type" : "INT NOT NULL"
    } ],
    "partitionKeys" : [ "f0" ],
    "primaryKeys" : [ "f0", "f1" ],
    "options" : {
      "bucket" : "-2",
      "path" : "oss://clg-paimon-b1af75xxxxxx/db-2788b0b9-xxxxxx.db/tbl-d2a8e203-xxxxxx",
      "manifest.merge-min-count" : "10",
      "manifest.delete-file-drop-stats" : "true",
      "data-file.thin-mode" : "true",
      "partition.legacy-name" : "false",
      "write-only" : "true",
      "metastore.partitioned-table" : "true"
    },
    "comment" : "comment"
  },
  "owner" : "acs:ram::104568******:root",
  "createdAt" : 1751944703679,
  "createdBy" : "acs:ram::104568******:root",
  "updatedAt" : 1751944703679,
  "updatedBy" : "acs:ram::104568******:root"
}

create - Create a table

Creates a new table.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:CreateTable

create

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf table create \
--full_name <catalogName.databaseName.tableName> \
--schema <schema>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified table name in the format `<catalogName>.<databaseName>.<tableName>`.
`--schema`	JSON string	Yes	The table's schema, specified as a JSON string. This includes properties such as fields, types, partition keys, and primary keys.

Example

./dlf-cli/bin/dlf table create \
--full_name test-cli.test_db.test_table \
--schema '{"fields" : [ {"id" : 0, "name" : "f0", "type" : "INT NOT NULL" }, {"id" : 1, "name" : "f1", "type" : "INT NOT NULL" } ], "partitionKeys" : [ "f0" ], "primaryKeys" : [ "f0", "f1" ], "options" : { }, "comment" : "comment" }'

Output

2025-07-08 11:18:23 : success

alter - Update table properties

Updates the properties of a specified table.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:AlterTable

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf table alter \
--full_name <catalogName.databaseName.tableName> \
--changes <changes>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified table name in the format `<catalogName>.<databaseName>.<tableName>`.
`--changes`	JSON string	Yes	A JSON array of change operations. Each operation specifies an `action` (such as `setOption` or `updateComment`) and its corresponding parameters.

Example

./dlf-cli/bin/dlf table alter \
--full_name test-cli.test_db.test_table \
--changes '[{"action":"setOption", "key" : "snapshot.time-retained", "value" : "2h" }, {"action":"updateComment","comment" : "hahaha" }]'

Output

2025-07-08 11:35:18 : success

drop - Drop a table

Drops the specified table.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:DropTable

delete

All resources

*

None

Synopsis

./dlf-cli/bin/dlf table drop \
--full_name <catalogName.databaseName.tableName>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified name of the table to drop, in the format `<catalogName>.<databaseName>.<tableName>`.

Example

./dlf-cli/bin/dlf table drop \
--full_name test-cli.test_db.test_table

Output

2025-07-08 11:35:18 : success

get_snapshot - Get table snapshot

Retrieves the latest snapshot for a specified table.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:GetTableSnapshot

get

All resources

*

None

Usage

./dlf-cli/bin/dlf table get_snapshot \
--full_name <catalogName.databaseName.tableName>

Parameters

Parameter	Type	Required	Description
`--full_name`	String	Yes	The fully qualified name of the table in the format `<catalogName>.<databaseName>.<tableName>`.

Example

./dlf-cli/bin/dlf table get_snapshot --full_name test_paimon.default.test_yt

Output

2025-07-08 11:42:32 : {
  "snapshot" : {
    "version" : 3,
    "id" : 14,
    "schemaId" : 0,
    "baseManifestList" : "manifest-list-e97f6ae4-xxxxxx",
    "baseManifestListSize" : 1041,
    "deltaManifestList" : "manifest-list-e97f6ae4-xxxxxx",
    "deltaManifestListSize" : 989,
    "changelogManifestList" : null,
    "commitUser" : "morax_d51dfc0b-xxxxxx",
    "commitIdentifier" : 5,
    "commitKind" : "COMPACT",
    "timeMillis" : 1749807238526,
    "logOffsets" : { },
    "totalRecordCount" : 3,
    "deltaRecordCount" : -5,
    "changelogRecordCount" : 0,
    "watermark" : -9223372036854775808
  },
  "recordCount" : 3,
  "fileSizeInBytes" : 799,
  "fileCount" : 1,
  "lastFileCreationTime" : 1749807176914
}

Rollback

Rolls back a specified table to a previous snapshot version.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:RollbackTable

*All resources

*

None

Usage

./dlf-cli/bin/dlf table rollback \
--full_name <catalogName.databaseName.tableName> \
--instant <instant>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified name of the table in the format `<catalogName>.<databaseName>.<tableName>`.
`--instant`	string	Yes	The target snapshot for the rollback, specified as a JSON string. For details about the JSON object, see Instant.

Example

./dlf-cli/bin/dlf table rollback \
--full_name test_paimon.default.test_yt \
--instant '{"type":"snapshot", "snapshotId": 13}'

Output

2025-07-08 11:46:56 : success

list_branches - List branch names

Lists the branch names for a specified table.

RAM access control

Actions

Access level

Resource type

Condition key

Associated actions

dlf:ListBranches

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf table list_branches \
--full_name <catalogName.databaseName.tableName>

Parameters

Parameter	Type	Required	Description
`--full_name`	String	Yes	The fully qualified table name in the format `<catalogName>.<databaseName>.<tableName>`.

Example

./dlf-cli/bin/dlf table list_branches \
--full_name test_paimon.default.test_yt

Output

2025-07-08 13:57:46 : [ "stream" ]

create_branch - Create a branch

Creates a new branch for a specified table.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:CreateBranch

create

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf table create_branch \
--full_name <catalogName.databaseName.tableName> \
--branch <branchName> \
[--from_tag <tagName>]

Parameters

Parameter	Type	Required	Description
`--full_name`	String	Yes	The fully qualified name of the table in the format `<catalogName>.<databaseName>.<tableName>`.
`--branch`	String	Yes	The name of the new branch.
`--from_tag`	String	No	Specifies the source tag for the new branch. If this parameter is omitted, the branch is created from the current main branch.

Example

./dlf-cli/bin/dlf table create_branch \
--full_name test_paimon.default.test_yt \
--branch stream

Output

2025-07-08 13:56:41 : success

forward_branch - Fast-forward a branch

Fast-forwards a branch for a specified table to its latest state.

RAM access control

Actions

Access level

Resource type

Condition key

Associated operation

dlf:ForwardBranch

create

All resources

*

None

Usage

./dlf-cli/bin/dlf table forward_branch \
--full_name <catalogName.databaseName.tableName> \
--branch <branchName>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The fully qualified name of the target table in the format `<catalogName>.<databaseName>.<tableName>`.
`--branch`	string	Yes	The name of the target branch to fast-forward.

Example

./dlf-cli/bin/dlf table forward_branch \
--full_name test_paimon.default.test_yt \
--branch stream

Output

2025-07-08 13:56:41 : success

drop_branch

Deletes a specified branch from a table.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:DropBranch

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf table drop_branch \
--full_name <catalogName.databaseName.tableName> \
--branch <branchName>

Parameters

Parameter	Type	Required	Description
`--full_name`	string	Yes	The table's fully qualified name, in the format `<catalogName>.<databaseName>.<tableName>`.
`--branch`	string	Yes	The branch to delete.

Example

./dlf-cli/bin/dlf table drop_branch \
--full_name test_paimon.default.test_yt \
--branch stream

Output

2025-07-08 14:02:19 : success

Partition command

List partitions

Lists partitions.

RAM access control

Actions

Access level

Resource type

Condition key

Associated actions

dlf:ListPartitions

list

*All resources

*

None

Synopsis

./dlf-cli/bin/dlf partition list \
--catalog <catalogName> \
--identifier <identifier> \
[--max_results <max_results>] \
[--page_token <page_token>]

Parameters

Parameter	Type	Required	Description
`--catalog`	string	Yes	The name of the target catalog.
`--identifier`	string	Yes	The unique identifier for the target table, formatted as `<databaseName>.<tableName>`.
`--max_results`	integer	No	The maximum number of results to return per page. If omitted, the system default is used.
`--page_token`	string	No	The token to retrieve the next page of results. Omit this parameter for the first request. For subsequent requests, use the nextPageToken value from the previous response.

Example

./dlf-cli/bin/dlf partition list \
--catalog 'baoma_poc' \
--identifier 'default.pk_ctas_tbl'

Result

2025-07-08 14:08:09 : {
  "elements" : [ {
    "spec" : {
      "p" : "1"
    },
    "recordCount" : 1,
    "fileSizeInBytes" : 684,
    "fileCount" : 1,
    "lastFileCreationTime" : 1748345335406,
    "done" : false
  } ],
  "nextPageToken" : null
}