TableTunnel是访问MaxCompute Tunnel服务的入口类,仅支持表数据(非视图)的上传和下载。

TableTunnel接口定义及说明

TableTunnel接口定义如下,详情请参见Java-sdk-doc
public class TableTunnel {
 public DownloadSession createDownloadSession(String projectName, String tableName);
 public DownloadSession createDownloadSession(String projectName, String tableName, PartitionSpec partitionSpec);
 public UploadSession createUploadSession(String projectName, String tableName,boolean overwrite);
 public UploadSession createUploadSession(String projectName, String tableName, PartitionSpec partitionSpec,boolean overwrite);
 public DownloadSession getDownloadSession(String projectName, String tableName, PartitionSpec partitionSpec, String id);
 public DownloadSession getDownloadSession(String projectName, String tableName, String id);
 public UploadSession getUploadSession(String projectName, String tableName, PartitionSpec partitionSpec, String id);
 public UploadSession getUploadSession(String projectName, String tableName, String id);
}
接口说明如下:
  • 生命周期:从TableTunnel实例被创建开始,一直到程序结束。
  • TableTunnel提供创建UploadSession对象和DownloadSession对象的方法。数据的上传和下载分别由TableTunnel.UploadSessionTableTunnel.DownloadSession这两个Session实现。
  • 对一张表或分区上传下载的过程,称为一个Session。Session由一或多个访问Tunnel RESTful API的HTTP Request组成。
  • 在UploadSession中,每个RecordWriter对应一个HTTP Request,由一个Block ID标识,对应服务端一个文件(Block ID即对应的文件名)。
  • 同一Session中,使用同一Block ID多次打开RecordWriter的行为会导致数据覆盖,最后一个调用close()的RecordWriter上传的数据会被保留。该特性可用于Block的上传失败重传。
  • TableTunnel的UploadSession中:
    • 如果没有指定boolean overwrite参数,则默认是INSERT INTO语义。
    • 如果指定了boolean overwrite参数,且传入的参数值为True,则默认是INSERT OVERWRITE语义。
    • 如果指定了boolean overwrite参数,且传入的参数值为False,则默认是INSERT INTO语义。
    两种语义的说明如下:
    • INSERT INTO,即对同一张表或分区的多个、多次上传Session互不影响,每个Session上传的数据会位于不同的目录中。
    • INSERT OVERWRITE,即当次上传会覆盖对应表或分区里的所有数据。如果使用该模式请不要对同一表或分区执行并发操作。

TableTunnel接口实现流程

  1. RecordWriter.write()将数据上传到临时目录的文件。
  2. RecordWriter.close()将相应的文件从临时目录移到数据目录。
  3. session.commit()将相应数据目录下的所有文件移到相应表所在目录,并更新表Meta,即数据进表。使数据对其它MaxCompute任务(例如SQL、MapReduce)可见。

TableTunnel接口限制

  • Block ID的取值范围是[0, 20000),单个Block上传的数据限制为100GB。
  • Session用Session ID来标识。Session的超时时间为24小时。如果大批量数据传送导致超过24小时,需要自行拆分成多个Session。
  • RecordWriter对应的HTTP Request超时时间为120s。如果120s内HTTP连接上没有数据流过,服务端会主动关闭连接。
    说明 HTTP本身还有8KB的缓存,因此并不是每次调用RecordWriter.write()都能保证HTTP连接上有数据流过。TunnelRecordWriter.flush()可以将Buffer内数据强制刷出。
  • 对于日志类写入MaxCompute的场景,无法预测数据的到达时间会造成RecordWriter超时。因此:
    • 不建议对每条数据打开一个RecordWriter。因为每个RecordWriter对应一个文件,此操作会造成小文件过多,严重影响MaxCompute后续使用性能。
    • 建议用户代码Cache至少64MB的数据后,再使用一个RecordWriter进行一次性批量写入。
  • RecordReader的超时时间为300s。
  • 如果用户访问的Endpoint是公网对应的地址,具体公网Endpoint地址请参见Endpoint,会产生下载费用,具体费用请参见下载费用
  • 用户使用公网Endpoint下载数据,如果已经开启下载权限检查,需要有Download数据对应的权限。具体授权明细请参见Download权限控制