com.aliyun.odps.task

Class SQLTask

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

Constructor Summary

Constructors

Constructor and Description
SQLTask()

Method Summary

Modifier and Type	Method and Description
String	getCommandText() 获取 Task 命令信息
String	getQuery()
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 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, 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 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) 运行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

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,
                                                     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

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

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,
                           int 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