# 数据自定义查询 API
在查询密钥生成后,您就可以通过调用自定义查询 API 进行项目数据的查询。请参见Open API文档中的调用方法描述。
# 一、SQL查询
# SQL查询
接口URL
/querySql?token=xxx&format=json&timeoutSeconds=10&sql=select "#country","#province","#city" from v_event_102 where "$part_date"='2018-10-01' limit 200
请求方式
POST
Content-Type
application/x-www-form-urlencoded
请求Query参数
参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|---|
token | xxx | String | 是 | 查询密钥 |
sql | select "#country","#province","#city" from v_event_102 where "$part_date"='2018-10-01' limit 200 | String | 是 | 查询的 SQL 语句 |
format | json | String | 否 | 行数据格式默认 json (json,csv,csv_header,tsv,tsv_header ,json_object ) |
timeoutSeconds | 10 | Integer | 否 | 请求超时参数,超时则取消查询任务 |
成功响应示例
返回结果按行分隔,每行格式为执行查询语句时指定的格式。
1.json 格式返回结果
当格式为 json 时,首行包含了状态值和数据元信息,格式如下:
{
"data": {
"headers": [
"#country",
"#province",
"#city"
]
},
"return_code": 0,
"return_message": "success"
}
参数名 | 示例值 | 参数类型 | 参数描述 | |
---|---|---|---|---|
return_code | 0 | Integer | 返回码 | |
return_message | success | String | 返回信息 | |
data | - | Object | 返回结果 | |
∟ headers | ["#country", "#province", "#city"] | List | 首行 | |
如果查询结果不为空,首行之后是数据行
["中国","甘肃省","兰州市"]
["中国","北京市","北京市"]
["中国","广东省","广州市"]
["中国","甘肃省","兰州市"]
2.其他格式返回结果
当格式为 csv_header 或 tsv_header 时,首行为列名信息(csv):
"#country","#province","#city"
之后是每行为一个列表,包含了返回的结果(csv)
"中国","甘肃省","兰州市"
"中国","北京市","北京市"
"中国","广东省","广州市"
"中国","甘肃省","兰州市"
3.当格式为 csv 或 tsv 时
结果中没有列名信息,只有数据内容。
curl 示例
curl -X POST 'http://ta2:8992/querySql?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD' --header 'Content-Type: application/x-www-form-urlencoded' -d 'sql=select+%22%23country%22%2c%22%23province%22%2c%22%23city%22+from+v_event_102+where+%22%24part_date%22%3d%272018-10-01%27+limit+200&format=json&timeoutSeconds=10'
# 二、SQL分页查询
SQL 分页查询 API 包含两个相关方法。第一个方法用于执行查询语句,执行结束后返回结果的 meta 信息和分页信息;第二个方法用于下载结果分页数据。
# 执行查询语句
接口URL
/open/execute-sql?token=xxx&sql=select * from v_user_0 limit 11000&pageSize=10000&format=json&timeoutSeconds=10
请求方式
POST
Content-Type
application/x-www-form-urlencoded
请求Query参数
参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|---|
token | xxx | String | 是 | 查询密钥 |
sql | select * from v_user_0 limit 11000 | String | 是 | 查询的 SQL 语句 |
format | json | String | 否 | 行数据格式(json,csv,tsv,json_object),默认 json |
pageSize | 10000 | Integer | 否 | 每页行数,最小 1000,默认 10000 |
timeoutSeconds | 10 | Integer | 否 | 请求超时参数,超时则取消查询任务 |
成功响应示例
{
"data": {
"headers": [
"#user_id",
"#account_id",
"#distinct_id",
"#active_time",
"#reg_time",
"#user_operation",
"#server_time",
"#is_delete",
"#update_time",
"user_level",
"coin_num",
"register_time",
"diamond_num",
"first_recharge_time"
],
"pageCount": 2,
"pageSize": 10000,
"rowCount": 11000,
"taskId": "119a3a37411f3000"
},
"return_code": 0,
"return_message": "success"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | 0 | Integer | 返回码 |
return_message | success | String | 返回信息 |
data | - | Object | 返回数据 |
∟ pageCount | 2 | Integer | 结果数据的总页数 |
∟ pageSize | 10000 | Integer | 每页行数 |
∟ rowCount | 11000 | Integer | 结果数据的总行数 |
∟ header | ["#user_id"] | List | 首行字段列表 |
∟ taskId | 119a3a37411f3000 | String | 任务ID |
错误响应示例
{
"return_code": -1008,
"return_message": "参数(token)为空"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | -1008 | Integer | 返回码 |
return_message | 参数(token)为空 | String | 返回信息 |
curl 示例
curl -X POST 'http://ta2:8992/open/execute-sql?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD' --header 'Content-Type: application/x-www-form-urlencoded' -d 'sql=select%20*%20from%20v_user_0%20limit%2011000&pageSize=10000&format=json&timeoutSeconds=10'
# 下载结果分页数据
接口URL
/open/sql-result-page?token=xxx&taskId=119a3a37411f3000&pageId=0
请求方式
GET
Content-Type
application/json
请求Query参数
参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|---|
token | xxx | String | 是 | 查询密钥 |
taskId | 119a3a37411f3000 | String | 是 | 来自 执行查询语句 接口的返 回 字段taskId |
pageId | 0 | Integer | 否 | 取值范围:[0, pageCount-1],默认为0 |
2.1 返回结果按行分隔,每行数据的格式为执行查询语句时指定的格式
[9324080,"c21756080","c40404080","2019-12-15 16:09:07.000","2019-12-15 16:09:07.000","user_set","2019-12-15 16:22:13.000",false,"2020-06-03 13:10:02.494",6,40000,"2019-12-15 16:09:07.000",0,null]
[9328294,"q21765894","q40422294","2019-12-15 16:19:49.000","2019-12-15 16:19:49.000","user_set","2019-12-15 16:42:18.000",false,"2020-06-03 13:10:02.494",17,642440,"2019-12-15 16:19:49.000",112,"2019-12-15 16:26:13.000"]
[9335719,"t21783319","t40454719","2019-12-15 16:29:45.000","2019-12-15 16:29:45.000","user_set","2019-12-15 16:42:18.000",false,"2020-06-03 13:10:02.494",6,70000,"2019-12-15 16:29:45.000",0,null]
2.2 在/open/execute-sql中format选择json_object时,返回的结果格式如下:
{"app_version": "1.1", "channel": "百度", "server_time": "2020-06-03 13:10:02.494", "distinct_id": "c40404080"}
{"app_version": "1.1", "channel": "百度", "server_time": "2020-06-03 13:10:02.494", "distinct_id": "q21765894"}
{"app_version": "1.1", "channel": "百度", "server_time": "2020-06-03 13:10:02.494", "distinct_id": "t21783319"}
错误响应示例
{
"return_code": -1,
"return_message": "The task is running"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | -1 | Integer | 返回码 |
return_message | The task is runningThe task is running | String | 返回信息 |
curl 示例
curl -X GET 'http://ta2:8992/open/sql-result-page?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&taskId=119a3a37411f3000&pageId=1'
# 三、SQL异步查询API
SQL 异步查询 API 包含四个相关方法。
- 提交查询语句,返回查询的任务ID;
- 查询任务的执行状态。
- 查询任务的结果数据。
- 取消未结束的任务。
# 执行查询语句
接口URL
/open/submit-sql?token=xxx&format=json&sql=select * from v_user_0 limit 11000
请求方式
POST
Content-Type
application/json
请求Query参数
参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|---|
token | xxx | String | 是 | 查询密钥 |
sql | select * from v_user_0 limit 11000 | String | 是 | 查询的 SQL 语句 |
format | json | String | 否 | 行数据格式(json,csv,tsv ,json_object ),默认 json |
pageSize | 1000 | Integer | 否 | 每页行数,最小 1000,默认不分页 |
成功响应示例
{
"data": {
"taskId": "119a3a37411f3000"
},
"return_code": 0,
"return_message": "success"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
data | - | Object | 返回结果 |
∟ taskId | 119a3a37411f3000 | String | 任务ID |
return_code | 0 | Integer | 返回码 |
return_message | success | String | 返回信息 |
错误响应示例
{
"return_code": -1008,
"return_message": "参数(token)为空"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | -1008 | Integer | 返回码 |
return_message | 参数(token)为空 | String | 返回信息 |
curl 示例
curl -X POST 'http://ta2:8992/open/submit-sql?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD' --header 'Content-Type: application/x-www-form-urlencoded' -d 'sql=select%20*%20from%20v_user_0%20limit%2011000&format=json'
# 查询任务的执行状态
接口URL
/open/sql-task-info?token=xxx&taskId=119a3a37411f3000
请求方式
GET
Content-Type
application/json
请求Query参数
参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|---|
token | xxx | String | 是 | 查询密钥 |
taskId | 119a3a37411f3000 | String | 是 | 接口 执行查询语句 返回结果中的taskId |
成功响应示例
{
"data": {
"taskId": "119a3a37411f3000",
"status": "FINISHED",
"progress": 100,
"resultStat": {
"rowCount": 11000,
"pageCount": 1,
"headers": [
"#user_id",
"#account_id",
"#distinct_id",
"#active_time",
"#reg_time",
"#user_operation",
"#server_time",
"#is_delete",
"#update_time",
"user_level",
"coin_num",
"register_time",
"diamond_num",
"first_recharge_time"
]
}
},
"return_code": 0,
"return_message": "success"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | 0 | Integer | 返回码 |
return_message | success | String | 返回信息 |
data | - | Object | 返回结果 |
∟ taskId | 119a3a37411f3000 | String | 查询任务的 ID,用于后续下载结果分页数据 |
∟ status | FINISHED | String | 任务状态(RUNNING, FINISHED, FAILED) |
∟ progress | 100 | Integer | 查询进度(RUNNING时,此值为0-100之间) |
∟ resultStat | - | Object | 结果信息,状态为FINISHED时返回 |
∟ headers | ["#user_id"] | List | 列名列表 |
∟ rowCount | 11000 | Integer | 总行数 |
∟ pageCount | 1 | Integer | 总页数 |
错误响应示例
{
"return_code": -1008,
"return_message": "参数(token)为空"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | -1008 | Integer | 返回码 |
return_message | 参数(token)为空 | String | 返回信息 |
curl 示例
curl -X GET 'http://ta2:8992/open/sql-task-info?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&taskId=119a3a37411f3000'
# 下载结果分页数据
接口URL
/open/sql-result-page?token=xxx&taskId=119a3a37411f3000
请求方式
GET
Content-Type
application/json
请求Query参数
参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|---|
token | xxx | String | 是 | 查询密钥 |
taskId | 119a3a37411f3000 | String | 是 | 接口 执行查询语句 返回结果中的taskId |
pageId | 0 | Integer | 否 | 取值范围:[0, pageCount-1],默认为0 |
返回结果按行分隔,每行数据的格式为执行查询语句时指定的格式
[9324080,"c21756080","c40404080","2019-12-15 16:09:07.000","2019-12-15 16:09:07.000","user_set","2019-12-15 16:22:13.000",false,"2020-06-03 13:10:02.494",6,40000,"2019-12-15 16:09:07.000",0,null]
[9328294,"q21765894","q40422294","2019-12-15 16:19:49.000","2019-12-15 16:19:49.000","user_set","2019-12-15 16:42:18.000",false,"2020-06-03 13:10:02.494",17,642440,"2019-12-15 16:19:49.000",112,"2019-12-15 16:26:13.000"]
[9335719,"t21783319","t40454719","2019-12-15 16:29:45.000","2019-12-15 16:29:45.000","user_set","2019-12-15 16:42:18.000",false,"2020-06-03 13:10:02.494",6,70000,"2019-12-15 16:29:45.000",0,null]
错误响应示例
{
"return_code": -1008,
"return_message": "参数(token)为空"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | -1008 | Integer | 返回码 |
return_message | 参数(token)为空 | String | 返回信息 |
curl 示例
curl -X GET 'http://ta2:8992/open/sql-result-page?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&taskId=119a3a37411f3000'
# 取消未结束的任务
接口URL
/open/cancel-sql-task?token=xxx&taskId=119a3a37411f3000
请求方式
POST
Content-Type
application/json
请求Query参数
参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|---|
token | xxx | String | 是 | 查询密钥 |
taskId | 119a3a37411f3000 | String | 是 | 接口 执行查询语句 返回结果中的taskId |
成功响应示例
{
"return_code": 0,
"return_message": "success"
}
错误响应示例
{
"return_code": -1008,
"return_message": "参数(token)为空"
}
参数名 | 示例值 | 参数类型 | 参数描述 |
---|---|---|---|
return_code | -1008 | Integer | 返回码 |
return_message | 参数(token)为空 | String | 返回信息 |
curl 示例
curl -X POST 'http://ta2:8992/open/cancel-sql-task?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&taskId=119a3a37411f3000'