콘텐츠로 이동

DQL 데이터 질의¶

POST /api/v1/df/query_data_v1

개요¶

DQL 데이터 질의

Body 요청 파라미터¶

파라미터명	유형	필수	설명
queries	array		다중 명령 질의로, query 객체로 구성된 리스트 비어 있을 수 없음: False
fieldTagDescNeeded	boolean		field 또는 tag 설명 정보 필요 여부 비어 있을 수 없음: False

파라미터 추가 설명¶

질의 설명

응답 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	필수	설명
queries	array	Y	다중 명령 질의로, query 객체로 구성된 리스트
fieldTagDescNeeded	boolean		field 또는 tag 설명 정보 필요 여부

queries[*] 멤버 파라미터 구조 설명

파라미터명	type	필수	설명
qtype	string	Y	질의문 유형 dql: dql 유형 질의문 promql: PromQL 유형 질의문
query	json	Y	질의 구조
query.q	string		qtype과 일치하는 질의문 (예: dql 또는 promql 질의문)
query.ignore_cache	boolean		질의 시 캐시 사용 여부, 기본값은 false (캐시 사용)
query.promqlType	enum		qtype=promql일 때 적용, promql 질의 유형,可选 값 `instantQuery` 및 `rangeQuery`, 기본값은 `rangeQuery`
query.highlight	boolean		하이라이트 데이터 표시 여부
query.timeRange	array		시간 범위의 타임스탬프 리스트
query.disableMultipleField	bool		단일 컬럼 모드 활성화 여부, 기본값은 `true`
query.showLabel	bool		객체의 레이블 표시 여부, 기본값 없음
query.funcList	array		dql 반환값의 재집계 수식, 단 disableMultipleField=false일 때 해당 파라미터는 무효
query.slimit	integer		시계열 그룹 크기, 메트릭 질의에만 적용
query.soffset	integer		시계열 그룹 오프셋
query.limit	integer		페이지 크기
query.offset	integer		페이지 오프셋
query.orderby	array		정렬 리스트, `{fieldName:method}`, 단 메저먼트 질의의 정렬은 fieldName=time만 지원, method=["desc", "asc"]
query.sorderby	array		정렬 리스트, sorderby의 column은 표현식이며, 단일 값을 반환하는 모든 집계 함수(min, max, last, avg, p90, p95, count) 지원, `{fieldName:method}`, 구조는 orderby와 동일
query.order_by	array		정렬 리스트, 구조는 [{"column": "field", "order": "DESC"}], Doris 엔진 호환 필드
query.sorder_by	array		정렬 리스트, 구조는 [{"column": "field", "order": "DESC"}], Doris 엔진 호환 필드
query.density	string		응답 포인트 밀도, 우선순위는 autoDensity보다 낮고 dql 문에 설정된 밀도보다 높음
query.interval	number		시간 분할 간격, Kodo int64 범위 내에서 1ms 이상의 정수 밀리초만 허용, 기본 단위는 초, interval_unit으로 밀리초 지정 가능
query.interval_unit	string		interval의 단위, `s` 또는 `ms`可选, 기본값 `s`
query.search_after	array		페이지 질의 마커, 동일 파라미터로 이전 요청 응답 결과의 search_after 값을 현재 요청의 파라미터로 사용
query.maxPointCount	integer		최대 포인트 수
query.workspaceUUID	string		질의할 워크스페이스의 UUID, "*"는 모든 권한이 있는 워크스페이스 질의를 의미, 워크스페이스 참조 인터페이스 /wksp_share/granted_ws_list 확인 가능
query.workspaceUUIDs	array		질의할 워크스페이스의 UUID 리스트, 우선순위는 query.workspaceUUID보다 높음, ["*"]는 모든 권한이 있는 워크스페이스 질의를 의미, 워크스페이스 참조 인터페이스 /wksp_share/granted_ws_list 확인 가능
query.targetRegion	string		질의 워크스페이스가 ["*"]로 지정된 경우, 해당 필드는 필수
query.output_format	string		lineprotocol: 라인 프로토콜 출력, 기본값 미입력 시 기존 출력 형식 유지
query.cursor_time	integer		세그먼트 질의 임계값: 첫 번째 세그먼트 질의 시 cursor_time을 end_time으로 설정, 이후 세그먼트 질의 시 cursor_time을 응답의 next_cursor_time으로 설정
query.cursor_token	string		페이지 질의 토큰 (엔진에서 cursor_token 값 반환): 페이지 질의 시 이전 질의에서 반환된 next_cursor_token을 현재 질의의 cursor_token으로 설정, cursor_token이 없는 요청은 페이지 전환 시 동일 타임스탬프의 데이터가 건너뛰어질 수 있음
query.disable_sampling	bool		샘플링 비활성화 스위치, 기본값은 false
query.disable_truncate	bool		질의 결과 반환 내용 잘라내기 여부, 기본값 없음

응답 포인트 밀도 density 파라미터 값 설명

可选 값	설명
lower	낮음, 60포인트
low	낮음, 180포인트
medium	중간, 360포인트
high	높음, 720포인트

포인트 밀도 파라미터의 우선순위, 최대 밀도 density[high] * maxPointCount > interval > density > dql 문의 제어 파라미터
일반 질의 설명
미복구 이벤트 질의

참고: openapi 인터페이스로 데이터 질의 시 기본적으로 관리자 역할이 적용됩니다. 데이터 액세스 규칙 제한을 받을 수 있습니다.

요청 예시¶

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

응답¶

{
    "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"
}