콘텐츠로 이동

DQL 데이터 조회


POST /api/v1/df/query_data_v1

개요

DQL 데이터 조회

Body 요청 매개변수

매개변수명 유형 필수 설명
queries array 다중 명령 조회로, query 객체로 구성된 목록입니다. 비즈니스 호출은 query를 하나 이상 전달해야 하며, 인터페이스는 현재 빈 배열 또는 생략을 허용하고 빈 데이터를 반환합니다.
비어 있음 허용: False
fieldTagDescNeeded boolean field 또는 tag 설명 정보가 필요한지 여부, 기본값 false
비어 있음 허용: False

매개변수 추가 설명

조회 설명

이 인터페이스는 POST와 GET을 모두 지원하며, 두 방식 모두 동일한 JSON object 매개변수 구조를 사용합니다.

  • POST: 전체 매개변수를 application/json request body로 전달합니다.
  • GET: HTTP entity body를 사용하지 않고 query string의 body=<전체 JSON object 문자열>을 통해 전달하며, 클라이언트는 body 매개변수를 URL 인코딩해야 합니다.
  • 최상위는 JSON object여야 하며, 이중 JSON 인코딩된 string, array, null, number 또는 boolean은 허용되지 않습니다.

응답의 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과 공존합니다.

선택적 매개변수의 기본값은 "호출자가 해당 매개변수를 생략한 경우"의 동작을 나타냅니다.

  • query.timeRange를 전달하지 않으면 Studio는 하위 시스템에 time_range: []를 전달하며, Studio 측에서 고정 시간 창을 보완하지 않고 DQL 문 내의 시간 범위를 덮어쓰지 않습니다. 현재 일반 DQL Select 메인 경로는 GuanceDB v1.52.0이 최근 30분을 대신 조회합니다. 이 값은 하위 구현에 속하며 모든 qtype, 모든 스토리지 엔진에 대한 통일된 OpenAPI 기본값이 아닙니다. PromQL 조회는 두 시점을 명시적으로 제공해야 합니다. 버전 간, 엔진 간 동작의 일관성을 보장하려면 [startTimeMs, endTimeMs] 형식의 밀리초 타임스탬프 두 개를 명시적으로 전달하는 것이 좋습니다.
  • query.limit, query.slimit, 정렬, 최대 포인트 수 및 조회 시간 상한은 DQL 문, 하위 서비스 구성 및 스토리지 엔진의 영향을 받으며, 통일된 OpenAPI 고정 기본값이 없습니다. 호출자가 안정적인 경계가 필요하면 명시적으로 전달해야 합니다.

워크스페이스 간/사이트 간 조회 제약:

  • 하나의 요청에 포함된 모든 queries[*]는 동일한 targetRegion만 가리킬 수 있습니다. 여러 사이트를 조회해야 하는 경우 사이트별로 요청을 분할하고 클라이언트에서 결과를 병합합니다.
  • 비어 있지 않은 workspaceUUIDs가 workspaceUUID보다 우선합니다. workspaceUUIDs가 빈 배열이거나 null이면 workspaceUUID로 대체됩니다. 두 필드를 동시에 전달하지 않는 것이 좋습니다. 현재 워크스페이스 조회에서는 둘 다 생략할 수 있으며, 권한이 부여된 워크스페이스를 명시적으로 조회할 때는 해당 워크스페이스가 속한 targetRegion도 함께 전달하는 것이 좋습니다.
  • workspaceUUIDs=["*"]인 경우 기본값이 없는 매개변수는 targetRegion입니다. 모든 권한이 부여된 워크스페이스를 조회할 때는 targetRegion을 명시적으로 전달해야 합니다. 호환 표기법인 workspaceUUID="*"도 계속 지원되며 동일한 규칙을 따릅니다.

  • 대상 워크스페이스와 targetRegion은 /api/v1/wksp_share/granted_ws_list를 통해 가져와야 합니다. 전체 예시는 다음을 참조하세요: OpenAPI 사이트 간 데이터 조회.

  • 매개변수 설명

매개변수명 type 필수 기본값 / 생략 시 동작 설명
queries array [](빈 데이터 반환) 다중 명령 조회로, query 객체로 구성된 목록입니다. 비즈니스 조회는 query를 하나 이상 전달해야 합니다.
fieldTagDescNeeded boolean false field 또는 tag 설명 정보가 필요한지 여부
  1. queries[*] 멤버 매개변수 구조 설명
매개변수명 type 필수 기본값 / 생략 시 동작 설명
qtype string dql 조회문 유형
dql: DQL 유형 조회문을 의미합니다.
promql: PromQL 유형 조회문을 의미합니다.
query json Y - 유효한 조회에 필수입니다. 누락되거나 query.q가 비어 있으면 유효한 하위 조회가 생성되지 않습니다.
query.q string 빈 문자열(일반적으로 유효한 조회가 생성되지 않음) qtype 유형과 일치하는 조회문(예: DQL 또는 PromQL 조회문)
query.ignore_cache boolean false 캐시 비활성화 여부. false는 캐시 사용을 의미합니다.
query.promqlType enum rangeQuery qtype=promql일 때 적용되며, 선택 값은 instantQuery, rangeQuery입니다.
query.highlight boolean false 하이라이트 데이터 표시 여부
query.timeRange array [] 외부 시간 범위. DQL에서 전달하지 않으면 문 내의 시간 창을 덮어쓰지 않으며, 현재 일반 Select 메인 경로는 GuanceDB가 최근 30분을 대신 조회합니다. PromQL은 두 시점을 명시적으로 전달해야 하며, 다른 엔진의 동작은 다를 수 있습니다. DQL/PromQL의 시작 및 종료 시간은 동일한 단위(초, 밀리초, 마이크로초 또는 나노초)를 사용해야 하며, 혼용 시 HTTP 400 ft.TimeRangeUnitMismatch가 반환됩니다. 페이지네이션 커서는 독립적으로 유지됩니다.
query.disableMultipleField bool true 단일 열 모드 활성화 여부
query.showLabel bool false 객체의 labels 표시 여부
query.funcList array [] DQL 반환 값을 다시 집계하여 수정합니다. disableMultipleField=false인 경우 현재 매개변수는 무효입니다.
query.slimit integer DQL / 하위 구성에 따라 결정 시계열 그룹 크기이며, 메트릭 조회에만 유효합니다.
query.soffset integer DQL의 값. DQL도 설정되지 않은 경우 추가 오프셋 없음 시계열 그룹 오프셋. 현재 파서는 양수 외부 값만 사용하여 DQL에 설정되지 않은 오프셋을 보완하며, 0은 DQL의 기존 값을 지우지 않습니다.
query.limit integer DQL / 하위 구성에 따라 결정 페이지네이션 크기
query.offset integer DQL의 값. DQL도 설정되지 않은 경우 추가 오프셋 없음 페이지네이션 오프셋. 현재 파서는 양수 외부 값만 사용하여 DQL에 설정되지 않은 오프셋을 보완하며, 0은 DQL의 기존 값을 지우지 않습니다.
query.orderby array DQL / 조회 엔진에 따라 결정 정렬 목록으로 구조는 {fieldName: method}입니다. 메저먼트 조회는 fieldName=time만 지원하며 method는 desc, asc를 선택할 수 있습니다.
query.sorderby array DQL / 조회 엔진에 따라 결정 정렬 목록. column은 단일 값을 반환하는 집계 함수(예: min, max, last, avg, p90, p95, count)를 지원합니다.
query.order_by array DQL / 조회 엔진에 따라 결정 Doris 엔진 호환 정렬 목록으로 구조는 [{"column": "field", "order": "DESC"}]입니다.
query.sorder_by array DQL / 조회 엔진에 따라 결정 Doris 엔진 호환 시계열 정렬 목록으로 구조는 [{"column": "field", "order": "DESC"}]입니다.
query.density string DQL / 조회 엔진에 따라 결정 응답 포인트 밀도로, DQL 문의 제어 매개변수보다 우선순위가 높습니다.
query.interval number DQL / 조회 엔진에 따라 결정 시간 분할 간격. Kodo int64 범위로 변환 가능하고 1ms 이상인 정수만 허용됩니다. 단위는 interval_unit으로 지정합니다.
query.interval_unit string s interval의 단위로 s, ms를 선택할 수 있습니다.
query.align_time boolean false 조회 엔진의 시간 그리드에 따라 시간 분할을 정렬할지 여부
query.tz string Asia/Shanghai 조회 시간대
query.search_after array 페이지네이션 마커 미설정 딥 페이지네이션 매개변수. 다음 요청에는 이전 응답의 search_after를 전달해야 합니다.
query.maxPointCount integer DQL / 조회 엔진에 따라 결정 최대 포인트 수
query.workspaceUUID string 현재 워크스페이스 조회할 단일 권한 부여자 워크스페이스 UUID. *는 targetRegion 내 모든 권한이 부여된 워크스페이스를 조회함을 의미합니다.
query.workspaceUUIDs array 미설정 조회할 권한 부여자 워크스페이스 UUID 목록. 비어 있지 않으면 query.workspaceUUID보다 우선합니다. 동일한 목록은 반드시 동일한 사이트에 속해야 합니다. ["*"]는 targetRegion 내 모든 권한이 부여된 워크스페이스를 조회함을 의미합니다. 두 필드를 동시에 전달하지 않는 것이 좋습니다.
query.targetRegion string 현재 워크스페이스 조회는 현재 사이트를 암시하며, 모든 권한이 부여된 워크스페이스 조회 시 기본값 없음 권한 부여자 워크스페이스가 속한 사이트의 regionCode. /wksp_share/granted_ws_list에서 대상 workspaceUUID와 같은 그룹의 regionCode로 가져옵니다. 명시적 사이트 간 조회 시 전달하는 것이 좋으며, 모든 권한이 부여된 워크스페이스 조회 시에는 반드시 명시적으로 전달해야 합니다. 호환 표기법인 workspaceUUID="*"도 동일한 규칙을 따릅니다.
query.output_format string 기존 JSON 응답 형식 lineprotocol로 설정하면 라인 프로토콜을 반환합니다.
query.cursor_time integer 커서 미설정 첫 번째 세그먼트 조회 시 end_time으로 설정하고, 이후에는 응답의 next_cursor_time을 전달합니다.
query.cursor_token string token 미설정 페이지네이션 시 이전 응답의 next_cursor_token을 전달합니다. 전달하지 않으면 동일한 타임스탬프의 데이터가 페이지를 넘길 때 건너뛸 수 있습니다.
query.disable_sampling bool false 샘플링 비활성화 여부
query.disable_truncate bool false 반환 내용 잘림 비활성화 여부. false는 잘림을 허용함을 의미합니다.
  1. 응답 포인트 밀도 density 매개변수 값 설명
선택 값 설명
lower 비교적 낮음, 60개 포인트
low 낮음, 180개 포인트
medium 중간, 360개 포인트
high 높음, 720개 포인트

  • 포인트 밀도 매개변수의 우선순위에 유의하세요. 최대 밀도 density[high] * maxPointCount > interval > density > dql 문의 제어 매개변수

  • 일반적인 조회 설명

  • 미복구 이벤트 조회

  • OpenAPI 사이트 간 데이터 조회

    참고: openapi 인터페이스로 데이터를 조회할 때 기본적으로 관리자 역할로 처리됩니다. 데이터 액세스 규칙의 제한을 받을 수 있으므로 유의하세요.

  • 요청 JSON 형식 오류

요청 본문이 유효한 JSON이 아닌 경우, 인터페이스는 조회 처리를 시작하기 전에 HTTP 400을 반환하며 errorCode는 공유 오류 코드인 ft.RequestJsonFormatError입니다. content.reason, content.line, content.column은 각각 JSON 파싱 사유, 줄 번호, 열 번호를 나타냅니다. 응답은 원본 요청 본문을 반환하지 않습니다.

{
  "code": 400,
  "content": {
    "reason": "Expecting property name enclosed in double quotes",
    "line": 22,
    "column": 17
  },
  "errorCode": "ft.RequestJsonFormatError",
  "message": "요청 JSON 형식 오류",
  "success": false,
  "traceId": "TRACE-..."
}

요청 예시

curl 'https://openapi.guance.com/api/v1/df/query_data_v1' \
-H 'Content-Type: application/json' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-raw $'{"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(avg(`usage_idle`))","_funcList":[],"funcList":[],"maxPointCount":720,"interval":10,"align_time":true,"sorder_by":[{"column":"`#1`","order":"DESC"}],"slimit":20,"disable_sampling":false,"timeRange":[1708911106000,1708912906999],"tz":"Asia/Shanghai"}}]}' \
--compressed

curl --get '<Endpoint>/api/v1/df/query_data_v1' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'body={"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(avg(`usage_idle`))"}}]}' \
--compressed

응답

{
    "code": 200,
    "content": {
        "data": [
            {
                "async_id": "",
                "column_names": [
                    "avg(usage_idle)"
                ],
                "complete": false,
                "cost": "14.815745ms",
                "index_name": "",
                "index_names": "",
                "index_store_type": "",
                "interval": 10000,
                "is_running": false,
                "max_point": 181,
                "next_cursor_time": -1,
                "points": null,
                "query_parse": {
                    "fields": {
                        "avg(usage_idle)": "usage_idle"
                    },
                    "funcs": {
                        "avg(usage_idle)": [
                            "avg"
                        ]
                    },
                    "namespace": "metric",
                    "sources": {
                        "cpu": "exact"
                    }
                },
                "query_type": "example_db",
                "sample": 1,
                "scan_completed": false,
                "scan_index": "",
                "series": [
                    {
                        "columns": [
                            "time",
                            "avg(usage_idle)"
                        ],
                        "name": "cpu",
                        "units": [
                            null,
                            null
                        ],
                        "values": [
                            [
                                1708912900000,
                                75.68748278863335
                            ],
                            [
                                1708912890000,
                                80.20737341208
                            ],
                            [
                                1708912880000,
                                73.23943236630001
                            ],
                            [
                                1708912870000,
                                71.08465385756001
                            ],
                            [
                                1708912860000,
                                75.12657005472002
                            ],
                            [
                                1708912850000,
                                84.19848645072001
                            ],
                            [
                                1708912840000,
                                81.59161169702
                            ],
                            [
                                1708912830000,
                                77.14274451154
                            ]
                        ]
                    }
                ],
                "window": 10000
            }
        ],
        "declaration": {
            "b": [
                "asfawfgajfasfafgafwba",
                "asfgahjfaf"
            ],
            "business": "aaa",
            "organization": "6540c09e4243b300077a9675"
        }
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "10888927517520616916"
}

문서 평가

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