TQL使用说明

TQL

Author: 放翁（文初）

Email：fangweng@taobao.com

Mblog: weibo.com/fangweng

概要：2

TQL使用说明：3

新增数据：3

查询数据：4

修改数据：5

删除数据：6

嵌套查询：7

嵌套更新：8

复制新增：9

复制修改：10

串行化批量操作：11

概要：

TQL是基于淘宝开放平台服务封装的一种查询语言调用方式，与标准REST化等模式一样，都是调用服务方式的一种变形，目的是希望能够通过使用方式的改变提高开发者开发效率，可维护性，降低性能损耗（减少http连接，调用次数等）。下面将会用具体的通过实际范例来展示使用场景。

同上所说，所有的TQL支持的服务都是开放平台已经开放的服务，因此可以参看开放平台服务文档来构建TQL（http://open.taobao.com/doc/api_list.htm?id=102 ）。

先来说一下几个约定：

1. TQL只支持Json格式的返回（考虑性能和数据占用等问题大部分开放平台已经舍弃了xml）。

2. TQL中的四类操作与开放平台服务名称之间的映射关系为：Select（get），Delete（delete），Update（update，set），Insert（add，upload，publish，create）。例如，文档中taobao.user.get 就可以映射为select xxx from user，taobao.item.delete可以映射为delete from item where tt=xxx。如果发现文档中没有此类服务，则判断是否为读服务，如果是读类的服务采用select 和它原始的api名称，例如select xxx from taobao.items.search。

3. 后面会介绍TQL可以支持嵌套和批量处理，服务计数和原来的方式一样，同时请估计一次请求会演变称为多少次请求，当前平台暂时限制一次请求可以支持嵌套或者批量发起10次真实调用。（以后可以放宽）

4. 在范例中调用服务都没有应用签名，因此在TQL初次发布的时候，使用者必须是将自己应用绑定固定服务器ip的开发者，可以省略签名，如果没有固定ip将会要和普通服务调用一样用签名。

TQL使用说明：

新增数据：

TQL：insert  into  x  (field1,field2,…) values (value1,value2,…)

范例是新增一条商品数据，新增商品的服务定义参见：http://api.taobao.com/apidoc/api.htm?path=cid:4-apiId:22 

调用方式：

http://10.232.127.145/tql/2.0/json?ql=insert into item (num,price,type,stuff_status,title,desc,location.state,location.city,cid,props) values (30,100,fixed,new,放翁测试手机,非常好用的测试内容,浙江,杭州,1512,1740089:11058;20000:4357282;30606:112030;10000:10122;10004:10022;10003:10019;10002:30590;20571:28956;20574:28972;20930:32999;1627207:3232480;1627207:3232482;1630696:3266781;20710:21958;20879:21456)&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

其中ql就是TQL的描述（红色部分），将需要创建的字段作为列写入即可，app_key必须传递，如果需要用户授权，需要通过授权获得session并传递。

返回结果：

{"item_add_response":{"item":{"created":"2011-11-02 17:56:52","iid":"1500003171382","num_iid":1500003171382}}}

查询数据：

TQL：select  field1,field2,…  from  x  where a=a1 and b=b1

范例是查询一条商品数据，查询商品的服务定义参见：http://api.taobao.com/apidoc/api.htm?path=cid:4-apiId:20 

调用方式：

http://10.232.127.145/tql/2.0/json?ql=select num,price,type,stuff_status,title,desc,location.state,location.city,cid,props from item where num_iid=1500003171382&app_key=4272

其中ql就是TQL的描述（红色部分），将需要查询的字段作为列写入即可，app_key必须传递，如果需要用户授权，需要通过授权获得session并传递。

返回结果：

{"item_get_response":{"item":{"cid":1512,"desc":"非常好用的测试内容","location":{"city":"杭州","state":"浙江"},"num":30,"price":"100.00","props":"1627207:3232480;1627207:3232482;21514:42370;30606:112030;10004:10022;10000:10122;10003:10019;1630696:3266781;10002:30590;20571:28956;20574:28972;20879:21456;20930:32999;20000:4357282;1740089:11058","stuff_status":"new","title":"放翁测试手机","type":"fixed"}}}

带有组合条件的查询：

http://10.232.127.145/tql/2.0/json?ql=select price,title from items where cid=1512 and order_by=price:desc&app_key=4272

修改数据：

TQL：update  x  set  field1=value1,field2=value2,…  where a=a1

范例是修改一条商品数据，修改商品的服务定义参见：http://api.taobao.com/apidoc/api.htm?path=cid:4-apiId:21 

调用方式：

http://10.232.127.145/tql/2.0/json?ql=update item set title=放翁测试手机2 where num_iid=1500003171382&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

其中ql就是TQL的描述（红色部分），将需要修改的字段作为列写入即可，app_key必须传递，如果需要用户授权，需要通过授权获得session并传递。

返回结果：

{"item_update_response":{"item":{"iid":"1500003171382","modified":"2011-11-02 17:58:18","num_iid":1500003171382}}}

在通过b的方式查询发现结果如下：

{"item_get_response":{"item":{"cid":1512,"desc":"非常好用的测试内容","location":{"city":"杭州","state":"浙江"},"num":30,"price":"100.00","props":"1627207:3232480;1627207:3232482;21514:42370;30606:112030;10004:10022;10000:10122;10003:10019;1630696:3266781;10002:30590;20571:28956;20574:28972;20879:21456;20930:32999;20000:4357282;1740089:11058","stuff_status":"new","title":"放翁测试手机2","type":"fixed"}}}

删除数据：

TQL：delete  from  x  where a=a1

范例是删除一条商品数据，删除商品的服务定义参见：http://api.taobao.com/apidoc/api.htm?path=cid:4-apiId:112 

调用方式：

http://10.232.127.145/tql/2.0/json?ql=delete from item where num_iid=1500003171382&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

其中ql就是TQL的描述（红色部分），app_key必须传递，如果需要用户授权，需要通过授权获得session并传递。

返回结果：

{"item_delete_response":{"item":{"created":"2011-11-02 17:59:30","iid":"1500003171382","num_iid":1500003171382}}}

在通过b的方式查询发现结果如下：

{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-is-delete:invalid-numIid","sub_msg":"该商品已被删除"}}

嵌套查询：

TQL： select field1,field2,field3 from x where a in (select a from x1 where t=t1 and b=b1)

调用方式：

http://10.232.127.145/tql/2.0/json?ql=select buyer_message,pay_time,seller_nick,buyer_nick,type,price,num,alipay_no,total_fee from trade where tid in (select tid from traderates where role=seller and rate_type=get)&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

支持多层嵌套，执行顺序由后往前顺序执行，如果后面获得的数据是多条，则会执行多次前面的服务调用，服务数据按块逐步返回（不是拼接以后一起返回，提高效率）

例如上面的调用就是先从订单接口获得当前作为卖家授权用户的订单信息，然后再将这些订单的详细交易信息获取出来。这样原本多次的请求合并为一个请求可以完成，节省开发者开发成本和机器资源。

返回结果如下：（只有交易信息，无订单信息，因为订单作为中间结果而不返回）

{"trade_get_response":{"trade":{"alipay_no":"2010112908533670","buyer_nick":"tbtest1062","num":1,"pay_time":"2011-07-25 14:52:39","price":"231.00","seller_nick":"tbtest1063","total_fee":"231.00","type":"fixed"}}}

嵌套更新：

TQL： update x set field1=value1,field2=value2… where a in (select a from x1 where t=t1 and b=b1)

调用方式：

http://10.232.127.145/tql/2.0/json?ql=update item set title=放翁测试手机3 where num_iid in (select num_iid from items where nicks=tbtest1062)&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

支持多层嵌套，执行顺序由后往前顺序执行，如果后面获得的数据是多条，则会执行多次前面的服务调用，执行多次更新，返回更新结果也会按块逐步返回，而非全部完成后统一返回。

例如上面的调用就是先从商品中获得nicks为tbtest1062的所有商品，然后更新这些商品的title。这样原本多次的请求合并为一个请求可以完成，节省开发者开发成本和机器资源。

返回结果如下：（注意，也许有很多纪录，但是当前平台限制后续服务操作小于等于10,因此如果结果集合很大，也只会操作前10个，后续考虑放开）

{"item_update_response":{"item":{"iid":"1500002657021","modified":"2011-11-02 18:03:08","num_iid":1500002657021}}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}{"error_response":{"code":530,"msg":"Remote service error","sub_code":"isv.item-update-service-error:IC_PERMISSION_FOR_SECOND_KILL","sub_msg":"您的这个宝贝处于秒杀活动中，不能进行编辑，可以下架但不能再上架，如果秒杀结束需要自由编辑请联系活动负责人去掉秒杀标记"}}

复制新增：

TQL： insert into x (field1,field2…) values($a$,$b$...) valuefrom  select a,b… from x1 where t=t1 and b=b1

调用方式：

http://10.232.127.145/tql/2.0/json?ql=insert into item (num,price,type,stuff_status,title,desc,location.state,location.city,cid,props) values ($num$,$price$,$type$,$stuff_status$,放翁测试手机,非常好用的测试手机,$location.state$,$location.city$,$cid$,$props$)  valuefrom select num,price,type,stuff_status,title,desc,location.state,location.city,cid,props from item where num_iid=1500005454845&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

复制新增可以将后面选择出来的内容有选择的复制到新增数据的某些字段，作为一些商品类目营销等便利的使用模式。

例如上面的调用就是先从商品中获得一部分属性，然后作为新增商品的一些属性并新增商品。这样原本多次的请求合并为一个请求可以完成，节省开发者开发成本和机器资源。

返回结果如下：（如果后面选择的数据为多条，则采用第一条数据填充）

{"item_add_response":{"item":{"created":"2011-11-02 18:04:28","iid":"1500003171388","num_iid":1500003171388}}}

复制修改：

TQL： update x set  field1=$a$,field2=$b$,field3=value3… where k=k1  valuefrom  select a,b… from x1 where t=t1 and b=b1

调用方式：

http://10.232.127.145/tql/2.0/json?ql=update item set title=$title$ where num_iid=1500003171388 valuefrom select num,price,type,stuff_status,title,desc,location.state,location.city,cid,props from item where num_iid=1500002657021&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

复制修改可以将后面选择出来的内容有选择的复制到需要数据的某些字段，作为一些商品类目营销等便利的使用模式。

例如上面的调用就是先从商品中获得一部分属性，然后作为修改商品的一些属性并修改商品。这样原本多次的请求合并为一个请求可以完成，节省开发者开发成本和机器资源。

返回结果如下：（如果后面选择的数据为多条，则采用第一条数据填充）

{"item_update_response":{"item":{"iid":"1500003171388","modified":"2011-11-02 18:08:23","num_iid":1500003171388}}}

串行化批量操作：

TQL： ｛tql｝｛tql｝｛tql｝

调用方式：

http://10.232.127.145/tql/2.0/json?ql={select price,title,num from items where cid=1512 and order_by=price:desc}{insert into item (num,price,type,stuff_status,title,desc,location.state,location.city,cid,props) values (30,100,fixed,new,放翁测试手机,非常好用的测试内容,浙江,杭州,1512,1740089:11058;20000:4357282;30606:112030;10000:10122;10004:10022;10003:10019;10002:30590;20571:28956;20574:28972;20930:32999;1627207:3232480;1627207:3232482;1630696:3266781;20710:21958;20879:21456)}&app_key=4272&session=41102241973015bd5bdf47d66f7a5204m2gPzbLcd739159657538031

串行化批量操作，就是可以将多个不相关的操作批量提交上来，顺序执行（并行执行可以做，但暂时不考虑，对于开发者来说可以节省多次请求反复调用，服务数据分块返回，同时可以简化开发成本，满足业务需求），串行化执行顺序由后往前执行。

例如上面的调用先执行新增一个商品，然后再执行批量获取满足条件的商品列表，可以很自然的想到我们的新增查询模式。这样原本多次的请求合并为一个请求可以完成，节省开发者开发成本和机器资源。

返回结果如下：（可以看到有两个结果，但是是分批返回的，只要服务执行完毕就返回结果）

{"item_add_response":{"item":{"created":"2011-11-02 18:09:24","iid":"1500003187172","num_iid":1500003187172}}}{"items_get_response":{"items":{"item":[{"price":"1000000.00","title":"有普通运送及货到付款模板"},{"price":"999998.50","title":"Nokia/诺基亚 （王迪）*%（￥@#…【＄★㊣§】＆◆"},{"price":"150000.00","title":"手机价格区间"},{"price":"111111.00","title":"王倩男页尾和页尾文案测试 Nokia/诺基亚 1000"},{"price":"50000.00","title":"update auction_auctions set auction_id =0123"},{"price":"20000.00","title":"电 a  棍"},{"price":"12344.00","title":"测试"},{"price":"10000.00","title":"addadgroup_诺基亚 E71 行货 年轻人(二手)"},{"price":"10000.00","title":"B 普通运送方式   Dell/戴尔 Mini 3iW"},{"price":"10000.00","title":"adsfasdfadsfasdfasdfadf-阳婉测试宝贝10"},{"price":"10000.00","title":"Nokia/诺基亚"},{"price":"10000.00","title":"新品诺基亚手机"},{"price":"9999.99","title":"步步手机01"},{"price":"9999.00","title":"test 1111"},{"price":"9876.00","title":"新品测试-002"},{"price":"9073.00","title":"Samsung/三星"},{"price":"8888.00","title":"Dell/戴尔 Mini 3i dsd"},{"price":"8888.00","title":"新品测试-010"},{"price":"8756.00","title":"限定在30个汉字内（60个字符"},{"price":"8622.00","title":"auctestb121-笔记本电脑-三星/SamsungNC10其它三星NC10"},{"price":"8520.00","title":"诺基亚 E71 行货 年轻人"},{"price":"7654.00","title":"新品测试-003"},{"price":"7600.00","title":"Nokia/诺基亚-0--测试用宝贝4"},{"price":"7333.00","title":"auctestb121-笔记本电脑-三星Q208-DS01(T3400)-13"},{"price":"7222.00","title":"auctestb121-笔记本电脑-三星X460-AS04(P8400)-11"},{"price":"6999.00","title":"测试价格审核----王兆辉"},{"price":"6742.00","title":"Samsung/三星 测试6"},{"price":"6555.00","title":"Dell/戴尔 Mini 3iW  聚划算"},{"price":"6500.00","title":"iphone 5"},{"price":"6000.00","title":"0205小家电Nokia/诺基亚 其它诺基亚型号 9500"},{"price":"5656.00","title":"新品测试-011"},{"price":"5559.00","title":"leafry发布一口价iphone 4"},{"price":"5555.00","title":"Samsung/三星 s5580"},{"price":"5432.00","title":"新品测试-004"},{"price":"5200.00","title":"Samsung/三星 测试"}））,"total_results":5413））