API list - Data Lake Formation - Alibaba Cloud Documentation Center

The metadata management APIs allow you to perform unified operations on metadata objects, such as databases, tables, partitions, and views. You can use these APIs to efficiently create, query, update, and delete metadata to meet your data management needs.

Authorization information

RAM access control

The following table lists the authorization information for the APIs. You can use this information in the Action element of a Resource Access Management (RAM) policy statement to grant a RAM user or RAM role the permission to call these APIs.

Operation: The specific permission.
Access level: The access level for each operation. Valid values are Write, Read, or List.
Resource type: The resource type that supports authorization for the operation.
- 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 successfully execute the operation. The caller must also have permissions for any associated operations.

Operation

Access level

Resource type

Condition key

Associated operation

dlf:See the specific API

See the specific API

*All resources

*

None

Note

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

ACL permission management

For more information, see Authorization management.

Database APIs

ListDatabases - Get a list of databases

Retrieves a list of databases from the data catalog.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListDatabases

List

*All resources

*

None

Return values

Name	Type	Description	Example value
databases	array	An array of database names from the data catalog. The order of array elements is not guaranteed.	[test_db1, test_db2]
database	string	The database name.	test_db1

Examples

List<String> databases = restApi.listDatabases();

ListDatabasesPaged - Get a paged list of databases

Retrieves a paged list of databases from the data catalog. You can filter the databases by name.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListDatabases

List

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
maxResults	integer	No	The number of entries to return on each page. If this parameter is not set, the server's default value is used. If you set this parameter to a value greater than 0, the system uses the smaller value between your setting and the server's default.	10
pageToken	string	No	The starting position for the paged query. For the first query, enter null. For subsequent queries, enter the NextPageToken value from the previous response. If the returned NextPageToken is an empty string, no more data is available.	db_test
databaseNamePattern	string	No	The SQL LIKE pattern for the database name, with a wildcard (%) at the end. If this parameter is not set or is empty, all databases are returned.	db_test%

Return values

Name	Type	Description	Example value
-	object	The returned data.
elements	array	An array of database names from the data catalog. The order of array elements is not guaranteed.	[test_db1, test_db2]
database	string	The database name.	test_db1
nextPageToken	string	The starting position for the next paged query.	test_db1

Examples

Retrieve a list of all databases

int maxResults = 10;
List<String> results = new ArrayList<>();
Map<String, String> queryParams = Maps.newHashMap();
String pageToken = null;
do {
  PagedResponse<String> response = restApi.listDatabasesPaged(10, pageToken, null);
  pageToken = response.getNextPageToken();
  if (response.data() != null) {
    results.addAll(response.data());
  }
  if (pageToken == null || response.data() == null || response.data().isEmpty()) {
    break;
  }
} while (StringUtils.isNotEmpty(pageToken));

Retrieve a paged list of databases that match a name pattern

PagedList<String> pagedDatabases = restApi.listDatabasesPaged(10, null, "test_db%");

CreateDatabase - Create a database

Creates a new metadatabase in the data catalog.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:CreateDatabase

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
name	string	No	The name.	db_demo
properties	map	No	The configuration parameter struct.

Return values

Name	Type	Description	Example value
This API has no return parameters.

Exceptions

Type	Description
AlreadyExistsException	The REST request returns 409, which indicates that the database already exists.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to create the database.

Examples

Map<String, String> properties = new HashMap();
properties.put("k1", "v1");
api.createDatabase("db_demo", properties);

GetDatabase - Get a database

Retrieves a metadatabase from the data catalog.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:GetDatabase

Get

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
name	string	Yes	The name.	db_demo

Return values

Name	Type	Description	Example value
-	object	The returned data.
id	string	The database ID.	6b168495-4a4f-48a5-be43-c258d6ce0715
name	string	The database name.	db_demo
location	string	The location of the database.
options	map	The configuration parameter struct.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the database.

Examples

 GetDatabaseResponse response = api.getDatabase(name);

DropDatabase - Delete a database

Deletes a database from the data catalog.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:DropDatabase

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
name	string	Yes	The name.	db_demo

Return values

Name	Type	Description	Example value
This API has no return parameters.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to delete the database.

Examples

api.dropDatabase(name);

AlterDatabase - Alter a database

Updates the information for a database in the data catalog.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:AlterDatabase

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
name	string	Yes	The name.	db_demo
removals	array	No	A list of configurations to delete.	k1
removal	string		The configuration to delete.
updates	map	No	The key-value pairs of the configurations to update.

Return values

Name	Type	Description	Example value
This API has no return parameters.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to alter the database.

Examples

List<String> removals = new ArrayList<>();
removals.add(“k1”)
Map<String, String> updates = new HashMap<>();
updates.put("k2", "v2")
api.alterDatabase(name, removals, updates);

Table APIs

CreateTable - Create a table

Creates a table.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:CreateTable

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table identifier.
schema	Schema	Yes	The table schema.

Return values

Name	Type	Description	Example value
This API has no return values.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
AlreadyExistsException	The REST request returns 409, which indicates that the table already exists.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to create the table.

Examples

Identifier identifier = Identifier.create("test_db", "test_table");
Schema schema =
            new Schema(
                    Lists.newArrayList(
                            new DataField(0, "pk", DataTypes.INT()),
                            new DataField(1, "col1", DataTypes.STRING()),
                            new DataField(2, "col2", DataTypes.STRING())),
                    Collections.emptyList(),
                    Collections.emptyList(),
                    Maps.newHashMap(),
                    "");
restApi.createTable(identifier, schema);

DropTable - Delete a table

Deletes a table.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:DropTable

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table identifier.

Return values

Name	Type	Description	Example value
This API has no return values.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the table does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to delete the current table.

Examples

Identifier identifier = Identifier.create("test_db", "new_table");
restApi.dropTable(identifier);

RenameTable - Rename a table

Renames a table.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:RenameTable

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
fromIdentifier	Identifier	Yes	The original table identifier.
toIdentifier	Identifier	Yes	The destination table identifier.

Return values

Name	Type	Description	Example value
This API has no return values.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the original table does not exist.
AlreadyExistsException	The REST request returns 409, which indicates that the destination table already exists.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to modify the current table.

Examples

Identifier fromIdentifier = Identifier.create("test_db", "old_table");
Identifier toIdentifier = Identifier.create("test_db", "new_table");
restApi.renameTable(fromIdentifier, toIdentifier);

AlterTable - Alter a table

Alters a table based on its identifier.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:AlterTable

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table descriptor.
changes	array	Yes	A list of table change information.
schemaChange	SchemaChange	Yes	The table change information.

Return values

Name	Type	Description	Example value
This API has no return values.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the table does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to modify the current table.

Examples

ArrayList<SchemaChange> schemaChanges = Lists.newArrayList(
                SchemaChange.addColumn("col2", DataTypes.DATE()),
                SchemaChange.addColumn("col3", DataTypes.STRING(), "col3 field"));
restApi.alterTable(
                identifier,
                schemaChanges);

GetTable - Get table details

Retrieves the details of a table in the data lake.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:GetTable

Get

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table identifier.

Return values

Name	Type	Description	Example value
getTableResponse	GetTableResponse	The table details.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the table does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the current table.

Examples

Identifier identifier = Identifier.create("test_db", "test_table");
GetTableResponse response = restApi.getTable(identifier);

ListTables - Query for a list of tables

Retrieves a list of table names from the data lake.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListTables

List

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
databaseName	string	Yes	The database name.	test_db

Return values

Name	Type	Description	Example value
tables	array	A list of table names.	[test_table1, test_table2]
table	string	The table name.	test_table

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to view the current database.

Examples

String databaseName = "test_db";
List<String> tables = restApi.listTables(databaseName);

ListTablesPaged - Get a paged list of table names

Retrieves a paged list of tables from the data lake. You can filter the tables by name.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListTables

List

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
databaseName	string	Yes	The database name.	test_db
maxResults	string	No	The page size. The effective value is the smaller value between the input value and the server's default value.	10
pageToken	string	No	The pagination token, which is returned from the result. If this is your first query, pass null. If the returned NextPageToken is an empty string, no more data is available.	2cb472ec1bf84f8d92f9c4baa0d21c19aa
tableNamePattern	string	No	The SQL-style wildcard pattern (%) for the table name. If you do not set this parameter, all tables are returned.	test_table%

Return values

Name	Type	Description	Example value
-	object	The returned data.
pagedTables	array	A list of table names.
table	string	The table name.	test_table
nextPageToken	string	The pagination token.	2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to view the current database.

Examples

Retrieve a list of all tables

String databaseName = "db_test";
int maxResults = 10;
List<String> results = new ArrayList<>();
Map<String, String> queryParams = Maps.newHashMap();
String pageToken = null;
do {
  PagedResponse<String> response = restApi.listTablesPaged(databaseName, 10, pageToken, null);
  pageToken = response.getNextPageToken();
  if (response.data() != null) {
    results.addAll(response.data());
  }
  if (pageToken == null || response.data() == null || response.data().isEmpty()) {
    break;
  }
} while (StringUtils.isNotEmpty(pageToken));

Retrieve a paged list of tables that match a name pattern

String databaseName = "test_db";
PagedList<String> pagedTables = restApi.listTablesPaged(databaseName, 10, pageToken, "test_table%");

ListTableDetailsPaged - Get a paged list of table details

Retrieves a paged list of table details from the data lake. You can filter the tables by name.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListTableDetails

List

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
databaseName	string	Yes	The database name.	test_db
maxResults	string	No	The page size. The effective value is the smaller value between the input value and the server's default value.	10
pageToken	string	No	The pagination token, which is returned from the result. If this is your first query, pass null. If the returned NextPageToken is an empty string, no more data is available.	2cb472ec1bf84f8d92f9c4baa0d21c19aa
tableNamePattern	string	No	The SQL-style wildcard pattern (%) for the table name. If you do not set this parameter, all tables are returned.	test_table%

Return values

Name	Type	Description	Example value
-	object	The returned data.
pagedTableDetails	array	A list of table details.
tableDetail		The table details.
nextPageToken	string	The pagination token.	2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to view the current database.

Examples

Retrieve the details of all tables

String databaseName = "test_db";
int maxResults = 10;
List<GetTableResponse> results = new ArrayList<>();
Map<String, String> queryParams = Maps.newHashMap();
String pageToken = null;
do {
  PagedResponse<String> response = restApi.listTablesPaged(databaseName, 10, pageToken, null);
  pageToken = response.getNextPageToken();
  if (response.data() != null) {
    results.addAll(response.data());
  }
  if (pageToken == null || response.data() == null || response.data().isEmpty()) {
    break;
  }
} while (StringUtils.isNotEmpty(pageToken));

Retrieve a paged list of tables that match a name pattern

String databaseName = "test_db";
PagedList<GetTableResponse> pagedTableDetails = restApi.listTablesPaged(databaseName, 10, pageToken, "test_table%");

GetTableSnapshot - Get the latest snapshot of a table

Retrieves the latest snapshot information for a table in the data lake.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:GetTableSnapshot

Get

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table identifier.

Return values

Name	Type	Description	Example value
TableSnapshot	TableSnapshot	The table snapshot information.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the table or the latest snapshot does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the current table.

Examples

Identifier identifier = Identifier.create("test_db", "test_table");
restApi.loadSnapshot(identifier)

GetVersionSnapshot - Get a snapshot of a specific version

Retrieves a snapshot of a table based on its version information.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:GetVersionSnapshot

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table identifier.
version	String	Yes	The version information.	"Latest", "EARLIEST", "1"

Return values

Name	Type	Description	Example value
Snapshot	Snapshot	The table snapshot information.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the table or the latest snapshot does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the current table.

Examples

Identifier identifier = Identifier.create("test_db", "test_table");
String version = "Latest";
restApi.loadSnapshot(identifier, version);

ListSnapshotsPaged - Get a paged list of snapshots

Retrieves a paged list of snapshot information for a table in the data lake.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListSnapshots

List

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table identifier.
maxResults	string	No	The page size. The effective value is the smaller value between the input value and the server's default value.	10
pageToken	string	No	The pagination token, which is returned from the result. If this is your first query, pass null. If the returned NextPageToken is an empty string, no more data is available.	1

Return values

Name	Type	Description	Example value
elements	array	The list of table snapshots.
snapshot	Snapshot	The table snapshot information.
nextPageToken	string	The token for the next page of results.	2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

Type	Description
NoSuchResourceException	The REST request returns a 404 error. This indicates that the table does not exist.
ForbiddenException	The REST request returns a 403 error. This indicates that the current user does not have permission to view the table.

Example

Identifier identifier = Identifier.create("test_db", "test_table");
int maxResults = 10;
List<Snapshot> results = new ArrayList<>();
Map<String, String> queryParams = Maps.newHashMap();
String pageToken = null;
do {
  PagedResponse<Snapshot> response = restApi.listSnapshotsPaged(identifier, maxResults, pageToken);
  pageToken = response.getNextPageToken();
  if (response.data() != null) {
    results.addAll(response.data());
  }
  if (pageToken == null || response.data() == null || response.data().isEmpty()) {
    break;
  }
} while (StringUtils.isNotEmpty(pageToken));

RollbackTable

Rolls back a table in a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:RollbackTable

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table descriptor.
instant	Instant	Yes	The information about the rollback instance.

Return values

Name	Type	Description	Example value
This API does not return a value.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns a 404 error, which indicates that the table, the snapshot for the rollback, or the tag does not exist.
ForbiddenException	The REST request returns a 403 error, which indicates that the current user does not have the permission to roll back the table.

Examples

Identifier identifier = Identifier.create("test_db", "test_table");
Instant instant = Instant.snapshot(snapshotId)
restApi.rollbackTo(identifier, instant);

CreateBranch - Create a table branch

Creates a branch for a table in a database.

Resource Access Management

Operation

Access level

Resource type

Condition key

Associated operation

dlf:CreateBranch

create

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table descriptor.
branch	string	Yes	The branch.	test_branch
fromTag	string	No	The tag.	test_tag

Return values

Name	Type	Description	Example value
This API does not have a return value.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404. This indicates that the data table or tag does not exist.
AlreadyExistsException	The REST request returns 409. This indicates that the branch already exists.
ForbiddenException	The REST request returns 403. This indicates that the current user does not have the permission to create the branch.

Example

Identifier identifier = Identifier.create("test_db", "new_table");
restCatalog.createBranch(tableIdentifier, "test_branch", "tag_test");

DropBranch - Delete a table branch

Deletes a table branch in a database by name.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:DropBranch

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table descriptor.
branch	string	Yes	The branch name.

Return value

Name	Type	Description	Example value
This API has no return value.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns a 404 error. This indicates that the branch does not exist.
ForbiddenException	The REST request returns a 403 error. This indicates that the current user does not have the permission to delete the branch.

Example

Identifier identifier = Identifier.create("test_db", "test_table");
restApi.dropBranch(identifier, "branch_test");

ForwardBranch - Forward table branch

Forwarding table branch.

RAM access control

Operation

Access level

Resource type

Condition key

Related operations

dlf:ForwardBranch

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	Table descriptor.
branch	string	Yes	The branch name.

Return values

Name	Type	Description	Example value
This API does not return a value.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns a 404 error. This means the branch does not exist.
ForbiddenException	The REST request returns a 403 error. This means the current user does not have permission to delete the current branch.

Example

Identifier identifier = Identifier.create("test_db", "test_table");
restApi.fastForward(identifier, "branch_test");

ListBranches

Retrieves the branches of a table in a database.

Resource Access Management

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListBranches

list

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example value
identifier	Identifier	Yes	The table descriptor.

Return values

Name	Type	Description	Example value
branches	array	A list of branch names.	[test_branch1, test_branch2]
branch	string	The table name.	test_branch

Exceptions

Type	Description
NoSuchResourceException	The REST request returns a 404 error if the data table does not exist.
ForbiddenException	The REST request returns a 403 error if the current user does not have the permission to view the table.

Example

Identifier identifier = Identifier.create("test_db", "test_table");
List<String> branches = restApi.listBranches(identifier);

Partition APIs

ListPartitions - Get a list of partitions

Retrieves a list of partitions.

Resource Access Management

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListPartitions

list

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
identifier	Identifier	Yes	The table descriptor.

Return values

Name	Type	Description	Example
partitions	array	A list of partition details.
partition	string	The partition details.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the data table does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have permissions on the table.

Example

Identifier identifier = Identifier.create("test_db", "new_table");
List<Partition> tables = restApi.listPartitions(identifier);

ListPartitionsPaged - Get a paginated list of partitions

Retrieves a paged list of partitions. You can filter the partitions by name.

Resource Access Management

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListPartitions

list

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
identifier	Identifier	Yes	The table identifier.
maxResults	string	No	The number of entries to return on each page. The effective value is the minimum of the specified value and the server's default value.	10
pageToken	string	No	The pagination token from a previous response. Leave this empty for the first request. An empty NextPageToken in the response indicates that there is no more data.	2cb472ec1bf84f8d92f9c4baa0d21c19aa
partitionNamePattern	string	No	An SQL-style pattern for right-hand wildcard matching of partition names. If you do not specify this parameter, all partitions are returned.	year=2025%

Return values

Name	Type	Description	Example
-	object	The returned data.
pagedPartitions	array	A list of partition details.
partition	Partition	The partition details.
nextPageToken	string	The pagination token.	2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the data table does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have permissions on the table.

Examples

Retrieve a list of all partition details

Identifier identifier = Identifier.create("test_db", "new_table");
int maxResults = 10;
List<String> results = new ArrayList<>();
Map<String, String> queryParams = Maps.newHashMap();
String pageToken = null;
do {
  PagedResponse<Partition> response = restApi.listPartitionsPaged(identifier, 10, pageToken, null);
  pageToken = response.getNextPageToken();
  if (response.data() != null) {
    results.addAll(response.data());
  }
  if (pageToken == null || response.data() == null || response.data().isEmpty()) {
    break;
  }
} while (StringUtils.isNotEmpty(pageToken));

Retrieve a paged list of partition details by matching partition names

Identifier identifier = Identifier.create("test_db", "new_table");
PagedList<Partition> pagedPartitions = restApi.listPartitionsPaged(identifier, 10, pageToken, "year=2025%");

MarkDonePartitions - Mark partitions as complete

Marks partitions as complete.

Resource Access Management

Operation

Access level

Resource type

Condition key

Associated operation

dlf:MarkDonePartitions

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
identifier	Identifier	Yes	The table descriptor.
partitions	array	Yes	A list of partitions to mark as complete.
partition	Map	Yes	A partition to mark as complete.	{"year":"1025", "month": "05"}

Return values

Name	Type	Description	Example
This API does not have a return value.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the data table does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have permissions on the table.

Example

Identifier identifier = Identifier.create("test_db", "new_table");
List<Map<String, String>> partitions = new ArrayList<>();
LinkedHashMap<String, String> partition = new LinkedHashMap<>();
partition.put("year", "2025");
partition.put("month", "05");
restApi.markDonePartitions(identifier, partitions);

View APIs

ListViews - Query a list of views

Retrieves a list of views from a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListViews

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
databaseName	string	Yes	The database name.	db_demo

Return values

Name	Type	Description	Example
views	array	A list of view names.
view	string	The view name.	view_demo

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the view does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the view.

Examples

 List<String> viewNames = api.listViews(name);

ListViewsPaged - Perform a paged query for a list of views

Retrieves a paged list of views from a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListViews

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
databaseName	string	Yes	The database name.	db_demo
maxResults	integer	No	The number of entries to return on each page. If this parameter is not set, the server's default configuration value is used. If you set this parameter to a value greater than 0, the system uses the smaller value between your setting and the server's default.	10
pageToken	string	No	The starting position for the paged query. For the first query, enter null. For subsequent queries, enter the NextPageToken value from the previous response. If the returned NextPageToken is an empty string, no more data is available.	view_test
viewNamePattern	string	No	The view name pattern for a SQL LIKE right-sided fuzzy match (%). If this parameter is not set or is empty, all views are returned.	view_tes%

Return values

Name	Type	Description	Example
-	object	The returned data.
elements	array	A list of view names.	[view_demo]
view	string	The view name.	view_demo
nextPageToken	string	The token for the next page.	2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the view does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the view.

Examples

Retrieve a list of all tables

String databaseName = "db_test";
int maxResults = 10;
List<String> results = new ArrayList<>();
Map<String, String> queryParams = Maps.newHashMap();
String pageToken = null;
do {
  PagedResponse<String> response = restApi.listViewsPaged(databaseName, 10, pageToken, null);
  pageToken = response.getNextPageToken();
  if (response.data() != null) {
    results.addAll(response.data());
  }
  if (pageToken == null || response.data() == null || response.data().isEmpty()) {
    break;
  }
} while (StringUtils.isNotEmpty(pageToken));

Retrieve a paged list of views that match a view name

String databaseName = "test_db";
PagedList<String> pagedViews = restApi.listViewsPaged(databaseName, 10, null, "test_v%");

ListViewDetailsPaged - Perform a paged query for a list of view details

Retrieves a paged list of view details from a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:ListViewDetails

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
databaseName	string	Yes	The database name.	db_demo
maxResults	integer	No	The number of entries to return on each page. If this parameter is not set, the server's default configuration value is used. If you set this parameter to a value greater than 0, the system uses the smaller value between your setting and the server's default.	10
pageToken	string	No	The starting position for the paged query. For the first query, enter null. For subsequent queries, enter the NextPageToken value from the previous response. If the returned NextPageToken is an empty string, no more data is available.	view_test
viewNamePattern	string	No	The view name pattern for a SQL LIKE right-sided fuzzy match (%). If this parameter is not set or is empty, all views are returned.	view_tes%

Return values

Name	Type	Description	Example
-	PagedList	The returned data.
elements	array	A list of view details.	[view_demo]
viewDetail	GetViewResponse	The view details.
nextPageToken	string	The token for the next page.	2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the view does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the view details.

Examples

Retrieve a list of all views

String databaseName = "db_test";
int maxResults = 10;
List<GetViewResponse> results = new ArrayList<>();
Map<String, String> queryParams = Maps.newHashMap();
String pageToken = null;
do {
  PagedResponse<GetViewResponse> response = restApi.listViewDetailsPaged(databaseName, 10, pageToken, null);
  pageToken = response.getNextPageToken();
  if (response.data() != null) {
    results.addAll(response.data());
  }
  if (pageToken == null || response.data() == null || response.data().isEmpty()) {
    break;
  }
} while (StringUtils.isNotEmpty(pageToken));

Retrieve a paged list of views that match a view name

String databaseName = "test_db";
PagedList<GetViewResponse> pagedViewDetails = restApi.listViewDetailsPaged(databaseName, 10, null, "test_v%");

CreateView - Create a view

Creates a view in a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:CreateView

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
identifier	Identifier	Yes	The view descriptor.
schema	ViewSchema	Yes	The view structure.

Exceptions

Type	Description
AlreadyExistsException	The REST request returns 409, which indicates that the view already exists.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to create the view.

Examples

Identifier identifier = new Identifier(databaseName, "my_view");
RowType rowType = RowType.builder().field("str",DataTypes.STRING()).build();
String query = "SELECT * FROM OTHER_TABLE";
Map<String, String> option = new HashMap<>();
Map<String, String> dialects = new HashMap<>();
dialects.put("spark", "SELECT * FROM SPARK_TABLE");
ViewSchema schema =
        new ViewSchema(
                rowType.getFields(),
                query,
                dialects,
                "comment",
                option));
api.createView(identifier, schema);

GetView - Get a view

Retrieves the details of a view in a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:GetView

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
identifier	Identifier	Yes	The view descriptor.

Return values

Name	Type	Description	Example
id	string	The view ID.
name	string	The view name.
schema	ViewSchema	The view structure.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the database.

Examples

Identifier identifier = new Identifier(databaseName, "my_view");
GetViewResponse response = api.getView(identifier);

DropView - Delete a view

Deletes a view from a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:DropView

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
identifier	Identifier	Yes	The view descriptor.

Return values

Name	Type	Description	Example
This API does not have return parameters.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the database does not exist.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to get the database.

Examples

Identifier identifier = new Identifier(databaseName, "my_view");
api.dropView(identifier);

RenameView - Rename a view

Renames a view in a database.

RAM access control

Operation

Access level

Resource type

Condition key

Associated operation

dlf:RenameView

*All resources

*

None

Request parameters

Name	Type	Required	Description	Example
fromView	Identifier	Yes	The original view descriptor.
toView	Identifier	Yes	The new view descriptor.

Return values

Name	Type	Description	Example
This API does not have return parameters.

Exceptions

Type	Description
NoSuchResourceException	The REST request returns 404, which indicates that the view does not exist.
AlreadyExistsException	The REST request returns 409, which indicates that the view already exists.
ForbiddenException	The REST request returns 403, which indicates that the current user does not have the permission to rename the view.

Examples

Identifier fromView = new Identifier(databaseName, "from_view");
Identifier toView = new Identifier(databaseName, "to_view");
api.renameView(fromView, toView);