InstanceTunnel lets you download the execution results of a SELECT statement instance through the MaxCompute Java SDK. Use it when you need programmatic access to query results — for example, in batch pipelines, ETL jobs, or any workflow where you retrieve results asynchronously after submitting a query.
How it works
Submit a SQL query and get an instance ID.
Create a
DownloadSessionusing the instance ID.Read records from the session in batches.
Because the download is asynchronous, you can store the instance ID and create a session later — even from a different process or after reconnecting.
Prerequisites
Before you begin, ensure that you have:
The MaxCompute Java SDK. See the Java SDK reference
Read permissions on the instance, or read permissions on all source tables if the result set exceeds 10,000 records. See Permissions
API reference
InstanceTunnel exposes two methods to create a download session:
public class InstanceTunnel {
public DownloadSession createDownloadSession(String projectName, String instanceID);
public DownloadSession createDownloadSession(String projectName, String instanceID, boolean limitEnabled);
}Parameters
| Parameter | Type | Description |
|---|---|---|
projectName | String | The name of the MaxCompute project. |
instanceID | String | The ID of the SQL instance. To find the instance ID, see View instance information. |
limitEnabled | boolean | Specifies whether to enable the download limit. |
Permissions
InstanceTunnel enforces permission checks based on result size to protect data security:
10,000 records or fewer: Any user with read permissions on the instance can download the results. The same rule applies to result downloads via the RESTful API.
More than 10,000 records: Only users with read permissions on all source tables referenced in the SQL query can download the results.
Billing
Downloading results through a public endpoint incurs download fees. For a list of public endpoint addresses, see Endpoint.
If the download control feature is enabled, users downloading through public endpoints must also have the related download permissions. For authorization details, see Download control.