API list

Updated at:

The metadata management APIs perform unified operations on metadata objects, including databases, tables, partitions, and views. Use these APIs to create, query, update, and delete metadata programmatically.

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.

ColumnDescription
OperationThe specific permission.
Access levelThe access level: Write, Read, or List.
Resource typeThe 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 keyThe condition keys defined by the cloud product.
Associated operationOther permissions required to call the operation successfully.
OperationAccess levelResource typeCondition keyAssociated operation
dlf:See the specific APISee the specific API\*All resourcesNoneNone

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 all database names from the data catalog.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListDatabasesList\*All resourcesNoneNone

Return values

NameTypeDescriptionExample
databasesarrayThe database names from the data catalog. The order of array elements is not guaranteed.\[test_db1, test_db2\]
databasestringThe database name.test_db1

Examples

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

ListDatabasesPaged - Get a paged list of databases

Retrieves a paged list of database names from the data catalog. Optionally filter by name pattern.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListDatabasesList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
maxResultsintegerNoThe number of entries per page. If not set, the server default applies. If set to a value greater than 0, the system uses the smaller of your value and the server default.10
pageTokenstringNoThe pagination token. Pass null for the first request. Use the nextPageToken value from the previous response for subsequent requests. An empty nextPageToken in the response means no more data is available.db_test
databaseNamePatternstringNoThe SQL LIKE pattern for filtering database names, with a wildcard (%) at the end. If not set or empty, all databases are returned.db_test%

Return values

NameTypeDescriptionExample
elementsarrayThe database names from the data catalog. The order of array elements is not guaranteed.\[test_db1, test_db2\]
databasestringThe database name.test_db1
nextPageTokenstringThe pagination token for the next page.test_db1

Examples

Retrieve all databases using pagination:

int maxResults = 10;
List<String> results = new ArrayList<>();
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 filtered paged list by name pattern:

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

CreateDatabase - Create a database

Creates a database in the data catalog. Returns HTTP 409 if the database already exists, or HTTP 403 if the caller lacks permission.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:CreateDatabaseWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
namestringNoThe database name.db_demo
propertiesmapNoThe configuration properties.

Return values

This operation has no return values.

Exceptions

TypeDescription
AlreadyExistsExceptionHTTP 409. The database already exists.
ForbiddenExceptionHTTP 403. The caller does not have 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 the details of a database from the data catalog.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:GetDatabaseRead\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
namestringYesThe database name.db_demo

Return values

NameTypeDescriptionExample
idstringThe database ID.6b168495-4a4f-48a5-be43-c258d6ce0715
namestringThe database name.db_demo
locationstringThe database location.
optionsmapThe configuration properties.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
ForbiddenExceptionHTTP 403. The caller does not have 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

OperationAccess levelResource typeCondition keyAssociated operation
dlf:DropDatabaseWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
namestringYesThe database name.db_demo

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to delete the database.

Examples

api.dropDatabase(name);

AlterDatabase - Alter a database

Updates the properties of a database in the data catalog.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:AlterDatabaseWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
namestringYesThe database name.db_demo
removalsarrayNoThe list of property keys to delete.k1
removalstring—A property key to delete.
updatesmapNoThe key-value pairs of properties to update.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
ForbiddenExceptionHTTP 403. The caller does not have 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 in the specified database. Returns HTTP 404 if the database does not exist, or HTTP 409 if the table already exists.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:CreateTableWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
schemaSchemaYesThe table schema.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
AlreadyExistsExceptionHTTP 409. The table already exists.
ForbiddenExceptionHTTP 403. The caller does not have 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 from the data lake.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:DropTableWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to delete the table.

Examples

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

RenameTable - Rename a table

Renames a table. Returns HTTP 404 if the source table does not exist, or HTTP 409 if the destination table already exists.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:RenameTableWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
fromIdentifierIdentifierYesThe source table identifier.
toIdentifierIdentifierYesThe destination table identifier.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The source table does not exist.
AlreadyExistsExceptionHTTP 409. The destination table already exists.
ForbiddenExceptionHTTP 403. The caller does not have permission to rename the 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

Applies schema changes to a table identified by its table identifier.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:AlterTableWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
changesarrayYesThe list of schema changes to apply.
schemaChangeSchemaChangeYesA schema change.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to alter the 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

OperationAccess levelResource typeCondition keyAssociated operation
dlf:GetTableRead\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.

Return values

NameTypeDescriptionExample
getTableResponseGetTableResponseThe table details.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to get the 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 specified database in the data lake.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListTablesList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
databaseNamestringYesThe database name.test_db

Return values

NameTypeDescriptionExample
tablesarrayThe list of table names.\[test_table1, test_table2\]
tablestringThe table name.test_table

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to view the 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 table names from the specified database. Optionally filter by name pattern.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListTablesList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
databaseNamestringYesThe database name.test_db
maxResultsstringNoThe number of entries per page. The effective value is the smaller of the specified value and the server default.10
pageTokenstringNoThe pagination token. Pass null for the first request. Use the nextPageToken value from the previous response for subsequent requests. An empty nextPageToken means no more data is available.2cb472ec1bf84f8d92f9c4baa0d21c19aa
tableNamePatternstringNoThe SQL-style wildcard pattern (%) for filtering table names. If not set, all tables are returned.test_table%

Return values

NameTypeDescriptionExample
pagedTablesarrayThe list of table names.
tablestringThe table name.test_table
nextPageTokenstringThe pagination token for the next page.2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to view the database.

Examples

Retrieve all tables using pagination:

String databaseName = "db_test";
int maxResults = 10;
List<String> results = new ArrayList<>();
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 filtered paged list by 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 specified database. Optionally filter by name pattern.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListTableDetailsList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
databaseNamestringYesThe database name.test_db
maxResultsstringNoThe number of entries per page. The effective value is the smaller of the specified value and the server default.10
pageTokenstringNoThe pagination token. Pass null for the first request. Use the nextPageToken value from the previous response for subsequent requests. An empty nextPageToken means no more data is available.2cb472ec1bf84f8d92f9c4baa0d21c19aa
tableNamePatternstringNoThe SQL-style wildcard pattern (%) for filtering table names. If not set, all tables are returned.test_table%

Return values

NameTypeDescriptionExample
pagedTableDetailsarrayThe list of table details.
tableDetail—The table details.
nextPageTokenstringThe pagination token for the next page.2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to view the database.

Examples

Retrieve the details of all tables using pagination:

String databaseName = "test_db";
int maxResults = 10;
List<GetTableResponse> results = new ArrayList<>();
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 filtered paged list of table details by 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 of a table in the data lake.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:GetTableSnapshotRead\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.

Return values

NameTypeDescriptionExample
TableSnapshotTableSnapshotThe latest snapshot information for the table.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table or its latest snapshot does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to get the 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 at a specific version.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:GetVersionSnapshotRead\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
versionstringYesThe version to retrieve. Valid values: Latest, EARLIEST, or a specific snapshot ID."Latest"

Return values

NameTypeDescriptionExample
SnapshotSnapshotThe snapshot information for the specified version.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table or the specified snapshot does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to get the 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 snapshots for a table in the data lake.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListSnapshotsList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
maxResultsstringNoThe number of entries per page. The effective value is the smaller of the specified value and the server default.10
pageTokenstringNoThe pagination token. Pass null for the first request. Use the nextPageToken value from the previous response for subsequent requests. An empty nextPageToken means no more data is available.1

Return values

NameTypeDescriptionExample
elementsarrayThe list of table snapshots.
snapshotSnapshotThe snapshot information.
nextPageTokenstringThe pagination token for the next page.2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to view the table.

Examples

Identifier identifier = Identifier.create("test_db", "test_table");
int maxResults = 10;
List<Snapshot> results = new ArrayList<>();
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 - Roll back a table

Rolls back a table to a previous snapshot or tag.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:RollbackTableWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
instantInstantYesThe rollback target (snapshot or tag).

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table, the target snapshot, or the tag does not exist.
ForbiddenExceptionHTTP 403. The caller does not have 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. Optionally based on an existing tag.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:CreateBranchWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
branchstringYesThe branch name.test_branch
fromTagstringNoThe tag to base the branch on.test_tag

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table or the specified tag does not exist.
AlreadyExistsExceptionHTTP 409. The branch already exists.
ForbiddenExceptionHTTP 403. The caller does not have permission to create the branch.

Examples

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

DropBranch - Delete a table branch

Deletes a table branch by name.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:DropBranchWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
branchstringYesThe branch name.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The branch does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to delete the branch.

Examples

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

ForwardBranch - Fast-forward a table branch

Fast-forwards a table branch.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ForwardBranchWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
branchstringYesThe branch name.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The branch does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to fast-forward the branch.

Examples

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

ListBranches - List table branches

Retrieves the branches of a table.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListBranchesList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.

Return values

NameTypeDescriptionExample
branchesarrayThe list of branch names.\[test_branch1, test_branch2\]
branchstringThe branch name.test_branch

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to view the table.

Examples

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

Partition APIs

ListPartitions - Get a list of partitions

Retrieves all partitions of a table.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListPartitionsList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.

Return values

NameTypeDescriptionExample
partitionsarrayThe list of partition details.
partitionstringThe partition details.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to access the table.

Examples

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 for a table. Optionally filter by partition name pattern.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListPartitionsList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
maxResultsstringNoThe number of entries per page. The effective value is the smaller of the specified value and the server default.10
pageTokenstringNoThe pagination token. Pass null for the first request. Use the nextPageToken value from the previous response for subsequent requests. An empty nextPageToken means no more data is available.2cb472ec1bf84f8d92f9c4baa0d21c19aa
partitionNamePatternstringNoThe SQL-style wildcard pattern (%) for right-hand matching of partition names. If not set, all partitions are returned.year=2025%

Return values

NameTypeDescriptionExample
pagedPartitionsarrayThe list of partition details.
partitionPartitionThe partition details.
nextPageTokenstringThe pagination token for the next page.2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to access the table.

Examples

Retrieve all partition details using pagination:

Identifier identifier = Identifier.create("test_db", "new_table");
int maxResults = 10;
List<String> results = new ArrayList<>();
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 filtered paged list by partition name pattern:

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

MarkDonePartitions - Mark partitions as complete

Marks a list of partitions as complete.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:MarkDonePartitionsWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe table identifier.
partitionsarrayYesThe list of partitions to mark as complete.
partitionmapYesA partition to mark as complete, specified as key-value pairs.{"year":"2025", "month": "05"}

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The table does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to access the table.

Examples

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 the view names from a database.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListViewsList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
databaseNamestringYesThe database name.db_demo

Return values

NameTypeDescriptionExample
viewsarrayThe list of view names.
viewstringThe view name.view_demo

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The database does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to access the database.

Examples

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

ListViewsPaged - Perform a paged query for a list of views

Retrieves a paged list of view names from a database. Optionally filter by name pattern.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListViewsList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
databaseNamestringYesThe database name.db_demo
maxResultsintegerNoThe number of entries per page. If not set, the server default applies. If set to a value greater than 0, the system uses the smaller of your value and the server default.10
pageTokenstringNoThe pagination token. Pass null for the first request. Use the nextPageToken value from the previous response for subsequent requests. An empty nextPageToken means no more data is available.view_test
viewNamePatternstringNoThe SQL LIKE pattern for right-hand fuzzy matching (%) of view names. If not set or empty, all views are returned.view_tes%

Return values

NameTypeDescriptionExample
elementsarrayThe list of view names.\[view_demo\]
viewstringThe view name.view_demo
nextPageTokenstringThe pagination token for the next page.2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The view does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to access the view.

Examples

Retrieve all views using pagination:

String databaseName = "db_test";
int maxResults = 10;
List<String> results = new ArrayList<>();
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 filtered paged list by view name pattern:

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. Optionally filter by name pattern.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:ListViewDetailsList\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
databaseNamestringYesThe database name.db_demo
maxResultsintegerNoThe number of entries per page. If not set, the server default applies. If set to a value greater than 0, the system uses the smaller of your value and the server default.10
pageTokenstringNoThe pagination token. Pass null for the first request. Use the nextPageToken value from the previous response for subsequent requests. An empty nextPageToken means no more data is available.view_test
viewNamePatternstringNoThe SQL LIKE pattern for right-hand fuzzy matching (%) of view names. If not set or empty, all views are returned.view_tes%

Return values

NameTypeDescriptionExample
elementsarrayThe list of view details.\[view_demo\]
viewDetailGetViewResponseThe view details.
nextPageTokenstringThe pagination token for the next page.2cb472ec1bf84f8d92f9c4baa0d21c19aa

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The view does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to get the view details.

Examples

Retrieve the details of all views using pagination:

String databaseName = "db_test";
int maxResults = 10;
List<GetViewResponse> results = new ArrayList<>();
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 filtered paged list of view details by name pattern:

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

OperationAccess levelResource typeCondition keyAssociated operation
dlf:CreateViewWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe view identifier.
schemaViewSchemaYesThe view schema.

Exceptions

TypeDescription
AlreadyExistsExceptionHTTP 409. The view already exists.
ForbiddenExceptionHTTP 403. The caller does not have 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

OperationAccess levelResource typeCondition keyAssociated operation
dlf:GetViewRead\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe view identifier.

Return values

NameTypeDescriptionExample
idstringThe view ID.
namestringThe view name.
schemaViewSchemaThe view schema.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The view does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to get the view.

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

OperationAccess levelResource typeCondition keyAssociated operation
dlf:DropViewWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
identifierIdentifierYesThe view identifier.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The view does not exist.
ForbiddenExceptionHTTP 403. The caller does not have permission to delete the view.

Examples

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

RenameView - Rename a view

Renames a view in a database. Returns HTTP 404 if the source view does not exist, or HTTP 409 if the destination view already exists.

RAM access control

OperationAccess levelResource typeCondition keyAssociated operation
dlf:RenameViewWrite\*All resourcesNoneNone

Request parameters

NameTypeRequiredDescriptionExample
fromViewIdentifierYesThe source view identifier.
toViewIdentifierYesThe destination view identifier.

Return values

This operation has no return values.

Exceptions

TypeDescription
NoSuchResourceExceptionHTTP 404. The source view does not exist.
AlreadyExistsExceptionHTTP 409. The destination view already exists.
ForbiddenExceptionHTTP 403. The caller does not have permission to rename the view.

Examples

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