콘텐츠로 이동

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/json request 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를 우선 사용합니다.

  1. 일반 배치 쿼리의 JSON 객체
매개변수명 type 필수 설명
queries array Y 다중 명령 쿼리이며, 내용은 query 객체로 구성된 목록입니다.
fieldTagDescNeeded boolean field 또는 tag 설명 정보가 필요한지 여부입니다.
  1. 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.
  1. 응답 포인트 밀도 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 매개변수를 전달함 요청 필드 검증에 실패했습니다. 매개변수 표에 있는 쿼리 필드만 사용합니다.

문서 평가

이 페이지가 도움이 되었나요?