@Public public class RESTApi extends Object
This API class only includes interaction with REST Server and does not have file read and write operations, which makes this API lightweight enough to avoid introducing dependencies such as Hadoop and file systems.
The following example show how to use the RESTApi:
Options options = new Options();
options.set(URI, "<rest server url>");
options.set(WAREHOUSE, "my_instance_name");
options.set(TOKEN_PROVIDER, "dlf");
options.set(DLF_ACCESS_KEY_ID, "<access-key-id>");
options.set(DLF_ACCESS_KEY_SECRET, "<access-key-secret>");
RESTApi api = new RESTApi(options);
List<String> tables = api.listTables("my_database");
System.out.println(tables);
This class also provide util methods for serializing json toJson(T)
and deserializing
json fromJson(java.lang.String, java.lang.Class<T>)
.
Modifier and Type | Field and Description |
---|---|
static String |
DATABASE_NAME_PATTERN |
static String |
HEADER_PREFIX |
static String |
MAX_RESULTS |
static org.apache.paimon.shade.jackson2.com.fasterxml.jackson.databind.ObjectMapper |
OBJECT_MAPPER |
static String |
PAGE_TOKEN |
static String |
PARTITION_NAME_PATTERN |
static String |
TABLE_NAME_PATTERN |
static long |
TOKEN_EXPIRATION_SAFE_TIME_MILLIS |
static String |
VIEW_NAME_PATTERN |
Constructor and Description |
---|
RESTApi(Options options)
Initializes a newly created
RESTApi object. |
RESTApi(Options options,
boolean configRequired)
Initializes a newly created
RESTApi object. |
Modifier and Type | Method and Description |
---|---|
void |
alterDatabase(String name,
List<String> removals,
Map<String,String> updates)
Alter a database.
|
void |
alterFunction(Identifier identifier,
List<FunctionChange> changes)
Alter a function.
|
void |
alterTable(Identifier identifier,
List<SchemaChange> changes)
Alter table.
|
void |
alterView(Identifier identifier,
List<ViewChange> viewChanges)
Alter view.
|
List<String> |
authTableQuery(Identifier identifier,
List<String> select)
Auth table query.
|
boolean |
commitSnapshot(Identifier identifier,
Snapshot snapshot,
List<PartitionStatistics> statistics)
Commit snapshot for table.
|
void |
createBranch(Identifier identifier,
String branch,
String fromTag)
Create branch for table.
|
void |
createDatabase(String name,
Map<String,String> properties)
Create a database.
|
void |
createFunction(Identifier identifier,
Function function)
Create a function.
|
void |
createTable(Identifier identifier,
Schema schema)
Create table.
|
void |
createView(Identifier identifier,
ViewSchema schema)
Create view.
|
void |
dropBranch(Identifier identifier,
String branch)
Drop branch for table.
|
void |
dropDatabase(String name)
Drop a database.
|
void |
dropFunction(Identifier identifier)
Drop a function.
|
void |
dropTable(Identifier identifier)
Drop table.
|
void |
dropView(Identifier identifier)
Drop view.
|
void |
fastForward(Identifier identifier,
String branch)
Forward branch for table.
|
static <T> T |
fromJson(String json,
Class<T> clazz)
Util method to deserialize object from json.
|
GetDatabaseResponse |
getDatabase(String name)
Get a database.
|
GetFunctionResponse |
getFunction(Identifier identifier)
Get a function by identifier.
|
GetTableResponse |
getTable(Identifier identifier)
Get table.
|
GetViewResponse |
getView(Identifier identifier)
Get view.
|
List<String> |
listBranches(Identifier identifier)
List branches for table.
|
List<String> |
listDatabases()
List databases.
|
PagedList<String> |
listDatabasesPaged(Integer maxResults,
String pageToken,
String databaseNamePattern)
List databases.
|
List<String> |
listFunctions(String databaseName)
List functions for database.
|
List<Partition> |
listPartitions(Identifier identifier)
List partitions for table.
|
PagedList<Partition> |
listPartitionsPaged(Identifier identifier,
Integer maxResults,
String pageToken,
String partitionNamePattern)
List partitions for a table.
|
PagedList<GetTableResponse> |
listTableDetailsPaged(String databaseName,
Integer maxResults,
String pageToken,
String tableNamePattern)
List table details for a database.
|
List<String> |
listTables(String databaseName)
List tables for a database.
|
PagedList<String> |
listTablesPaged(String databaseName,
Integer maxResults,
String pageToken,
String tableNamePattern)
List tables for a database.
|
PagedList<String> |
listTablesPagedGlobally(String databaseNamePattern,
String tableNamePattern,
Integer maxResults,
String pageToken)
List table for a catalog.
|
PagedList<GetViewResponse> |
listViewDetailsPaged(String databaseName,
Integer maxResults,
String pageToken,
String viewNamePattern)
List view details.
|
List<String> |
listViews(String databaseName)
List views for a database.
|
PagedList<String> |
listViewsPaged(String databaseName,
Integer maxResults,
String pageToken,
String viewNamePattern)
List views.
|
PagedList<String> |
listViewsPagedGlobally(String databaseNamePattern,
String viewNamePattern,
Integer maxResults,
String pageToken)
List views for a catalog.
|
TableSnapshot |
loadSnapshot(Identifier identifier)
Load latest snapshot for table.
|
GetTableTokenResponse |
loadTableToken(Identifier identifier)
Load token for File System of this table.
|
void |
markDonePartitions(Identifier identifier,
List<Map<String,String>> partitions)
Mark done partitions for table.
|
Options |
options()
Get the configured options which has been merged from REST Server.
|
void |
renameTable(Identifier fromTable,
Identifier toTable)
Rename table.
|
void |
renameView(Identifier fromView,
Identifier toView)
Rename view.
|
void |
rollbackTo(Identifier identifier,
Instant instant)
Rollback instant for table.
|
static <T> String |
toJson(T t)
Util method to serialize object to json.
|
public static final String HEADER_PREFIX
public static final String MAX_RESULTS
public static final String PAGE_TOKEN
public static final String DATABASE_NAME_PATTERN
public static final String TABLE_NAME_PATTERN
public static final String VIEW_NAME_PATTERN
public static final String PARTITION_NAME_PATTERN
public static final long TOKEN_EXPIRATION_SAFE_TIME_MILLIS
public static final org.apache.paimon.shade.jackson2.com.fasterxml.jackson.databind.ObjectMapper OBJECT_MAPPER
public RESTApi(Options options)
RESTApi
object.
By default, configRequired
is true, this means that there will be one REST request
to merge configurations during initialization.
options
- contains authentication and catalog information for REST Serverpublic RESTApi(Options options, boolean configRequired)
RESTApi
object.
If the options
are already obtained through options()
, you can configure
configRequired to be false.
options
- contains authentication and catalog information for REST ServerconfigRequired
- is there one REST request to merge configurations during initializationpublic Options options()
public List<String> listDatabases()
Gets an array of databases for a catalog. There is no guarantee of a specific ordering of the elements in the array.
public PagedList<String> listDatabasesPaged(@Nullable Integer maxResults, @Nullable String pageToken, @Nullable String databaseNamePattern)
Gets an array of databases for a catalog. There is no guarantee of a specific ordering of the elements in the array.
maxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.PagedList
: elements and nextPageToken.public void createDatabase(String name, Map<String,String> properties)
name
- name of this databaseAlreadyExistsException
- Exception thrown on HTTP 409 means a database already existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic GetDatabaseResponse getDatabase(String name)
name
- name of this databaseGetDatabaseResponse
NoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic void dropDatabase(String name)
name
- name of this databaseNoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic void alterDatabase(String name, List<String> removals, Map<String,String> updates)
name
- name of this databaseremovals
- options to be removedupdates
- options to be updated or addedNoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic List<String> listTables(String databaseName)
databaseName
- name of this databaseNoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic PagedList<String> listTablesPaged(String databaseName, @Nullable Integer maxResults, @Nullable String pageToken, @Nullable String tableNamePattern)
Gets an array of tables for a database. There is no guarantee of a specific ordering of the elements in the array.
databaseName
- name of database.maxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.tableNamePattern
- A sql LIKE pattern (%) for table names. All tables will be returned
if not set or empty. Currently, only prefix matching is supported.PagedList
: elements and nextPageToken.NoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic PagedList<GetTableResponse> listTableDetailsPaged(String databaseName, @Nullable Integer maxResults, @Nullable String pageToken, @Nullable String tableNamePattern)
Gets an array of table details for a database. There is no guarantee of a specific ordering of the elements in the array.
databaseName
- name of database.maxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.tableNamePattern
- A sql LIKE pattern (%) for table names. All tables will be returned
if not set or empty. Currently, only prefix matching is supported.PagedList
: elements and nextPageToken.NoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic PagedList<String> listTablesPagedGlobally(@Nullable String databaseNamePattern, @Nullable String tableNamePattern, @Nullable Integer maxResults, @Nullable String pageToken)
Gets an array of table for a catalog. There is no guarantee of a specific ordering of the elements in the array.
databaseNamePattern
- A sql LIKE pattern (%) for database names. All databases will be
returned if not set or empty. Currently, only prefix matching is supported.tableNamePattern
- A sql LIKE pattern (%) for table names. All tables will be returned
if not set or empty. Currently, only prefix matching is supported.maxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.PagedList
: elements and nextPageToken.ForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic GetTableResponse getTable(Identifier identifier)
identifier
- database name and table name.GetTableResponse
NoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic TableSnapshot loadSnapshot(Identifier identifier)
identifier
- database name and table name.TableSnapshot
Optional snapshot.NoSuchResourceException
- Exception thrown on HTTP 404 means the table or the latest
snapshot not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic boolean commitSnapshot(Identifier identifier, Snapshot snapshot, List<PartitionStatistics> statistics)
identifier
- database name and table name.snapshot
- snapshot for committingstatistics
- statistics for this snapshot incrementalNoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic void rollbackTo(Identifier identifier, Instant instant)
identifier
- database name and table name.instant
- instant to rollbackNoSuchResourceException
- Exception thrown on HTTP 404 means the table or the snapshot
or the tag not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic void createTable(Identifier identifier, Schema schema)
identifier
- database name and table name.schema
- schema to create tableNoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsAlreadyExistsException
- Exception thrown on HTTP 409 means a table already existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
creating tablepublic void renameTable(Identifier fromTable, Identifier toTable)
fromTable
- from tabletoTable
- to tableNoSuchResourceException
- Exception thrown on HTTP 404 means the fromTable not existsAlreadyExistsException
- Exception thrown on HTTP 409 means the toTable already existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
renaming tablepublic void alterTable(Identifier identifier, List<SchemaChange> changes)
identifier
- database name and table name.changes
- changes to alter tableNoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic List<String> authTableQuery(Identifier identifier, @Nullable List<String> select)
identifier
- database name and table name.select
- select columns, null if select allNoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic void dropTable(Identifier identifier)
identifier
- database name and table name.NoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic void markDonePartitions(Identifier identifier, List<Map<String,String>> partitions)
identifier
- database name and table name.partitions
- partitions to be marked doneNoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic List<Partition> listPartitions(Identifier identifier)
identifier
- database name and table name.NoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic PagedList<Partition> listPartitionsPaged(Identifier identifier, @Nullable Integer maxResults, @Nullable String pageToken, @Nullable String partitionNamePattern)
Gets an array of partitions for a table. There is no guarantee of a specific ordering of the elements in the array.
identifier
- database name and table name.maxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.partitionNamePattern
- A sql LIKE pattern (%) for partition names. All partitions will
be returned if not set or empty. Currently, only prefix matching is supported.PagedList
: elements and nextPageToken.NoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic void createBranch(Identifier identifier, String branch, @Nullable String fromTag)
identifier
- database name and table name.branch
- branch namefromTag
- optional from tagNoSuchResourceException
- Exception thrown on HTTP 404 means the table or fromTag not
existsAlreadyExistsException
- Exception thrown on HTTP 409 means the branch already existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic void dropBranch(Identifier identifier, String branch)
identifier
- database name and table name.branch
- branch nameNoSuchResourceException
- Exception thrown on HTTP 404 means the branch not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic void fastForward(Identifier identifier, String branch)
identifier
- database name and table name.branch
- branch nameNoSuchResourceException
- Exception thrown on HTTP 404 means the branch or table not
existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic List<String> listBranches(Identifier identifier)
identifier
- database name and table name.NoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic List<String> listFunctions(String databaseName)
databaseName
- database namepublic GetFunctionResponse getFunction(Identifier identifier)
identifier
- the identifier of the function to retrieveNoSuchResourceException
- if the function does not existForbiddenException
- if the user lacks permission to access the functionpublic void createFunction(Identifier identifier, Function function)
identifier
- database name and function name.function
- the function to be createdAlreadyExistsException
- Exception thrown on HTTP 409 means a function already existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
creating functionpublic void dropFunction(Identifier identifier)
identifier
- database name and function name.NoSuchResourceException
- Exception thrown on HTTP 404 means the function not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this functionpublic void alterFunction(Identifier identifier, List<FunctionChange> changes)
identifier
- database name and function name.changes
- list of function changes to applyNoSuchResourceException
- if the function does not existForbiddenException
- if the user lacks permission to modify the functionpublic GetViewResponse getView(Identifier identifier)
identifier
- database name and view name.GetViewResponse
NoSuchResourceException
- Exception thrown on HTTP 404 means the view not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this viewpublic void dropView(Identifier identifier)
identifier
- database name and view name.NoSuchResourceException
- Exception thrown on HTTP 404 means the view not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this viewpublic void createView(Identifier identifier, ViewSchema schema)
identifier
- database name and view name.schema
- schema of the viewAlreadyExistsException
- Exception thrown on HTTP 409 means the view already existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this viewpublic List<String> listViews(String databaseName)
databaseName
- name of this databaseNoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic PagedList<String> listViewsPaged(String databaseName, @Nullable Integer maxResults, @Nullable String pageToken, @Nullable String viewNamePattern)
Gets an array of views for a database. There is no guarantee of a specific ordering of the elements in the array.
databaseName
- database namemaxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.viewNamePattern
- A sql LIKE pattern (%) for view names. All views will be returned if
not set or empty. Currently, only prefix matching is supported.PagedList
: elements and nextPageToken.NoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic PagedList<GetViewResponse> listViewDetailsPaged(String databaseName, @Nullable Integer maxResults, @Nullable String pageToken, @Nullable String viewNamePattern)
Gets an array of view details for a database. There is no guarantee of a specific ordering of the elements in the array.
databaseName
- database namemaxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.viewNamePattern
- A sql LIKE pattern (%) for view names. All views will be returned if
not set or empty. Currently, only prefix matching is supported.PagedList
: elements and nextPageToken.NoSuchResourceException
- Exception thrown on HTTP 404 means the database not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic PagedList<String> listViewsPagedGlobally(@Nullable String databaseNamePattern, @Nullable String viewNamePattern, @Nullable Integer maxResults, @Nullable String pageToken)
Gets an array of views for a catalog. There is no guarantee of a specific ordering of the elements in the array.
databaseNamePattern
- A sql LIKE pattern (%) for database names. All databases will be
returned if not set or empty. Currently, only prefix matching is supported.viewNamePattern
- A sql LIKE pattern (%) for view names. All views will be returned if
not set or empty. Currently, only prefix matching is supported.maxResults
- Optional parameter indicating the maximum number of results to include in
the result. If maxResults is not specified or set to 0, will return the default number of
max results.pageToken
- Optional parameter indicating the next page token allows list to be start
from a specific point.PagedList
: elements and nextPageToken.ForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this databasepublic void renameView(Identifier fromView, Identifier toView)
fromView
- from viewtoView
- to viewNoSuchResourceException
- Exception thrown on HTTP 404 means fromView not existsAlreadyExistsException
- Exception thrown on HTTP 409 means toView already existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
viewspublic void alterView(Identifier identifier, List<ViewChange> viewChanges)
identifier
- database name and view name.viewChanges
- view changesNoSuchResourceException
- Exception thrown on HTTP 404 means the view not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this viewpublic GetTableTokenResponse loadTableToken(Identifier identifier)
identifier
- database name and view name.GetTableTokenResponse
NoSuchResourceException
- Exception thrown on HTTP 404 means the table not existsForbiddenException
- Exception thrown on HTTP 403 means don't have the permission for
this tablepublic static <T> T fromJson(String json, Class<T> clazz) throws org.apache.paimon.shade.jackson2.com.fasterxml.jackson.core.JsonProcessingException
org.apache.paimon.shade.jackson2.com.fasterxml.jackson.core.JsonProcessingException
public static <T> String toJson(T t) throws org.apache.paimon.shade.jackson2.com.fasterxml.jackson.core.JsonProcessingException
org.apache.paimon.shade.jackson2.com.fasterxml.jackson.core.JsonProcessingException
Copyright © 2023–2025 The Apache Software Foundation. All rights reserved.