API list
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
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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListDatabases | List | \*All resources | None | None |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| databases | array | The 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 database names from the data catalog. Optionally filter by name pattern.
RAM access control
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListDatabases | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| maxResults | integer | No | The 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 |
| pageToken | string | No | The 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 |
| databaseNamePattern | string | No | The 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
| Name | Type | Description | Example |
|---|---|---|---|
| elements | array | The 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 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:CreateDatabase | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| name | string | No | The database name. | db_demo |
| properties | map | No | The configuration properties. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| AlreadyExistsException | HTTP 409. The database already exists. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:GetDatabase | Read | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| name | string | Yes | The database name. | db_demo |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| id | string | The database ID. | 6b168495-4a4f-48a5-be43-c258d6ce0715 |
| name | string | The database name. | db_demo |
| location | string | The database location. | |
| options | map | The configuration properties. |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:DropDatabase | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| name | string | Yes | The database name. | db_demo |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:AlterDatabase | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| name | string | Yes | The database name. | db_demo |
| removals | array | No | The list of property keys to delete. | k1 |
| removal | string | — | A property key to delete. | |
| updates | map | No | The key-value pairs of properties to update. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:CreateTable | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| schema | Schema | Yes | The table schema. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| AlreadyExistsException | HTTP 409. The table already exists. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:DropTable | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:RenameTable | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| fromIdentifier | Identifier | Yes | The source table identifier. | |
| toIdentifier | Identifier | Yes | The destination table identifier. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The source table does not exist. |
| AlreadyExistsException | HTTP 409. The destination table already exists. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:AlterTable | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| changes | array | Yes | The list of schema changes to apply. | |
| schemaChange | SchemaChange | Yes | A schema change. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:GetTable | Read | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| getTableResponse | GetTableResponse | The table details. |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListTables | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| databaseName | string | Yes | The database name. | test_db |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| tables | array | The list of table names. | \[test_table1, test_table2\] |
| table | string | The table name. | test_table |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListTables | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| databaseName | string | Yes | The database name. | test_db |
| maxResults | string | No | The number of entries per page. The effective value is the smaller of the specified value and the server default. | 10 |
| pageToken | string | No | The 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 |
| tableNamePattern | string | No | The SQL-style wildcard pattern (%) for filtering table names. If not set, all tables are returned. | test_table% |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| pagedTables | array | The list of table names. | |
| table | string | The table name. | test_table |
| nextPageToken | string | The pagination token for the next page. | 2cb472ec1bf84f8d92f9c4baa0d21c19aa |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListTableDetails | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| databaseName | string | Yes | The database name. | test_db |
| maxResults | string | No | The number of entries per page. The effective value is the smaller of the specified value and the server default. | 10 |
| pageToken | string | No | The 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 |
| tableNamePattern | string | No | The SQL-style wildcard pattern (%) for filtering table names. If not set, all tables are returned. | test_table% |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| pagedTableDetails | array | The list of table details. | |
| tableDetail | — | The table details. | |
| nextPageToken | string | The pagination token for the next page. | 2cb472ec1bf84f8d92f9c4baa0d21c19aa |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:GetTableSnapshot | Read | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| TableSnapshot | TableSnapshot | The latest snapshot information for the table. |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table or its latest snapshot does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:GetVersionSnapshot | Read | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| version | string | Yes | The version to retrieve. Valid values: Latest, EARLIEST, or a specific snapshot ID. | "Latest" |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| Snapshot | Snapshot | The snapshot information for the specified version. |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table or the specified snapshot does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListSnapshots | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| maxResults | string | No | The number of entries per page. The effective value is the smaller of the specified value and the server default. | 10 |
| pageToken | string | No | The 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
| Name | Type | Description | Example |
|---|---|---|---|
| elements | array | The list of table snapshots. | |
| snapshot | Snapshot | The snapshot information. | |
| nextPageToken | string | The pagination token for the next page. | 2cb472ec1bf84f8d92f9c4baa0d21c19aa |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:RollbackTable | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| instant | Instant | Yes | The rollback target (snapshot or tag). |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table, the target snapshot, or the tag does not exist. |
| ForbiddenException | HTTP 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
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| branch | string | Yes | The branch name. | test_branch |
| fromTag | string | No | The tag to base the branch on. | test_tag |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table or the specified tag does not exist. |
| AlreadyExistsException | HTTP 409. The branch already exists. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:DropBranch | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| branch | string | Yes | The branch name. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The branch does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ForwardBranch | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| branch | string | Yes | The branch name. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The branch does not exist. |
| ForbiddenException | HTTP 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
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| branches | array | The list of branch names. | \[test_branch1, test_branch2\] |
| branch | string | The branch name. | test_branch |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| partitions | array | The list of partition details. | |
| partition | string | The partition details. |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| maxResults | string | No | The number of entries per page. The effective value is the smaller of the specified value and the server default. | 10 |
| pageToken | string | No | The 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 |
| partitionNamePattern | string | No | The SQL-style wildcard pattern (%) for right-hand matching of partition names. If not set, all partitions are returned. | year=2025% |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| pagedPartitions | array | The list of partition details. | |
| partition | Partition | The partition details. | |
| nextPageToken | string | The pagination token for the next page. | 2cb472ec1bf84f8d92f9c4baa0d21c19aa |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The table identifier. | |
| partitions | array | Yes | The list of partitions to mark as complete. | |
| partition | map | Yes | A partition to mark as complete, specified as key-value pairs. | {"year":"2025", "month": "05"} |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The table does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListViews | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| databaseName | string | Yes | The database name. | db_demo |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| views | array | The list of view names. | |
| view | string | The view name. | view_demo |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The database does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListViews | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| databaseName | string | Yes | The database name. | db_demo |
| maxResults | integer | No | The 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 |
| pageToken | string | No | The 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 |
| viewNamePattern | string | No | The SQL LIKE pattern for right-hand fuzzy matching (%) of view names. If not set or empty, all views are returned. | view_tes% |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| elements | array | The list of view names. | \[view_demo\] |
| view | string | The view name. | view_demo |
| nextPageToken | string | The pagination token for the next page. | 2cb472ec1bf84f8d92f9c4baa0d21c19aa |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The view does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:ListViewDetails | List | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| databaseName | string | Yes | The database name. | db_demo |
| maxResults | integer | No | The 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 |
| pageToken | string | No | The 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 |
| viewNamePattern | string | No | The SQL LIKE pattern for right-hand fuzzy matching (%) of view names. If not set or empty, all views are returned. | view_tes% |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| elements | array | The list of view details. | \[view_demo\] |
| viewDetail | GetViewResponse | The view details. | |
| nextPageToken | string | The pagination token for the next page. | 2cb472ec1bf84f8d92f9c4baa0d21c19aa |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The view does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:CreateView | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The view identifier. | |
| schema | ViewSchema | Yes | The view schema. |
Exceptions
| Type | Description |
|---|---|
| AlreadyExistsException | HTTP 409. The view already exists. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:GetView | Read | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The view identifier. |
Return values
| Name | Type | Description | Example |
|---|---|---|---|
| id | string | The view ID. | |
| name | string | The view name. | |
| schema | ViewSchema | The view schema. |
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The view does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:DropView | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| identifier | Identifier | Yes | The view identifier. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The view does not exist. |
| ForbiddenException | HTTP 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
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| dlf:RenameView | Write | \*All resources | None | None |
Request parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| fromView | Identifier | Yes | The source view identifier. | |
| toView | Identifier | Yes | The destination view identifier. |
Return values
This operation has no return values.
Exceptions
| Type | Description |
|---|---|
| NoSuchResourceException | HTTP 404. The source view does not exist. |
| AlreadyExistsException | HTTP 409. The destination view already exists. |
| ForbiddenException | HTTP 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);