menu
Is this helpful?

# 数据自定义查询 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 返回结果
data.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 返回数据
data.pageCount 2 Integer 结果数据的总页数
data.pageSize 10000 Integer 每页行数
data.rowCount 11000 Integer 结果数据的总行数
data.header ["#user_id"] List 首行字段列表
data.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 返回结果
data.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 返回结果
data.taskId 119a3a37411f3000 String 查询任务的 ID,用于后续下载结果分页数据
data.status FINISHED String 任务状态(RUNNING, FINISHED, FAILED)
data.progress 100 Integer 查询进度(RUNNING时,此值为0-100之间)
data.resultStat - Object 结果信息,状态为FINISHED时返回
data.resultStat.headers ["#user_id"] List 列名列表
data.resultStat.rowCount 11000 Integer 总行数
data.resultStat.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'