SDK Methods
Creating a Session
- Function
A session represents a connection. You can execute SQL requests through a session and query the request results through this session. This method allows you to synchronously create a session using the provided workspace ID and endpoint ID and configure the LakeFormation instance information and catalog name associated with the session.
- Method definition
createSession(String workspaceId, CreateSessionRequest request) createSession(String workspaceId, CreateSessionRequest request, int timeout) createSession(String workspaceId, CreateSessionRequest request, Map<String, String> headers) createSession(String workspaceId, CreateSessionRequest request, Map<String, String> headers, int timeout)
- Parameter descriptions:
Table 1 createSession parameter descriptions Parameter
Type
Mandatory
Description
workspaceId
String
Yes
ID of the workspace created in DataArts Fabric
request
CreateSessionRequest
Yes
Session request
timeout
int
No
Request timeout duration (The default value is -1, indicating no timeout is set.)
headers
Map<String,String>
No
HTTP request header
Table 2 CreateSessionRequest Parameter
Type
Mandatory
Description
endpointId
str
Yes
Execution endpoint ID
lakeFormationConfig
LakeFormationConfig
Yes
LakeFormation instance ID
Table 3 LakeFormationConfig Parameter
Type
Mandatory
Description
instanceId
String
Yes
LakeFormation instance ID
catalog
String
Yes
LakeFormation catalog name
- Response
Table 4 Response parameters Parameter
Type
Description
sessionId
String
Session ID
- Sample code
// Initialize the DwsRestClient instance and pass necessary parameters. // Parameter descriptions: // - First parameter: base URL (endpoint) of the API // - Second parameter: AK // - Third parameter: SK // - Fourth parameter: security token (optional, if using STS temporary credentials) DwsRestClient client = new DwsRestClient( "https://<your_endpoint_here>", "<your_access_key_here>", "<your_secret_key_here>", "<your_security_token_here>"); workspaceId = "<your_workspace_id_here>"; // Create a CreateSessionRequest object to request a session. CreateSessionRequest request = new CreateSessionRequest(); request.setEndpointId("<your_endpoint_id_here>"); // Create a LakeFormationConfig object and set relevant configurations. LakeFormationConfig lakeFormationConfig = new LakeFormationConfig(); lakeFormationConfig.setCatalog("<your_catalog_here>"); lakeFormationConfig.setInstanceId("<your_instance_id_here>"); request.setLakeFormationConfig(lakeFormationConfig); // Call the client.createSession method to create a session and obtain the session ID. String sessionId = client.createSession(workspaceId, request);
Closing a Session
- Function
This method allows you to close a specific session using the provided workspace ID and session ID.
- Method definition
closeSession(String workspaceId, String sessionId) closeSession(String workspaceId, String sessionId, int timeout) closeSession(String workspaceId, String sessionId, Map<String, String> headers) closeSession(String workspaceId, String sessionId, Map<String, String> headers, int timeout)
- Parameter descriptions:
Table 5 closeSession parameter descriptions Parameter
Type
Mandatory
Description
workspaceId
String
Yes
ID of the workspace created in DataArts Fabric
sessionId
String
Yes
ID of the session to be closed
timeout
int
No
Request timeout duration (The default value is -1, indicating no timeout is set.)
headers
Map<String,String>
No
HTTP request header
- Response
- Sample code
// Initialize the DwsRestClient instance and pass necessary parameters. // Parameter descriptions: // - First parameter: base URL (endpoint) of the API // - Second parameter: AK // - Third parameter: SK // - Fourth parameter: security token (optional, if using STS temporary credentials) DwsRestClient client = new DwsRestClient( "https://<your_endpoint_here>", "<your_access_key_here>", "<your_secret_key_here>", "<your_security_token_here>"); workspaceId = "<your_workspace_id_here>"; // Create a CreateSessionRequest object to request a session. CreateSessionRequest request = new CreateSessionRequest(); request.setEndpointId("<your_endpoint_id_here>"); // Create a LakeFormationConfig object and set relevant configurations. LakeFormationConfig lakeFormationConfig = new LakeFormationConfig(); lakeFormationConfig.setCatalog("<your_catalog_here>"); lakeFormationConfig.setInstanceId("<your_instance_id_here>"); request.setLakeFormationConfig(lakeFormationConfig); // Call the client.createSession method to create a session and obtain the session ID. String sessionId = client.createSession(workspaceId, request); client.closeSession(workspaceId, sessionId);
Executing SQL Synchronously
- Function
Through a session, a SQL request is issued synchronously, and the query results are returned immediately. You need to provide the workspace ID and session ID and construct the request body.
- Method definition
syncQuery(String workspaceId, StatementQuery query) syncQuery(String workspaceId, StatementQuery query, int timeout) syncQuery(String workspaceId, StatementQuery query, Map<String, String> headers) syncQuery(String workspaceId, StatementQuery query, Map<String, String> headers, int timeout)
- Parameter descriptions:
Table 6 syncQuery parameter descriptions Parameter
Type
Mandatory
Description
workspaceId
String
Yes
ID of the workspace created in DataArts Fabric
query
StatementQuery
Yes
SQL request class
timeout
int
No
Request timeout duration
headers
Map<String,String>
No
HTTP request header
Table 7 StatementQuery Parameter
Type
Mandatory
Description
statement
String
Yes
Content of the SQL to be issued
sessionId
String
Yes
Session ID
limit
int
No
SQL limit
bindings
List<List<String>>
No
Parameter bindings
- Response body: StatementResponse
Table 8 StatementResponse Parameter
Type
Description
status
int
Overall SQL execution status
sessionId
String
Session ID
statementId
String
Statement ID
results
List<StatementResult>
List of statement execution results
Table 9 StatementResult Parameter
Type
Description
status
String
Execution status of this SQL statement
statementId
String
Statement ID
numRows
int
Total number of rows in the statement
rowCount
int
Total number of rows on this page
pageCount
int
Total number of pages
pageNo
int
Current page number, starting from 1
errCode
int
Error code
message
String
Error message
resultSet
StatementResultSet
Result set
Table 10 StatementResultSet Parameter
Type
Description
columns
list[RowType]
Column header data
rows
List<List<String>>
Column data
If the request fails or the query inherently contains no result set, both columns and rows in result_set will be null.
Table 11 RowType Parameter
Type
Description
name
String
Name of the column header
tableId
String
Table ID
columnId
String
Column ID
format
int
Format
type
int
Type
size
int
Size
typemod
int
typemod
Table 12 Status values in StatementResponse Status Value
Description
-1
Execution failed.
0
Execution succeeded.
1
Executing.
2
Command completed with no return value.
3
Queued waiting for execution.
- Sample code
// Initialize the DwsRestClient instance and pass necessary parameters. // Parameter descriptions: // - First parameter: base URL (endpoint) of the API // - Second parameter: AK // - Third parameter: SK // - Fourth parameter: security token (optional, if using STS temporary credentials) DwsRestClient client = new DwsRestClient( "https://<your_endpoint_here>", "<your_access_key_here>", "<your_secret_key_here>", "<your_security_token_here>"); workspaceId = "<your_workspace_id_here>"; // Create a CreateSessionRequest object to request a session. CreateSessionRequest request = new CreateSessionRequest(); request.setEndpointId("<your_endpoint_id_here>"); // Create a LakeFormationConfig object and set relevant configurations. LakeFormationConfig lakeFormationConfig = new LakeFormationConfig(); lakeFormationConfig.setCatalog("<your_catalog_here>"); lakeFormationConfig.setInstanceId("<your_instance_id_here>"); request.setLakeFormationConfig(lakeFormationConfig); // Call the client.createSession method to create a session and obtain the session ID. String sessionId = client.createSession(workspaceId, request); // Execute the query. StatementQuery statementQuery = new StatementQuery(); statementQuery.setSessionId(sessionId); statementQuery.setLimit(2); statementQuery.setStatement("select 1"); StatementResponse statementResponse = client.syncQuery(workspaceId, statementQuery);
Executing SQL Statements Asynchronously
- Function
A SQL request is issued asynchronously through a session, returning query information for subsequent retrieval of results. You need to provide the workspace ID and session ID and construct the request body.
- Method definition
asyncQuery(String workspaceId, StatementQuery query) asyncQuery(String workspaceId, StatementQuery query, int timeout) asyncQuery(String workspaceId, StatementQuery query, Map<String, String> headers) asyncQuery(String workspaceId, StatementQuery query, Map<String, String> headers, int timeout)
- Parameter descriptions:
Table 13 asyncQuery parameter descriptions Parameter
Type
Mandatory
Description
workspaceId
String
Yes
ID of the workspace created in DataArts Fabric
query
StatementQuery
Yes
SQL request class
timeout
int
No
Request timeout duration
headers
Map<String,String>
No
HTTP request header
Table 14 StatementQuery Parameter
Type
Mandatory
Description
statement
String
Yes
Content of the SQL to be issued
sessionId
String
Yes
Session ID
limit
int
No
SQL limit
bindings
List<List<String>>
No
Parameter bindings
- Response body: AsyncQueryResponse
Table 15 AsyncQueryResponse Parameter
Type
Description
sessionId
String
Session ID
statementId
String
Statement ID
- Sample code
// Initialize the DwsRestClient instance and pass necessary parameters. // Parameter descriptions: // - First parameter: base URL (endpoint) of the API // - Second parameter: AK // - Third parameter: SK // - Fourth parameter: security token (optional, if using STS temporary credentials) DwsRestClient client = new DwsRestClient( "https://<your_endpoint_here>", "<your_access_key_here>", "<your_secret_key_here>", "<your_security_token_here>"); workspaceId = "<your_workspace_id_here>"; // Create a CreateSessionRequest object to request a session. CreateSessionRequest request = new CreateSessionRequest(); request.setEndpointId("<your_endpoint_id_here>"); // Create a LakeFormationConfig object and set relevant configurations. LakeFormationConfig lakeFormationConfig = new LakeFormationConfig(); lakeFormationConfig.setCatalog("<your_catalog_here>"); lakeFormationConfig.setInstanceId("<your_instance_id_here>"); request.setLakeFormationConfig(lakeFormationConfig); // Call the client.createSession method to create a session and obtain the session ID. String sessionId = client.createSession(workspaceId, request); // Execute the query. StatementQuery statementQuery = new StatementQuery(); statementQuery.setSessionId(sessionId); statementQuery.setLimit(2); statementQuery.setStatement("select 1"); AsyncQueryResponse asyncQueryResponse = client.asyncQuery(workspaceId, statementQuery, headers);
Canceling a Query
- Function
This method allows you to close a specific session using the provided workspace ID, session ID, and statement ID.
- Method definition
cancelExecute(String workspaceId, String sessionId, String statementId) cancelExecute(String workspaceId, String sessionId, String statementId, Map<String, String> headers) cancelExecute(String workspaceId, String sessionId, String statementId, int timeout) cancelExecute(String workspaceId, String sessionId, String statementId, Map<String, String> headers, int timeout)
- Parameter descriptions:
Table 16 closeSession parameter descriptions Parameter
Type
Mandatory
Description
workspaceId
String
Yes
ID of the workspace created in DataArts Fabric
sessionId
String
Yes
Session ID
statementId
String
Yes
Statement ID of the query to be terminated
timeout
int
No
Request timeout duration (The default value is -1, indicating no timeout is set.)
headers
Map<String,String>
No
HTTP request header
- Response
- Sample code
// Initialize the DwsRestClient instance and pass necessary parameters. // Parameter descriptions: // - First parameter: base URL (endpoint) of the API // - Second parameter: AK // - Third parameter: SK // - Fourth parameter: security token (optional, if using STS temporary credentials) DwsRestClient client = new DwsRestClient( "https://<your_endpoint_here>", "<your_access_key_here>", "<your_secret_key_here>", "<your_security_token_here>"); workspaceId = "<your_workspace_id_here>"; // Create a CreateSessionRequest object to request a session. CreateSessionRequest request = new CreateSessionRequest(); request.setEndpointId("<your_endpoint_id_here>"); // Create a LakeFormationConfig object and set relevant configurations. LakeFormationConfig lakeFormationConfig = new LakeFormationConfig(); lakeFormationConfig.setCatalog("<your_catalog_here>"); lakeFormationConfig.setInstanceId("<your_instance_id_here>"); request.setLakeFormationConfig(lakeFormationConfig); // Call the client.createSession method to create a session and obtain the session ID. String sessionId = client.createSession(workspaceId, request); // Execute the query. StatementQuery statementQuery = new StatementQuery(); statementQuery.setSessionId(sessionId); statementQuery.setLimit(2); statementQuery.setStatement("select 1"); AsyncQueryResponse asyncQueryResponse = client.asyncQuery(workspaceId, statementQuery, headers);
Obtaining Query Results (Through OBS)
- Function
You can use statementId and sessionId to query the execution result of the statement and retrieve the result set. This interface method accesses OBS through the Java SDK to obtain and return the result set.
- Method definition
getStatementResult(String workspaceId, String sessionId, String statementId, int pageNum) getStatementResult(String workspaceId, String sessionId, String statementId, int pageNum, int timeout) getStatementResult(String workspaceId, String sessionId, String statementId, int pageNum, Map<String, String> headers) getStatementResult(String workspaceId, String sessionId, String statementId, int pageNum, Map<String, String> headers, int timeout) getStatementResult(String workspaceId, String sessionId, String statementId, int pageNum, Map<String, String> headers, Region region) getStatementResult(String workspaceId, String sessionId, String statementId, int pageNum, Map<String, String> headers, int timeout, Region region)
- Parameter descriptions:
Table 17 Parameter descriptions Parameter
Type
Mandatory
Description
workspaceId
String
Yes
ID of the workspace created in DataArts Fabric
sessionId
String
Yes
Session ID
statementId
String
Yes
Statement ID
pageNum
int
Yes
Page number
timeout
int
No
Request timeout duration
headers
Map<String,String>
No
HTTP request header
region
Region
No
IAM authentication region. For details, see IAM Region Description.
- Response
Table 18 StatementResponse Parameter
Type
Description
status
String
Content of the SQL to be issued
statementId
String
Session ID
sessionId
int
SQL limit
results
List<StatementResult>
Parameter bindings
Table 19 StatementResult Parameter
Type
Description
status
String
Execution status of this SQL statement
statementId
String
Statement ID
numRows
int
Total number of rows in the statement
rowCount
int
Total number of rows on this page
pageCount
int
Total number of pages
pageNo
int
Current page number, starting from 1
errCode
int
Error code
message
String
Error message
resultSet
StatementResultSet
Result set
Table 20 StatementResultSet Parameter
Type
Description
columns
list[RowType]
Column header data
rows
List<List<String>>
Column data
If the request fails or the query inherently contains no result set, both columns and rows in result_set will be null.
Table 21 RowType Parameter
Type
Description
name
String
Name of the column header
tableId
String
Table ID
columnId
String
Column ID
format
int
Format
type
int
Type
size
int
Size
typemod
int
typemod
Table 22 Status values in StatementResponse Status Value
Description
-1
Execution failed.
0
Execution succeeded.
1
Executing.
2
Command completed with no return value.
3
Queued waiting for execution.
- Sample code
// Initialize the DwsRestClient instance and pass necessary parameters. // Parameter descriptions: // - First parameter: base URL (endpoint) of the API // - Second parameter: AK // - Third parameter: SK // - Fourth parameter: security token (optional, if using STS temporary credentials) DwsRestClient client = new DwsRestClient( "https://<your_endpoint_here>", "<your_access_key_here>", "<your_secret_key_here>", "<your_security_token_here>"); workspaceId = "<your_workspace_id_here>"; // Create a CreateSessionRequest object to request a session. CreateSessionRequest request = new CreateSessionRequest(); request.setEndpointId("<your_endpoint_id_here>"); // Create a LakeFormationConfig object and set relevant configurations. LakeFormationConfig lakeFormationConfig = new LakeFormationConfig(); lakeFormationConfig.setCatalog("<your_catalog_here>"); lakeFormationConfig.setInstanceId("<your_instance_id_here>"); request.setLakeFormationConfig(lakeFormationConfig); // Call the client.createSession method to create a session and obtain the session ID. String sessionId = client.createSession(workspaceId, request); // Execute the query. StatementQuery statementQuery = new StatementQuery(); statementQuery.setSessionId(sessionId); statementQuery.setLimit(2); statementQuery.setStatement("select 1"); AsyncQueryResponse asyncQueryResponse = client.asyncQuery(workspaceId, statementQuery); StatementResponse statementResponse = client.getStatementResult(workspaceId, sessionId, asyncQueryResponse.getStatementId(), 1); while (statementResponse.getStatus() == StatementStatus.RUNNING.getValue()) { // Polling interval TimeUnit.SECONDS.sleep(2); statementResponse = client.getStatementResult(workspaceId, sessionId, asyncQueryResponse.getStatementId(), 1); }
Obtaining Query Results (Directly)
- Function
You can use statementId and sessionId to query the execution result of the statement and retrieve the result set. This interface method accesses the server through the Java SDK to directly obtain and return the result set.
- Method definition
StatementResponse getStatementResultDirect(String workspaceId, String sessionId, String statementId, int pageNum, Map<String, String> headers, int timeout)
- Parameter descriptions:
Table 23 Parameter descriptions Parameter
Type
Mandatory
Description
workspaceId
String
Yes
ID of the workspace created in DataArts Fabric
sessionId
String
Yes
Session ID
statementId
String
Yes
Statement ID
pageNum
int
Yes
Page number
timeout
int
No
Request timeout duration
headers
Map<String,String>
No
HTTP request header
- Response
Table 24 StatementResponse Parameter
Type
Description
status
String
Content of the SQL to be issued
statementId
String
Session ID
sessionId
int
SQL limit
results
List<StatementResult>
Parameter bindings
Table 25 StatementResult Parameter
Type
Description
status
String
Execution status of this SQL statement
statementId
String
Statement ID
numRows
int
Total number of rows in the statement
rowCount
int
Total number of rows on this page
pageCount
int
Total number of pages
pageNo
int
Current page number, starting from 1
errCode
int
Error code
message
String
Error message
resultSet
StatementResultSet
Result set
Table 26 StatementResultSet Parameter
Type
Description
columns
list[RowType]
Column header data
rows
List<List<String>>
Column data
If the request fails or the query inherently contains no result set, both columns and rows in result_set will be null.
Table 27 RowType Parameter
Type
Description
name
String
Name of the column header
tableId
String
Table ID
columnId
String
Column ID
format
int
Format
type
int
Type
size
int
Size
typemod
int
typemod
Table 28 Status values in StatementResponse Status Value
Description
-1
Execution failed.
0
Execution succeeded.
1
Executing.
2
Command completed with no return value.
3
Queued waiting for execution.
- Sample code
// Initialize the DwsRestClient instance and pass necessary parameters. // Parameter descriptions: // - First parameter: base URL (endpoint) of the API // - Second parameter: AK // - Third parameter: SK // - Fourth parameter: security token (optional, if using STS temporary credentials) DwsRestClient client = new DwsRestClient( "https://<your_endpoint_here>", "<your_access_key_here>", "<your_secret_key_here>", "<your_security_token_here>"); workspaceId = "<your_workspace_id_here>"; // Create a CreateSessionRequest object to request a session. CreateSessionRequest request = new CreateSessionRequest(); request.setEndpointId("<your_endpoint_id_here>"); // Create a LakeFormationConfig object and set relevant configurations. LakeFormationConfig lakeFormationConfig = new LakeFormationConfig(); lakeFormationConfig.setCatalog("<your_catalog_here>"); lakeFormationConfig.setInstanceId("<your_instance_id_here>"); request.setLakeFormationConfig(lakeFormationConfig); // Call the client.createSession method to create a session and obtain the session ID. String sessionId = client.createSession(workspaceId, request); // Execute the query. StatementQuery statementQuery = new StatementQuery(); statementQuery.setSessionId(sessionId); statementQuery.setLimit(2); statementQuery.setStatement("select 1"); AsyncQueryResponse asyncQueryResponse = client.asyncQuery(workspaceId, statementQuery); StatementResponse statementResponse = client.getStatementResultDirect(workspaceId, sessionId, asyncQueryResponse.getStatementId(), 1,null,-1); while (statementResponse.getStatus() == StatementStatus.RUNNING.getValue() || statementResponse.getStatus() == StatementStatus.WAITING.getValue()) { TimeUnit.SECONDS.sleep(2); statementResponse = client.getStatementResultDirect(workspaceId, sessionId, asyncQueryResponse.getStatementId(), 1,null,-1); }
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot