데이터 커스텀 조회 API

최근 업데이트 2026. 10. 03.

쿼리 키를 생성한 후에는 커스텀 조회 API를 호출하여 프로젝트 데이터를 조회할 수 있습니다. 호출 방법은 Open API 문서의 설명을 참고하십시오.

1. 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	첫 행
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=YOUR_TOKEN' --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'

2. SQL 페이징 쿼리

SQL 페이징 쿼리 API에는 관련 메서드가 두 개 있습니다. 첫 번째 메서드는 쿼리 문을 실행하며, 실행이 끝나면 결과의 meta 정보와 페이지 정보를 반환합니다. 두 번째 메서드는 결과 페이지 데이터를 다운로드하는 데 사용합니다.

2. 쿼리 문 실행

인터페이스 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=YOUR_TOKEN' --header 'Content-Type: application/x-www-form-urlencoded' -d 'sql=select%20*%20from%20v_user_0%20limit%2011000&pageSize=10000&format=json&timeoutSeconds=10'

3. 결과 페이지 데이터 다운로드

인터페이스 URL

/open/sql-result-page?token=xxx&taskId=119a3a37411f3000&pageId=0

요청 방식

GET

Content-Type

application/json

요청 Query 파라미터

파라미터 이름	예시 값	파라미터 타입	필수 여부	파라미터 설명
token	xxx	String	예	조회 키
taskId	119a3a37411f3000	String	예	쿼리 문 실행 API에서 반환된 필드 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": "Baidu", "server_time": "2020-06-03 13:10:02.494", "distinct_id": "c40404080"}
{"app_version": "1.1", "channel": "Baidu", "server_time": "2020-06-03 13:10:02.494", "distinct_id": "q21765894"}
{"app_version": "1.1", "channel": "Baidu", "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=YOUR_TOKEN&taskId=119a3a37411f3000&pageId=1'

3. SQL 비동기 쿼리 API

SQL 비동기 쿼리 API에는 관련 메서드가 네 개 있습니다.

쿼리 문을 제출하고 쿼리 작업 ID를 반환합니다.
쿼리 작업의 실행 상태를 조회합니다.
쿼리 작업의 결과 데이터를 조회합니다.
종료되지 않은 작업을 취소합니다.

4. 쿼리 문 실행

인터페이스 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=YOUR_TOKEN' --header 'Content-Type: application/x-www-form-urlencoded' -d 'sql=select%20*%20from%20v_user_0%20limit%2011000&format=json'

5. 쿼리 작업 실행 상태 조회

인터페이스 URL

/open/sql-task-info?token=xxx&taskId=119a3a37411f3000

요청 방식

GET

Content-Type

application/json

요청 Query 파라미터

파라미터 이름	예시 값	파라미터 타입	필수 여부	파라미터 설명
token	xxx	String	예	조회 키
taskId	119a3a37411f3000	String	예	쿼리 문 실행 API가 반환한 결과의 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=YOUR_TOKEN&taskId=119a3a37411f3000'

6. 결과 페이지 데이터 다운로드

인터페이스 URL

/open/sql-result-page?token=xxx&taskId=119a3a37411f3000

요청 방식

GET

Content-Type

application/json

요청 Query 파라미터

파라미터 이름	예시 값	파라미터 타입	필수 여부	파라미터 설명
token	xxx	String	예	조회 키
taskId	119a3a37411f3000	String	예	쿼리 문 실행 API가 반환한 결과의 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=YOUR_TOKEN&taskId=119a3a37411f3000'

7. 종료되지 않은 작업 취소

인터페이스 URL

/open/cancel-sql-task?token=xxx&taskId=119a3a37411f3000

요청 방식

POST

Content-Type

application/json

요청 Query 파라미터

파라미터 이름	예시 값	파라미터 타입	필수 여부	파라미터 설명
token	xxx	String	예	조회 키
taskId	119a3a37411f3000	String	예	쿼리 문 실행 API가 반환한 결과의 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=YOUR_TOKEN&taskId=119a3a37411f3000'

이 문서가 도움이 되었나요?

1. SQL 쿼리​

1. SQL 쿼리​

2. SQL 페이징 쿼리​

2. 쿼리 문 실행​

3. 결과 페이지 데이터 다운로드​

3. SQL 비동기 쿼리 API​

4. 쿼리 문 실행​

5. 쿼리 작업 실행 상태 조회​

6. 결과 페이지 데이터 다운로드​

7. 종료되지 않은 작업 취소​

1. SQL 쿼리

1. SQL 쿼리

2. SQL 페이징 쿼리

2. 쿼리 문 실행

3. 결과 페이지 데이터 다운로드

3. SQL 비동기 쿼리 API

4. 쿼리 문 실행

5. 쿼리 작업 실행 상태 조회

6. 결과 페이지 데이터 다운로드

7. 종료되지 않은 작업 취소