SQLTask (ODPS SDK Core 0.52.0-public API)

java.lang.Object
- com.aliyun.odps.Task
- - com.aliyun.odps.task.SQLTask

```
public class SQLTask
extends Task
```
SQLTask的定义

Nested Class Summary
- Nested classes/interfaces inherited from class com.aliyun.odps.Task
  Task.Properties, Task.Property

Field Summary

Fields
Modifier and Type Field and Description

static String AnonymousSQLTaskName

Fields
Modifier and Type	Field and Description
`static String`	`AnonymousSQLTaskName`

Constructor Summary

Constructors
Constructor and Description

SQLTask()

Constructors
Constructor and Description
`SQLTask()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`String`	`getCommandText()` 获取 Task 命令信息
`String`	`getQuery()`
`static String`	`getRawResult(Instance instance)`
`static String`	`getRawResult(Instance instance, String taskName)`
`static List<Record>`	`getResult(Instance instance)` Return 1W records at most.
`static List<Record>`	`getResult(Instance instance, String taskName)` Return 1W records at most.
`static List<Record>`	`getResultByInstanceTunnel(Instance instance)` 使用 instance tunnel 的方式获取 Anonymous task 的结果
`static List<Record>`	`getResultByInstanceTunnel(Instance instance, Long limit)` 使用 instance tunnel 的方式获取 Anonymous task 的结果
`static List<Record>`	`getResultByInstanceTunnel(Instance instance, String taskName)` 使用 instance tunnel 的方式获取 instance 结果当数据量不大于 `#SQL_TASK_RESULT_LIMIT` 条时,成功; 若数据量量大于 `#SQL_TASK_RESULT_LIMIT` 条, 返回 SQL_TASK_RESULT_LIMIT 条结果; 可使用 `getResultByInstanceTunnel(Instance, String, Long)` 接口调整 limit 参数, 来获取更多数据;
`static List<Record>`	`getResultByInstanceTunnel(Instance instance, String taskName, Long limit)` Return 1W records with completed schema info at most.
`static List<Record>`	`getResultByInstanceTunnel(Instance instance, String taskName, Long limit, boolean limitEnabled)`
`static TableSchema`	`getResultSchema(Instance instance)` 获取运行 SQL 运行结果的 schema 信息。
`static ResultSet`	`getResultSet(Instance instance)` 通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载
`static ResultSet`	`getResultSet(Instance instance, Long limit)` 通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载
`static ResultSet`	`getResultSet(Instance instance, String taskName)` 通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载
`static ResultSet`	`getResultSet(Instance instance, String taskName, InstanceTunnel instanceTunnel, Long limit, boolean limitHint)`
`static ResultSet`	`getResultSet(Instance instance, String taskName, Long limit)` 通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载
`static ResultSet`	`getResultSet(Instance instance, String taskName, Long limit, boolean limitHint)` 通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注： 1.只有instance的owner本人可以使用本接口 2.当limitHint为true时，结果最多只能获得1条记录，超过将截断，但无需进行逐表的权限检查 3.当limitHint为false时，没有记录数限制，可获取instance对应query结果集的全量数据。但前提是需要逐表（SQL中涉及的表与视图）对用户进行权限检查，所以当查询涉及表所在project打开protection时，需要提前在policy中为相应表和视图添加exception，否则无权下载
`static ResultSet`	`getResultSet(Instance instance, String taskName, Long limit, boolean limitHint, URI tunnelEndpoint)` 通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。 1.只有instance的owner本人可以使用本接口 2.当limitHint为true时，结果最多只能获得1条记录，超过将截断，但无需进行逐表的权限检查 3.当limitHint为false时，没有记录数限制，可获取instance对应query结果集的全量数据。但前提是需要逐表（SQL中涉及的表与视图）对用户进行权限检查，所以当查询涉及表所在project打开protection时，需要提前在policy中为相应表和视图添加exception，否则无权下载
`static List<String>`	`getSqlWarning(Instance instance)` 获取运行 SQL 的编译警告信息，可能有多条.
`static List<String>`	`getSqlWarning(Instance instance, String taskName)` 获取运行 SQL 的编译警告信息，可能有多条.
`static List<Record>`	`parseCsvRecord(String csvResult)` 解析 CSV 格式的数据字符串，转换为 record 列表
`static void`	`removeDefaultHints()`
`static Instance`	`run(Odps odps, String sql)` 运行 SQL. 特别注意，在执行数据读取操作时：正常情况下的 task 执行后，task 的状态为 SUCCESS，并正常返回数据结果。但是，当读取数据量超过 10MB，task 的状态将是 FAILED，返回的数据结果为 error message。因此,大量数据的获取建议使用 `TableTunnel` 进行操作。示例代码：
`static Instance`	`run(Odps odps, String sql, SQLTaskOption option)`
`static Instance`	`run(Odps odps, String project, String sql, Map<String,String> hints, Map<String,String> aliases)` 运行SQL
`static Instance`	`run(Odps odps, String project, String sql, String taskName, Map<String,String> hints, Map<String,String> aliases)`
`static Instance`	`run(Odps odps, String project, String sql, String taskName, Map<String,String> hints, Map<String,String> aliases, int priority)` Deprecated.
`static Instance`	`run(Odps odps, String project, String sql, String taskName, Map<String,String> hints, Map<String,String> aliases, Integer priority)` 运行SQL
`static Instance`	`run(Odps odps, String project, String sql, String taskName, Map<String,String> hints, Map<String,String> aliases, Integer priority, String mcqaConnHeader)` 运行SQL
`static void`	`setDefaultHints(Map<String,String> hints)`
`void`	`setQuery(String query)` 设置SQL查询语句

Methods inherited from class com.aliyun.odps.Task
getComment, getName, getProperties, setComment, setName, setProperties, setProperty

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- AnonymousSQLTaskName
```
public static final String AnonymousSQLTaskName
```
  See Also:
  
  Constant Field Values

Constructor Detail
- SQLTask
```
public SQLTask()
```

Method Detail

getQuery
```
public String getQuery()
```

setDefaultHints

public static void setDefaultHints(Map<String,String> hints)

removeDefaultHints

public static void removeDefaultHints()

setQuery
```
public void setQuery(String query)
```
设置SQL查询语句

Parameters:

query - 需要执行的SQL查询

parseCsvRecord
```
public static List<Record> parseCsvRecord(String csvResult)
                                   throws OdpsException
```
解析 CSV 格式的数据字符串，转换为 record 列表

Parameters:

csvResult - 数据字符串

Returns:

记录列表

Throws:

OdpsException

getResult

public static List<Record> getResult(Instance instance,
                                     String taskName)
                              throws OdpsException

Return 1W records at most.
Columns of each record in result are ALL OdpsType.STIRNG, ignore their real type in odps
Return value is valid only when SQL query is select, otherwise, result will be empty.
This API is used when SQLTask Instance is created with specific task name.
Example:

 {
   String taskName = "test_select_sql_task";
   Instance i = SQLTask.run(odps, odps.getDefaultProject(),
                            "select * from test_select_sql_result;",
                            taskName, null, null, 3);
   instance.waitForSuccess();
   List records = SQLTask.getResult(i, taskName);
 }

Parameters:: instance -
Returns:
Throws:: OdpsException
See Also:: #getResultByInstanceTunnel(Instance, String, Long)}

getResultByInstanceTunnel
```
public static List<Record> getResultByInstanceTunnel(Instance instance,
                                                     String taskName,
                                                     Long limit)
                                              throws OdpsException,
                                                     IOException
```
Return 1W records with completed schema info at most. No data size limit.
Return value is valid only when SQL query is select, otherwise, result will be empty.
This API is used when SQLTask Instance is created with specific task name.
Example:
```
 {
   String taskName = "test_select_sql_task";
   Instance i = SQLTask.run(odps, odps.getDefaultProject(),
                            "select * from test_select_sql_result;",
                            taskName, null, null, 3);
   instance.waitForSuccess();
   List records = SQLTask.getResultByInstanceTunnel(i, taskName, 1000L);
 }
 
```
使用 instance tunnel 的方式获取 task 结果. 本接口与 getResult(Instance, String) 略有不同: 1) 本接口返回的 record 带有完整 schema 信息; 2) 本接口返回的 record 结果集有 1W 的条数限制，但不再有 10M 的大小限制注意 : 返回结果类型为 List, 数据量较大时会带来较多内存开销, 大数据量下载建议直接使用 InstanceTunnel 或 getResultSet(Instance, String);
Parameters:

instance - instance 对象

taskName - task 名称

limit - 获取结果的数量

Returns:

record list

Throws:

OdpsException, - IOException

OdpsException

IOException

getResultByInstanceTunnel

public static List<Record> getResultByInstanceTunnel(Instance instance,
                                                     String taskName,
                                                     Long limit,
                                                     boolean limitEnabled)
                                              throws OdpsException,
                                                     IOException

Throws:: OdpsException; IOException

getResultByInstanceTunnel

public static List<Record> getResultByInstanceTunnel(Instance instance,
                                                     Long limit)
                                              throws OdpsException,
                                                     IOException

使用 instance tunnel 的方式获取 Anonymous task 的结果

Parameters:: instance - instance 对象; limit - 获取结果的数量
Returns:: record list
Throws:: OdpsException, - IOException; OdpsException; IOException
See Also:: getResultByInstanceTunnel(Instance, String, Long)

getResultByInstanceTunnel
```
public static List<Record> getResultByInstanceTunnel(Instance instance,
                                                     String taskName)
                                              throws OdpsException,
                                                     IOException
```
使用 instance tunnel 的方式获取 instance 结果当数据量不大于 #SQL_TASK_RESULT_LIMIT 条时,成功; 若数据量量大于 #SQL_TASK_RESULT_LIMIT 条, 返回 SQL_TASK_RESULT_LIMIT 条结果; 可使用 getResultByInstanceTunnel(Instance, String, Long) 接口调整 limit 参数, 来获取更多数据;

Parameters:

instance - instance 对象

taskName - task 名称

Returns:

record list

Throws:

OdpsException, - IOException

OdpsException

IOException

getResultByInstanceTunnel

public static List<Record> getResultByInstanceTunnel(Instance instance)
                                              throws OdpsException,
                                                     IOException

使用 instance tunnel 的方式获取 Anonymous task 的结果

Parameters:: instance - instance 对象
Returns:: record list
Throws:: OdpsException, - IOException; OdpsException; IOException
See Also:: getResultByInstanceTunnel(Instance, String)

getResult
```
public static List<Record> getResult(Instance instance)
                              throws OdpsException
```
Return 1W records at most.
Columns of each record in result are ALL OdpsType.STIRNG, ignore their real type in odps
Return value is valid only when SQL query is select, otherwise, result will be empty.
Default task name 'AnonymousSQLTask' will be used.

Example:
```
 {
    Instance i = SQLTask.run(odps, "select * from test_select_sql_result;");
    instance.waitForSuccess();
    List records = SQLTask.getResult(i);
 }
 
```
Parameters:

instance -

Returns:

Throws:

OdpsException

getResultSet
```
public static ResultSet getResultSet(Instance instance)
                              throws OdpsException,
                                     IOException
```
通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载

Parameters:

instance -

Returns:

Throws:

OdpsException

IOException

getResultSet
```
public static ResultSet getResultSet(Instance instance,
                                     String taskName)
                              throws OdpsException,
                                     IOException
```
通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载

Parameters:

instance -

taskName -

Returns:

Throws:

OdpsException

IOException

getResultSet
```
public static ResultSet getResultSet(Instance instance,
                                     Long limit)
                              throws OdpsException,
                                     IOException
```
通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载

Parameters:

instance -

limit -

Returns:

Throws:

OdpsException

IOException

getResultSet
```
public static ResultSet getResultSet(Instance instance,
                                     String taskName,
                                     Long limit)
                              throws OdpsException
```
通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。但是只有instance的owner本人可以使用本接口，且当对应project打开protection时，需要提前在policy中为对应SQL中涉及的相应表和视图添加exception，否则无权下载

Parameters:

instance -

taskName -

limit -

Returns:

Throws:

OdpsException

getResultSet
```
public static ResultSet getResultSet(Instance instance,
                                     String taskName,
                                     Long limit,
                                     boolean limitHint)
                              throws OdpsException
```
通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注： 1.只有instance的owner本人可以使用本接口 2.当limitHint为true时，结果最多只能获得1条记录，超过将截断，但无需进行逐表的权限检查 3.当limitHint为false时，没有记录数限制，可获取instance对应query结果集的全量数据。但前提是需要逐表（SQL中涉及的表与视图）对用户进行权限检查，所以当查询涉及表所在project打开protection时，需要提前在policy中为相应表和视图添加exception，否则无权下载

Parameters:

instance -

taskName -

limit -

limitHint -

Returns:

Throws:

OdpsException

getResultSet
```
public static ResultSet getResultSet(Instance instance,
                                     String taskName,
                                     Long limit,
                                     boolean limitHint,
                                     URI tunnelEndpoint)
                              throws OdpsException
```
通过instance获取记录迭代器，从而可以让用户通过迭代器逐条获取记录来避免一次性获取全量数据到本地时撑爆内存的问题注：本接口使用 instance tunnel 实现，没有记录数限制，可获取instance对应query结果集的全量数据。 1.只有instance的owner本人可以使用本接口 2.当limitHint为true时，结果最多只能获得1条记录，超过将截断，但无需进行逐表的权限检查 3.当limitHint为false时，没有记录数限制，可获取instance对应query结果集的全量数据。但前提是需要逐表（SQL中涉及的表与视图）对用户进行权限检查，所以当查询涉及表所在project打开protection时，需要提前在policy中为相应表和视图添加exception，否则无权下载

Parameters:

instance -

taskName -

limit -

limitHint -

tunnelEndpoint - 指定 tunnel endpoint

Returns:

Throws:

OdpsException

getResultSet

public static ResultSet getResultSet(Instance instance,
                                     String taskName,
                                     InstanceTunnel instanceTunnel,
                                     Long limit,
                                     boolean limitHint)
                              throws OdpsException

Throws:: OdpsException

getCommandText
```
public String getCommandText()
```
Description copied from class: Task

获取 Task 命令信息

Overrides:

getCommandText in class Task

Returns:

Task 命令信息

getSqlWarning
```
public static List<String> getSqlWarning(Instance instance)
                                  throws OdpsException
```
获取运行 SQL 的编译警告信息，可能有多条.

Parameters:

instance - instance 对象

Returns:

编译警告信息

Throws:

OdpsException

getSqlWarning

public static List<String> getSqlWarning(Instance instance,
                                         String taskName)
                                  throws OdpsException

获取运行 SQL 的编译警告信息，可能有多条.

Parameters:: instance - instance 对象; taskName - task 名称
Returns:: 编译警告信息
Throws:: OdpsException

getResultSchema
```
public static TableSchema getResultSchema(Instance instance)
                                   throws OdpsException
```
获取运行 SQL 运行结果的 schema 信息。

Parameters:

instance - Instance 对象

Returns:

运行结果的 schema

Throws:

OdpsException

run

public static Instance run(Odps odps,
                           String sql)
                    throws OdpsException

运行 SQL.
特别注意，在执行数据读取操作时：
正常情况下的 task 执行后，task 的状态为 SUCCESS，并正常返回数据结果。
但是，当读取数据量超过 10MB，task 的状态将是 FAILED，返回的数据结果为 error message。
因此,大量数据的获取建议使用 TableTunnel 进行操作。

示例代码：

 {
    String sql = "select ....;";

    Instance instance = SQLTask.run(odps, sql);

    instance.waitForSuccess();

    Map results = instance.getTaskResults();
    Map taskStatus = instance.getTaskStatus();

    for(Entry status : taskStatus.entrySet()) {
        if (TaskStatus.Status.SUCCESS == status.getValue().getStatus()) {
           String result = results.get(status.getKey());
          System.out.println(result);
        }
    }
 }

Parameters:: {@link - Odps}; sql - 需要执行的SQL查询
Returns:: 运行实例 Instance
Throws:: OdpsException

run

public static Instance run(Odps odps,
                           String project,
                           String sql,
                           Map<String,String> hints,
                           Map<String,String> aliases)
                    throws OdpsException

运行SQL

Parameters:: odps - Odps对象; project - 任务运行时所属的Project名称; sql - 需要运行的SQL查询; hints - 能够影响SQL执行的Set信息，例如：odps.mapred.map.split.size等; aliases - Alias信息。详情请参考用户手册中alias命令的相关介绍
Returns:: 作业运行实例 Instance
Throws:: OdpsException

run

public static Instance run(Odps odps,
                           String project,
                           String sql,
                           String taskName,
                           Map<String,String> hints,
                           Map<String,String> aliases)
                    throws OdpsException

Throws:: OdpsException

run

public static Instance run(Odps odps,
                           String project,
                           String sql,
                           String taskName,
                           Map<String,String> hints,
                           Map<String,String> aliases,
                           Integer priority)
                    throws OdpsException

运行SQL

Parameters:: odps - Odps对象; project - 任务运行时所属的Project名称; sql - 需要运行的SQL查询; taskName - 任务名称; hints - 能够影响SQL执行的Set信息，例如：odps.mapred.map.split.size等; aliases - Alias信息。详情请参考用户手册中alias命令的相关介绍; priority - 作业优先级 (注：公共云环境此参数无效)
Returns:: 作业运行实例 Instance
Throws:: OdpsException

run

@Deprecated
public static Instance run(Odps odps,
                                       String project,
                                       String sql,
                                       String taskName,
                                       Map<String,String> hints,
                                       Map<String,String> aliases,
                                       int priority)
                                throws OdpsException

Deprecated.

Throws:: OdpsException

run

public static Instance run(Odps odps,
                           String project,
                           String sql,
                           String taskName,
                           Map<String,String> hints,
                           Map<String,String> aliases,
                           Integer priority,
                           String mcqaConnHeader)
                    throws OdpsException

运行SQL

Parameters:: odps - Odps对象; project - 任务运行时所属的Project名称; sql - 需要运行的SQL查询; taskName - 任务名称; hints - 能够影响SQL执行的Set信息，例如：odps.mapred.map.split.size等; aliases - Alias信息。详情请参考用户手册中alias命令的相关介绍; priority - 作业优先级 (注：公共云环境此参数无效); mcqaConnHeader - 是否开启MCQA V2, 应当指定 MCQA 2.0 Quota.getMcqaConnHeader()
Returns:: 作业运行实例 Instance
Throws:: OdpsException

run

public static Instance run(Odps odps,
                           String sql,
                           SQLTaskOption option)
                    throws OdpsException

Throws:: OdpsException

getRawResult

public static String getRawResult(Instance instance,
                                  String taskName)
                           throws OdpsException

Throws:: OdpsException

getRawResult

public static String getRawResult(Instance instance)
                           throws OdpsException

Throws:: OdpsException

Class SQLTask

Nested Class Summary

Nested classes/interfaces inherited from class com.aliyun.odps.Task

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.aliyun.odps.Task

Methods inherited from class java.lang.Object

Field Detail

AnonymousSQLTaskName

Constructor Detail

SQLTask

Method Detail

getQuery

setDefaultHints

removeDefaultHints

setQuery

parseCsvRecord

getResult

getResultByInstanceTunnel

getResultByInstanceTunnel

getResultByInstanceTunnel

getResultByInstanceTunnel

getResultByInstanceTunnel

getResult

getResultSet

getResultSet

getResultSet

getResultSet

getResultSet

getResultSet

getResultSet

getCommandText

getSqlWarning

getSqlWarning

getResultSchema

run

run

run

run

run

run

run

getRawResult

getRawResult