Updated on 2025-08-25 GMT+08:00

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

    The response is empty.

  • 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

    The response is empty.

  • 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);
    }