DQL 데이터 쿼리(이전 버전)¶
POST /api/v1/df/query_data
GET /api/v1/df/query_data
개요¶
쿼리 배치 단위로 DQL 또는 PromQL 데이터를 조회합니다. 이 엔드포인트는 이전 버전 GET 및 POST 호출과 호환됩니다.
호출 전 및 사용 단계¶
GET은 JSON 객체를 URL 인코딩된 body에 넣고, POST는 JSON을 직접 제출할 수 있습니다. 이전 GET은 비어 있지 않은 queries_body를 우선 처리하며, 해당 경로에서만 최상위 search_after를 인식합니다. 기존 POST 단일 쿼리 형식에서는 최상위 qtype와 query를 사용할 수 있습니다. 새 클라이언트를 연결할 때는 쿼리 v1을 사용합니다.
예시의 메저먼트와 필드는 워크스페이스에서 수집된 데이터로 바꿔야 하며, 메저먼트 목록 및 메트릭 스키마에서 가져올 수 있습니다. 시간 범위는 데이터가 있는 시간 구간으로 바꿉니다. 응답을 파싱할 때는 warnings 또는 query_error를 항목별로 확인하고, 다음 페이지에서는 해당 항목의 자체 커서를 사용합니다.
요청 헤더¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 현재 워크스페이스의 OpenAPI Key입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 쿼리 권한이 있는 자격 증명을 가져옵니다. |
Query 요청 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| body | string | 조건부 필수 | 전체 쿼리 JSON 객체 문자열입니다. null 허용: False 예시: {"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}획득 또는 입력 방법: 쿼리 객체를 한 번 직렬화한 후 URL 인코딩합니다(예: curl --data-urlencode). |
| queries_body | string | 조건부 필수 | 비어 있지 않으면 body보다 우선하며, 이전 클라이언트와 호환됩니다. null 허용: False 예시: {"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}획득 또는 입력 방법: queries를 포함한 객체를 직렬화하고 curl --data-urlencode로 제출합니다. |
| search_after | string | queries_body 경로에서만 읽으며, 첫 조회에서는 생략합니다. null 허용: False 예시: [1785427200000,"cursor-example"]획득 또는 입력 방법: 동일한 쿼리의 이전 페이지에서 실제 반환된 배열을 JSON 직렬화하고 URL 인코딩합니다. |
매개변수 추가 설명¶
쿼리 설명
이 인터페이스는 이전 버전 호환 엔드포인트입니다. 새로 연결할 때는 POST /api/v1/df/query_data_v1 사용을 권장합니다. 이전 버전 GET은 계속 body=<URL 인코딩된 JSON>으로 매개변수를 전달하며, JSON을 이중 인코딩하지 마세요.
이 인터페이스는 POST와 GET을 모두 지원하며, 두 방식 모두 아래의 배치 쿼리 객체를 지원합니다:
- POST: 전체 매개변수를
application/jsonrequest body로 전달합니다. - GET: HTTP entity body를 사용하지 않고 query string에서
body=<전체 JSON object 문자열>로 전달하며, 클라이언트는body매개변수에 URL 인코딩을 적용해야 합니다. - 최상위는 반드시 JSON object여야 하며, 이중 JSON 인코딩된 string, array, null, number 또는 boolean은 허용되지 않습니다.
교차 워크스페이스/교차 사이트 쿼리 시 한 요청의 모든 queries[*]는 동일한 targetRegion만 가리킬 수 있습니다. 여러 사이트를 조회해야 할 때는 사이트별로 요청을 분할하고 클라이언트에서 결과를 병합해야 합니다. 대상 워크스페이스와 targetRegion은 /api/v1/wksp_share/granted_ws_list를 통해 가져와야 하며, 자세한 내용은 OpenAPI 교차 사이트 데이터 쿼리를 참고하세요.
응답 content.data[i].warnings[]에는 DQLDataAccessScopeRestricted가 포함될 수 있습니다:
details[0].metadata.namespace는 이번 버전에서logging으로 고정됩니다.details[0].metadata.restriction=partial은 권한이 있는 로그 인덱스의 데이터만 반환함을 의미합니다.details[0].metadata.restriction=all은 관련 로그 인덱스 모두 데이터 접근 권한이 없어 빈 결과를 반환함을 의미합니다.-
HTTP 상태 코드는 여전히 200이며, warning은 GuanceDB/Kodo의 기존 warning과 함께 존재합니다.
-
쿼리 문자열 요소 필드 설명
| 매개변수명 | type | 필수 | 설명 |
|---|---|---|---|
| body | string | queries_body와 택일 | 쿼리 요청 본문 |
| queries_body | string | body와 택일 | (호환 매개변수) queries 배열을 포함한 JSON 객체 문자열 |
| search_after | string | (호환 매개변수, queries_body에만 사용) 페이지네이션 데이터를 조회합니다. 첫 조회에서는 생략하고, 더 많은 페이지 데이터를 조회해야 할 때 이전 조회 결과의 search_after 필드를 추가하여 후속 데이터를 조회합니다. |
body와 호환 매개변수 queries_body는 모두 조건부 필수 매개변수이며, GET은 비어 있지 않고 유효한 JSON 객체를 하나 이상 제공해야 합니다. 동시에 제공하는 경우 비어 있지 않은 queries_body를 우선 사용합니다.
- 일반 배치 쿼리의 JSON 객체
| 매개변수명 | type | 필수 | 설명 |
|---|---|---|---|
| queries | array | Y | 다중 명령 쿼리이며, 내용은 query 객체로 구성된 목록입니다. |
| fieldTagDescNeeded | boolean | field 또는 tag 설명 정보가 필요한지 여부입니다. |
- queries[*] 멤버 매개변수 구조 설명
| 매개변수명 | type | 필수 | 설명 |
|---|---|---|---|
| qtype | string | 기본값은 dql입니다. 쿼리 문 유형입니다. dql: DQL 쿼리 문; promql: PromQL 쿼리 문. 예시 dql. |
|
| query | json | Y | 쿼리 구조입니다. 예시 {"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}. |
| query.q | string | qtype 유형과 일치하는 쿼리 문입니다(예: dql 또는 promql 쿼리 문). 예시 M::`cpu`:(`usage_idle`). 쿼리 도구에서 문을 복사하거나 메저먼트 스키마/로그 스키마의 필드 이름에 따라 작성합니다. |
|
| query.ignore_cache | boolean | 캐시를 비활성화할지 여부입니다. 기본값은 false이며 캐시 사용을 의미합니다. 예시 false. |
|
| query.disable_streaming_aggregation | boolean | 스트리밍 집계를 비활성화할지 여부입니다. 기본값은 false이며, 명시적으로 true를 전달하면 비활성화되고 명시적으로 false를 전달하면 사용을 허용합니다. 예시 false. |
|
| query.promqlType | enum | qtype=promql일 때 적용됩니다. 선택 가능한 값은 instantQuery, rangeQuery이며 기본값은 rangeQuery입니다. 예시 rangeQuery. |
|
| query.highlight | boolean | 하이라이트 데이터를 표시할지 여부입니다. 예시 false. |
|
| query.timeRange | array | 시간 범위의 타임스탬프 목록입니다. DQL / PromQL의 시작 및 종료 시간은 동일한 단위(초, 밀리초, 마이크로초 또는 나노초)를 사용해야 하며, 혼용 시 HTTP 400 ft.TimeRangeUnitMismatch를 반환합니다. 페이지네이션 커서는 독립적으로 유지됩니다. 예시 [1785427200000,1785430800000]. 필요한 쿼리 기간을 동일한 정밀도의 두 타임스탬프로 바꾸며, Unix 밀리초를 권장합니다. |
|
| query.disableMultipleField | bool | 단일 열 모드를 사용할지 여부입니다. 기본값은 true입니다. 예시 true. |
|
| query.showLabel | bool | 객체의 labels를 표시할지 여부입니다. 기본값은 false입니다. 예시 false. |
|
| query.funcList | array | DQL 반환값을 다시 집계하여 보정합니다. 선택한 집계 함수에 따라 처리합니다. 예시 ["last"]. |
|
| query.slimit | integer | 시계열 그룹 크기이며 메트릭 쿼리에만 유효합니다. 예시 10. |
|
| query.soffset | integer | 시계열 그룹 오프셋입니다. 예시 10. |
|
| query.limit | integer | 페이지 크기입니다. 예시 5. |
|
| query.offset | integer | 페이지 오프셋입니다. 예시 5. |
|
| query.orderby | array | 정렬 목록이며 구조는 {fieldName: method}입니다. 메저먼트 쿼리는 fieldName=time만 지원하며 method는 desc, asc를 선택할 수 있습니다. 예시 [{"time":"desc"}]. |
|
| query.density | string | 응답의 포인트 밀도입니다. 우선순위는 autoDensity보다 낮고 dql 문에 설정된 밀도보다 높습니다. 예시 medium. |
|
| query.interval | number | 시간 분할 간격입니다. Kodo int64 범위로 변환할 수 있고 1ms 이상인 정수 밀리초의 양수만 허용합니다. 기본 단위는 초이며 interval_unit을 통해 밀리초로 지정할 수 있습니다. 예시 60. |
|
| query.interval_unit | string | interval의 단위입니다. s, ms를 선택할 수 있으며 기본값은 s입니다. 예시 s. |
|
| query.search_after | array | 페이지네이션 마커로, 현재 인터페이스에서 반환된 페이지네이션 마커이며 다음 요청 시 전달합니다. 예시 [1785427200000,"cursor-example"]. 다음 페이지에서는 동일한 쿼리의 이전 조회에서 실제 반환된 배열을 복사해야 합니다. |
|
| query.maxPointCount | integer | 최대 포인트 수입니다. 예시 360. |
|
| query.workspaceUUID | string | 조회할 단일 권한 부여자 워크스페이스 UUID입니다. *는 targetRegion 내 모든 권한이 부여된 워크스페이스를 조회함을 의미합니다. 예시 wksp_example. |
|
| query.workspaceUUIDs | array | 조회할 권한 부여자 워크스페이스 UUID 목록입니다. 비어 있지 않으면 query.workspaceUUID보다 우선합니다. 동일한 목록은 반드시 같은 사이트에 속해야 합니다. ["*"]는 targetRegion 내 모든 권한이 부여된 워크스페이스를 조회함을 의미합니다. 두 필드를 동시에 전달하지 않는 것이 좋습니다. 예시 ["wksp_example"]. |
|
| query.targetRegion | string | 권한 부여자 워크스페이스가 속한 사이트의 regionCode입니다. /wksp_share/granted_ws_list에서 대상 workspaceUUID와 같은 그룹의 regionCode를 가져옵니다. 명시적으로 교차 사이트를 지정할 때는 권한 부여자의 regionCode를 전달하며, 와일드카드이고 생략된 경우 현재 사이트를 조회합니다. 예시 example-region. |
|
| query.output_format | string | lineprotocol: 라인 프로토콜 출력입니다. 기본적으로 입력하지 않으면 기존 출력 형식을 그대로 유지합니다. 예시 lineprotocol. |
|
| query.cursor_time | integer | 분할 쿼리 임계값입니다. 첫 번째 분할 쿼리 시 end_time으로 설정하고, 이후에는 응답의 next_cursor_time을 전달합니다. 예시 1785430800000. 다음 페이지에서는 응답의 next_cursor_time을 사용합니다. |
|
| query.cursor_token | string | 페이지네이션 쿼리 token(엔진에서 반환된 cursor_token 값)입니다. 페이지네이션 쿼리 시 이전 조회에서 반환된 next_cursor_token을 이번 조회의 cursor_token으로 설정해야 합니다. cursor_token이 없는 요청은 페이지 전환 시 동일한 타임스탬프의 데이터를 건너뛸 수 있습니다. 예시 cursor-example. 다음 페이지에서는 응답의 next_cursor_token을 사용합니다. |
|
| query.disable_sampling | bool | 샘플링 비활성화 스위치입니다. 기본값은 false입니다. 예시 false. |
|
| query.disable_truncate | bool | 반환 내용 잘림을 비활성화할지 여부입니다. 기본값은 false이며 잘림 허용을 의미합니다. 예시 false. |
- 응답 포인트 밀도
density매개변수 값 설명
| 선택 가능한 값 | 설명 |
|---|---|
| lower | 다소 낮음, 60개 포인트 |
| low | 낮음, 180개 포인트 |
| medium | 중간, 360개 포인트 |
| high | 높음, 720개 포인트 |
-
포인트 밀도 매개변수의 우선순위에 유의하세요. 최대 밀도
density[high]* interval은 density 및 DQL의 포인트 밀도 설정보다 우선합니다. maxPointCount는 추론된 포인트 수를 추가로 제한할 수 있습니다. -
일반적인 쿼리 설명
- OpenAPI 교차 사이트 데이터 쿼리
데이터 가시 범위는 API Key의 유효 권한, 워크스페이스 권한 부여 및 데이터 액세스 규칙에 따라 달라집니다.
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/df/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'body={"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'
이전 클라이언트에서 queries_body를 사용하는 예시
curl --get 'https://openapi.guance.com/api/v1/df/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'queries_body={"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'
응답¶
HTTP 200, application/json. 쿼리 항목별로 결과와 오류를 확인합니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.data | array<object> |
쿼리에서 반환된 배치 결과입니다. 쿼리 항목별로 파싱합니다. |
| content.data[].series | array<object> |
데이터 시리즈입니다. 데이터가 없거나 쿼리 항목이 실패하면 비어 있을 수 있습니다. |
| content.data[].series[].columns | array<string> |
시리즈의 열 이름입니다. |
| content.data[].series[].values | array | columns 순서로 정렬된 결과 행입니다. |
| content.data[].series[].name | string | 엔진 및 쿼리 유형에 따라 반환되는 시리즈 이름입니다. |
| content.data[].series[].units | array | columns 순서로 반환되는 단위이며, 요소는 문자열 또는 null일 수 있습니다. 필드는 생략할 수 있습니다. |
| content.data[].series[].tags | object | 태그별로 그룹화할 때 그룹 정보를 반환할 수 있습니다. |
| content.data[].column_names | array<string> |
일부 엔진은 열 이름을 별도로 제공합니다. |
| content.data[].complete | boolean | 엔진이 결과가 완전하다고 보고하는지 여부입니다. |
| content.data[].is_running | boolean | 쿼리 항목이 아직 실행 중인지 여부입니다. |
| content.data[].search_after | array | 이전 분할 페이지네이션 커서입니다. 동일한 쿼리의 다음 페이지에서만 사용합니다. |
| content.data[].next_cursor_time | integer | 새 커서 시간입니다. 음수 값은 더 이상 레코드가 없음을 의미합니다. |
| content.data[].next_cursor_token | string | 새 커서와 함께 사용하는 마커이며 비어 있을 수 있습니다. |
| content.data[].warnings | array<object> |
쿼리 경고입니다. 일부 인덱스가 제한된 경우에도 HTTP 200을 반환할 수 있습니다. |
| content.data[].query_error | object | 개별 쿼리 항목의 오류 객체이며 HTTP 200과 함께 나타날 수 있습니다. |
| content.data[].query_error.errorCode | string | 개별 항목 오류 식별자입니다. |
| content.data[].query_error.errorType | integer | 일반 DQL 쿼리 엔진에서 반환되는 오류 유형이며 실제 응답에 따라 제공됩니다. |
| content.data[].query_error.error | string | 일부 일반 DQL 오류에서 제공되는 텍스트입니다. |
| content.declaration | object 또는 null | 워크스페이스 선언입니다. |
{
"code": 200,
"content": {
"data": [
{
"column_names": [
"time",
"usage_idle"
],
"complete": true,
"is_running": false,
"series": [
{
"columns": [
"time",
"usage_idle"
],
"values": [
[
1785427260000,
91.5
]
]
}
]
}
],
"declaration": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 400 | ft.JsonFormatError | 이전 버전 호환 엔드포인트가 매개변수를 파싱할 수 없거나 JSON 객체에 쿼리 내용이 누락됨 | 일부 JSON 파일 형식이 잘못되었습니다. | GET은 URL 인코딩된 body를 전달하고, POST는 JSON 객체를 전달합니다. |
| 400 | ft.TimeRangeUnitMismatch | timeRange의 시작 및 종료 시간에 서로 다른 단위가 사용됨 | 시작 및 종료 시간 단위가 일치하지 않습니다. | 동일한 정밀도의 타임스탬프를 사용하도록 통일합니다. |
| 403 | ft.ForbiddenQuery | API Key에 대상 데이터를 쿼리할 권한이 없거나 대상 사이트가 권한 오류로 교차 사이트 쿼리를 거부함 | DQL 쿼리 권한이 없습니다. | 대상 워크스페이스 권한 부여와 대상 사이트를 확인합니다. |
| 406 | ft.InvalidParameter | interval 또는 interval_unit이 요구 사항을 충족하지 않음 | 매개변수가 유효하지 않습니다. | 단위가 s/ms인지 확인하고, 양의 정수 밀리초로 변환 가능해야 합니다. |
| 406 | ft.DqlParseError | DQL 쿼리 문을 파싱할 수 없음 | 쿼리 문 파싱에 실패했으며 상세 정보를 포함할 수 있습니다. | 먼저 쿼리 도구에서 구문을 검증합니다. |
| 406 | ft.UnsupportMultiSiteQuery | 배치 쿼리가 여러 사이트에 걸쳐 있음 | 다중 사이트 워크스페이스 쿼리는 지원되지 않습니다. | 사이트별로 각각 제출합니다. |
| 406 | ft.workspaceUnauthorized | 권한이 없는 워크스페이스를 명시적으로 요청함 | 메시지에 권한이 없는 워크스페이스가 표시됩니다. | 권한이 부여된 워크스페이스 목록에서 사용 가능한 식별자를 다시 가져옵니다. |
| 406 | ft.NotFoundWorkspaceAuthorizationCfg | 교차 사이트 쿼리에서 해당 권한 부여를 찾을 수 없음 | 워크스페이스 권한 부여 정보를 찾을 수 없습니다. | 사이트와 워크스페이스 간 공유 설정을 확인합니다. |
| 406 | ft.OpenapiDqlLoggingWildcardIndexForbidden | 인덱스 설정이 전체 인덱스 쿼리를 제한함 | 로그 인덱스를 명시적으로 지정하세요. | 로그 인덱스 목록에서 인덱스 이름을 가져옵니다. |
| 406 | ft.OpenapiDqlLoggingIndexLimitExceeded | 로그 인덱스 수가 설정 한도를 초과함 | 메시지에 한 번에 쿼리할 수 있는 인덱스 수가 포함됩니다. | 인덱스 범위를 줄입니다. |
| 503 | ft.QueryServiceUnavailable | 쿼리 서비스를 일시적으로 사용할 수 없음 | 쿼리 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하세요. | content.retryable 및 실제 상태에 따라 백오프 재시도합니다. |
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 매개변수를 전달함 | 요청 필드 검증에 실패했습니다. | 매개변수 표에 있는 쿼리 필드만 사용합니다. |