DQL 데이터 비동기 쿼리¶
POST /api/v1/df/asynchronous/query_data
GET /api/v1/df/asynchronous/query_data
개요¶
워크스페이스 비동기 데이터 쿼리를 제출하거나 폴링하며, 일반 DQL/PromQL 및 QueryHub 배치를 지원합니다.
호출 전 준비 및 사용 단계¶
현재 인터페이스는 freeEdition 유형의 워크스페이스를 지원하지 않으므로 먼저 워크스페이스 버전을 확인하세요. 일반 쿼리는 GET과 호환됩니다. POST와 동일한 전체 객체를 URL 인코딩된 body 파라미터에 넣습니다. QueryHub는 POST JSON만 지원합니다. 현재 워크스페이스에서 쿼리 권한이 있는 API Key를 사용하고, 항상 POST application/json을 사용하는 것이 좋습니다. 일반 메저먼트와 필드는 메저먼트 목록 및 메저먼트 스키마에서 가져오며, 쿼리 구문은 일반 쿼리 v1을 참고하세요. 처음에는 async_id를 전달하지 않습니다. 응답의 각 항목이 is_running=true이면 해당 항목에만 async_id를 그대로 다시 전달합니다. 일반 쿼리는 원래 query를 유지하며, QueryHub 폴링은 qtype=queryhub, uuid, async_id만 전달할 수 있습니다. 항목별로 처리하고 이미 완료된 항목은 다시 제출하지 않아 쿼리가 의도치 않게 다시 열리는 것을 방지하세요.
일반 쿼리는 먼저 동기적으로 대기한 후 비동기로 전환될 수 있습니다. 웨어하우스 대기 임계값은 기본 50초, 전체 검색 예산은 기본 2분이며 사이트에서 재정의할 수 있습니다. async_timeout은 전환 임계값을 조정하며, Front의 search_timeout 필드로 이 OpenAPI 예산을 변경할 수 없습니다. 외부 함수 쿼리는 짧게 캐시를 대기할 수 있으며 기본적으로 최대 10초 동안 0.5초마다 확인하므로 작업이 즉시 반환된다고 가정할 수 없습니다. 호스팅 outer_datasource 쿼리 채널은 OpenAPI에서 액세스가 거부되며, QueryHub는 별도 프로토콜을 사용합니다.
QueryHub를 사용하려면 관리자가 데이터 소스를 구성하고 활성화해야 하며, 쿼리 항목은 최대 20개, 전체 워크스페이스에서 활성 작업은 최대 20개입니다. pending은 등록되었을 뿐이며, 작업 전달에 실패하면 백그라운드 재전달을 기다릴 수 있습니다. 작업은 원래 워크스페이스와 원래 API Key에 바인딩되며 제출 시점부터 300초 후 만료되고, 폴링과 실행 완료로 만료가 연장되지 않습니다. is_running=true인 항목만 폴링하세요. QueryHub의 종료 상태에서는 async_id가 비워지며, 일반 실패 항목은 ID가 비어 있지 않더라도 폴링을 중지해야 합니다. HTTP 200과 success=true는 배치 반환 성공만 의미하며 각 항목의 쿼리 성공을 의미하지 않으므로 query_error/errorInfo, query_status, warnings를 반드시 확인해야 합니다.
비동기 쿼리 취소를 통해 현재 Key로 제출한 QueryHub 작업을 취소할 수 있습니다. 이 취소 진입점은 일반 DQL의 작업 ID를 허용하지 않습니다. 취소하면 취소로 표시하고 결과를 폐기하지만, 이미 실행 중인 하위 쿼리가 중단된다는 보장은 없습니다. 쿼리 결과의 커서는 동일한 쿼리의 데이터 이어보기에만 사용하며 비동기 작업 ID로 사용할 수 없습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| body | string | 일반 GET의 전체 JSON 객체 문자열입니다. QueryHub는 이 방식을 허용하지 않으며 POST JSON만 가능합니다. 예시: {"queries": [{"qtype": "dql", "async_timeout": "5s", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}}]}가져오기 또는 입력 방법: 일반 GET 쿼리에서만 사용합니다. 동일한 전체 JSON 객체를 한 번 직렬화한 후 URL 인코딩합니다(예: curl --data-urlencode). |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| queries[*] | object | 하나의 쿼리 항목이며 qtype이 프로토콜을 결정합니다. 예시: {"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000]}}가져오기 또는 입력 방법: 이 페이지의 일반 DQL 또는 QueryHub 예시에 따라 객체를 구성합니다. |
|
| queries[*].qtype | string | 일반 쿼리의 기본값은 dql이며 promql 및 구성된 외부 함수 유형도 지원합니다. QueryHub는 반드시 queryhub여야 하며 폴링에서도 유지해야 합니다. 예시: dql가져오기 또는 입력 방법: 실제 쿼리 언어에 따라 선택합니다. 호스팅 outer_datasource 채널은 이 OpenAPI에서 액세스가 거부되므로 Front 기능을 그대로 사용할 수 없습니다. |
|
| queries[*].uuid | string | QueryHub의 선택적 클라이언트 표시이며 응답에 그대로 반환됩니다. 작업 ID가 아니며 폴링에 사용하지 않습니다. 예시: cpu-query가져오기 또는 입력 방법: 호출자가 결과를 매칭할 수 있도록 안정적인 쿼리 항목 식별자를 생성합니다. |
|
| queries[*].async_id | string | 첫 쿼리에서는 생략하거나 빈 문자열로 둡니다. 폴링 중이며 여전히 실행 중인 동일한 항목에만 원래 응답 ID를 다시 전달합니다. QueryHub는 qhtask_ 접두사를 사용하며 일반 ID와 혼용할 수 없습니다. 예시: <async-id-from-response>가져오기 또는 입력 방법: 해당 항목 응답의 content.data[].async_id를 사용하며 원래 워크스페이스와 원래 API Key를 유지해야 합니다. |
|
| queries[*].async_timeout | string | 일반 쿼리가 동기 대기에서 비동기로 전환되는 대기 임계값입니다. 생략하면 사이트 기본값을 사용하며 웨어하우스 기본값은 50s입니다. 작업의 전체 실행 예산이 아니며 QueryHub는 이 필드를 사용하지 않습니다. 예시: 5s가져오기 또는 입력 방법: 호출 측의 대기 능력에 따라 단위가 포함된 기간을 선택합니다. 실제 지원 범위는 현재 쿼리 엔진에 따라 달라집니다. |
|
| queries[*].query | object | 일반 쿼리는 최초 제출과 폴링 모두 원래 쿼리 객체를 제공합니다. QueryHub는 최초 제출 시 필수이며 폴링에서는 생략할 수 있습니다. 두 프로토콜의 하위 필드는 다음과 같습니다. 예시: {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}가져오기 또는 입력 방법: 쿼리 문과 시간은 비즈니스 데이터 범위에서 결정하고 데이터 소스 ID는 관리자가 제공합니다. |
|
| queries[*].query.q | string | 일반 DQL/PromQL 문이며 일반 쿼리는 유효한 비어 있지 않은 문을 제공해야 합니다. 예시: M::`cpu`:(`usage_idle`)가져오기 또는 입력 방법: 메저먼트 목록 및 메저먼트 스키마에서 실제 메저먼트와 필드를 가져오고 쿼리 도구에서 먼저 문을 검증합니다. |
|
| queries[*].query.timeRange | array | 일반 쿼리의 시작 및 종료 시간입니다. Unix 밀리초 두 항목 배열을 통일적으로 사용하는 것이 좋으며 양 끝의 단위를 혼용할 수 없습니다. 예시: [1785427200000, 1785430800000]가져오기 또는 입력 방법: 비즈니스 이벤트 시간 또는 JavaScript Date.getTime()으로 쿼리 구간을 선택합니다. |
|
| queries[*].query.timeRange[*] | integer | 동일한 정밀도의 타임스탬프이며 Unix 밀리초를 권장합니다. 예시: 1785427200000가져오기 또는 입력 방법: 시작과 종료에 동일한 단위의 정수를 사용합니다. |
|
| queries[*].query.limit | integer | 일반 쿼리의 레코드 수 제한이며 정수로 변환됩니다. 각 엔진의 최종 최대 읽기 가능 행 수를 의미하지는 않습니다. 예시: 100가져오기 또는 입력 방법: 응답 본문 요구 사항에 따라 양의 정수를 선택하고 작은 배치부터 읽습니다. |
|
| queries[*].query.offset | integer | 일반 쿼리의 레코드 오프셋입니다. limit와 함께 사용하며 백엔드 지원 여부는 쿼리에 따라 달라집니다. 예시: 0가져오기 또는 입력 방법: 이전에 읽은 레코드 수에 따라 입력하며 첫 페이지는 0입니다. |
|
| queries[*].query.slimit | integer | 일반 쿼리의 시리즈 수 제한입니다. 예시: 10가져오기 또는 입력 방법: 집계 그룹이 너무 많을 때 필요한 시리즈 수를 선택합니다. |
|
| queries[*].query.soffset | integer | 일반 쿼리의 시리즈 오프셋입니다. 예시: 0가져오기 또는 입력 방법: 이전에 읽은 시리즈 수에 따라 입력합니다. |
|
| queries[*].query.tz | string | 일반 쿼리의 IANA 시간대이며 기본값은 Asia/Shanghai이고 시간 분할/정렬에 사용됩니다. 예시: Asia/Shanghai가져오기 또는 입력 방법: 비즈니스의 실제 시간대 식별자를 사용합니다. |
|
| queries[*].query.interval | number | 일반 쿼리의 시간 분할 값입니다. 정확히 양의 정수 밀리초로 환산할 수 있어야 합니다. 60s와 같은 단위 포함 문자열은 지원하지 않습니다. 예시: 60가져오기 또는 입력 방법: 필요한 분할 단위에 따라 숫자를 입력하고 interval_unit으로 s/ms를 지정합니다. |
|
| queries[*].query.interval_unit | string | 분할 단위이며 s 또는 ms만 가능하고 기본값은 s입니다. 예시: s가져오기 또는 입력 방법: 초는 s, 밀리초는 ms를 입력합니다. |
|
| queries[*].query.align_time | boolean | 일반 쿼리의 분할 시작 시간 정렬 스위치입니다. 생략하면 엔진 기본 동작을 따릅니다. 예시: false가져오기 또는 입력 방법: 시간대에 맞춰 집계 경계를 정렬해야 할 때 사용합니다. |
|
| queries[*].query.density | string | 일반 쿼리의 포인트 밀도 이름이며 사이트 구성에 의해 정의됩니다. 웨어하우스 기본값은 lower/low/medium/high에 대해 각각 60/180/360/720입니다. 예시: medium가져오기 또는 입력 방법: interval 또는 maxPointCount로 명시적으로 제어하는 것을 우선하며, density 사용 전에 사이트 지원 값을 확인합니다. |
|
| queries[*].query.maxPointCount | integer | 일반 쿼리의 최대 포인트 수입니다. interval로 계산한 포인트 수와 동시에 존재하면 더 작은 값을 사용합니다. 예시: 360가져오기 또는 입력 방법: 차트에 표시 가능한 포인트 수에 따라 양의 정수를 선택합니다. |
|
| queries[*].query.workspaceUUID | string | 일반 쿼리의 단일 승인 대상 워크스페이스입니다. 전달하지 않으면 현재 워크스페이스를 사용합니다. QueryHub에서는 금지됩니다. 예시: wksp_target가져오기 또는 입력 방법: 워크스페이스 공유 승인 구성에서 실제 대상 워크스페이스 UUID를 가져옵니다. |
|
| queries[*].query.workspaceUUIDs | array<string> |
일반 쿼리의 여러 승인 대상 워크스페이스이며 단일 workspaceUUID보다 우선합니다. QueryHub에서는 금지됩니다. 예시: ["wksp_target"]가져오기 또는 입력 방법: 워크스페이스 공유 승인 구성에서 동일 사이트의 워크스페이스 목록을 가져옵니다. |
|
| queries[*].query.workspaceUUIDs[*] | string | 승인된 워크스페이스 UUID 하나입니다. 예시: wksp_target가져오기 또는 입력 방법: 승인된 워크스페이스 정보에서 복사하며 표시 이름은 사용하지 않습니다. |
|
| queries[*].query.targetRegion | string | 일반 크로스 워크스페이스 쿼리의 대상 사이트입니다. 전체 배치는 하나의 사이트만 지원합니다. QueryHub에서는 금지됩니다. 예시: <authorized-site-code>가져오기 또는 입력 방법: 사이트 간 승인 구성에서 사이트 코드를 제공하며 도메인 이름으로 추측할 수 없습니다. |
|
| queries[*].query.indexes | array<string> |
일반 로그 쿼리의 인덱스 이름 배열이며 현재 Key와 인덱스 제한을 충족해야 합니다. 예시: ["default"]가져오기 또는 입력 방법: 현재 워크스페이스의 로그 인덱스 구성에서 이미 존재하는 이름을 읽습니다. |
|
| queries[*].query.indexes[*] | string | 실제 로그 인덱스 이름 하나입니다. 예시: default가져오기 또는 입력 방법: 구성된 인덱스 이름을 복사합니다. |
|
| queries[*].query.conditions | string | 일반 쿼리의 추가 WHERE 조건이며 filter 조건과 AND로 결합됩니다. 이스케이프되지 않은 외부 입력을 넣을 수 없습니다. 예시: env = 'production'가져오기 또는 입력 방법: 실제 필드에 따라 쿼리 언어에 맞는 조건 표현식을 구성합니다. |
|
| queries[*].query.filter | object | 일반 쿼리에附加 태그/필드 조건이며 두 배열이 병합되어 조건 포맷에 들어갑니다. 예시: {"tags": [], "fields": []}가져오기 또는 입력 방법: 복잡한 필터링은 검증된 q 또는 conditions에 직접 작성할 수 있습니다. |
|
| queries[*].query.filter.tags | array<object> |
태그 필터 조건 배열입니다. 예시: []가져오기 또는 입력 방법: 이 페이지의 조건 객체 구조를 사용하여 실제 태그 이름에 따라 구성합니다. |
|
| queries[*].query.filter.fields | array<object> |
필드 필터 조건 배열입니다. 예시: []가져오기 또는 입력 방법: 이 페이지의 조건 객체 구조를 사용하여 실제 필드 이름에 따라 구성합니다. |
|
| queries[*].query.search_after | array | 일반 쿼리의 이전 세그먼트 페이지 커서이며 원래 쿼리의 이어보기에만 사용합니다. 예시: []가져오기 또는 입력 방법: 해당 항목 응답의 search_after를 그대로 복사하며 반환되지 않으면 생략합니다. |
|
| queries[*].query.cursor_time | integer | 일반 세그먼트 쿼리의 다음 세그먼트 시작 시간이며 cursor_token과 쌍으로 이어가야 합니다. 예시: 1785430800000가져오기 또는 입력 방법: 해당 항목 응답의 next_cursor_time을 사용하며 음수 값은 더 이상 레코드가 없음을 의미합니다. |
|
| queries[*].query.cursor_token | string | 일반 세그먼트 페이지 표시이며 동일 시간 레코드가 건너뛰어지는 것을 방지합니다. 예시: <next-cursor-token>가져오기 또는 입력 방법: 해당 항목 응답의 next_cursor_token을 그대로 복사하고 원래 필터와 정렬을 유지합니다. |
|
| queries[*].query.disable_sampling | boolean | 일반 쿼리의 세그먼트 비활성화 스위치이며 true이면 cursor_time이 적용되지 않습니다. 예시: false가져오기 또는 입력 방법: 일반적으로 생략하며 세그먼트를 명확히 비활성화해야 할 때만 true로 설정합니다. |
|
| queries[*].query.disable_streaming_aggregation | boolean | 일반 쿼리의 스트리밍 집계 비활성화이며 기본값은 false입니다. 실제 엔진과 컨텍스트가 재정의할 수 있습니다. 예시: false가져오기 또는 입력 방법: 일반적으로 기본값을 유지하며 문제를 진단하거나 전체 집계가 명확히 필요할 때 선택합니다. |
|
| queries[*].query.ignore_cache | boolean | 일반 쿼리에서 쿼리 캐시를 무시하는 엔진 전달 스위치입니다. 예시: false가져오기 또는 입력 방법: 하위 데이터를 다시 쿼리해야 할 때 사이트 엔진 기능에 따라 사용합니다. |
|
| queries[*].query.disable_truncate | boolean | 일반 쿼리에서 반환 잘림을 비활성화하는 엔진 전달 스위치입니다. 백엔드 리소스 제한을 우회하지는 않습니다. 예시: false가져오기 또는 입력 방법: 일반적으로 생략하며 전체 결과가 확실히 필요하면 먼저 데이터 양과 엔진 지원을 확인합니다. |
|
| queries[*].query.disable_var_expansion | boolean | ScopeDB 쿼리 경로에서만 계속 전달되는 변수 확장 비활성화 스위치입니다. 예시: false가져오기 또는 입력 방법: 이미 명확한 ScopeDB 구성이 필요할 때만 제공하며 다른 엔진에서는 생략합니다. |
|
| queries[*].query.enable_preflight_estimate | boolean | 일반 쿼리의 사전 검사 추정 스위치이며 엔진에 직접 전달됩니다. 예시: false가져오기 또는 입력 방법: 대상 엔진이 지원하고 추정이 필요할 때만 제공합니다. |
|
| queries[*].query.disallow_large_query | boolean | 일반 고소모 쿼리 제한 스위치이며 기본값은 false입니다. 예시: false가져오기 또는 입력 방법: 엔진이 고소모 요청을 거부하도록 하려면 사용하며 실제 판정은 사이트 엔진 규칙을 따릅니다. |
|
| queries[*].query.scan_completed | boolean | 일반 인덱스 배치 스캔 진행 표시이며 기본값은 false입니다. 예시: false가져오기 또는 입력 방법: 엔진이 배치 스캔 상태를 반환할 때만 원래 반환값에 따라 이어서 쿼리합니다. |
|
| queries[*].query.scan_index | string | 일반 인덱스 배치 스캔 위치 표시이며 기본값은 빈 문자열입니다. 예시: <scan-index>가져오기 또는 입력 방법: 동일한 쿼리 엔진이 반환한 표시만 사용하며 첫 쿼리에서는 생략합니다. |
|
| queries[*].query.promqlType | string | 일반 qtype=promql의 하위 유형은 instantQuery 또는 rangeQuery이며 일반 PromQL 엔진에 전달됩니다. QueryHub native.operation과 다릅니다. 예시: rangeQuery가져오기 또는 입력 방법: 실제 PromQL 쿼리에서 사용하는 인스턴트/레인지 방식에 따라 구성합니다. |
|
| queries[*].query.output_format | string | 일반 쿼리에서 엔진이 지원하는 출력 형태를 요청할 수 있습니다. lineprotocol은 일반 결과 변환을 건너뛰며 series 구조를 보장하지 않습니다. 예시: lineprotocol가져오기 또는 입력 방법: 일반 클라이언트는 생략하고 통합 series 반환을 사용하는 것이 좋습니다. |
|
| queries[*].query.funcList | array | 일반 쿼리 결과의 후처리 함수 목록이며 최종 구조에 영향을 줍니다. 예시: []가져오기 또는 입력 방법: 일반적으로 생략합니다. 검증된 결과 변환 구성만 재사용할 수 있으며 DQL 문 함수 목록이 아닙니다. |
|
| queries[*].query.needclearnone | boolean | 일반 결과 변환 시 빈 값을 정리할지 여부이며 기본값은 true입니다. 예시: true가져오기 또는 입력 방법: 엔진의 빈 값을 유지하려면 false로 설정할 수 있으며 최종 구조는 결과 변환에 따라 달라집니다. |
|
| queries[*].query.filter.tags[*] | object | 하나의 필터 조건입니다. filters/condition으로 중첩 조건을 구성할 수도 있습니다. 예시: {"name": "env", "operation": "=", "value": ["production"], "condition": "and"}가져오기 또는 입력 방법: 실제 태그 또는 필드에서 이름과 값을 선택합니다. |
|
| queries[*].query.filter.tags[*].name | string | 필드 또는 태그 이름입니다. 예시: env가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.tags[*].operation | string | 비교 연산자이며 =, !=, in, not in, match 등이 있고 대상 DQL 지원 여부를 따릅니다. 예시: =가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.tags[*].value | array | 비교에 참여하는 값 배열입니다. 예시: ["production"]가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.tags[*].condition | string | 동일 그룹의 다른 조건과 연결하는 논리이며 and/or를 권장합니다. 예시: and가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.tags[*].filters | array<object> |
선택적 중첩 조건 배열이며 각 항목은 동일한 조건 객체를 재사용합니다. 예시: []가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.fields[*] | object | 하나의 필터 조건입니다. filters/condition으로 중첩 조건을 구성할 수도 있습니다. 예시: {"name": "env", "operation": "=", "value": ["production"], "condition": "and"}가져오기 또는 입력 방법: 실제 태그 또는 필드에서 이름과 값을 선택합니다. |
|
| queries[*].query.filter.fields[*].name | string | 필드 또는 태그 이름입니다. 예시: env가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.fields[*].operation | string | 비교 연산자이며 =, !=, in, not in, match 등이 있고 대상 DQL 지원 여부를 따릅니다. 예시: =가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.fields[*].value | array | 비교에 참여하는 값 배열입니다. 예시: ["production"]가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.fields[*].condition | string | 동일 그룹의 다른 조건과 연결하는 논리이며 and/or를 권장합니다. 예시: and가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.filter.fields[*].filters | array<object> |
선택적 중첩 조건 배열이며 각 항목은 동일한 조건 객체를 재사용합니다. 예시: []가져오기 또는 입력 방법: 실제 필터링 요구에 따라 입력하고 소량의 데이터로 먼저 검증합니다. |
|
| queries[*].query.datasourceId | string | 활성화된 QueryHub 데이터 소스 식별자이며 연결 문자열이나 워크스페이스 UUID가 아닙니다. 총 길이는 1~128자이고 영문 또는 숫자로 시작하며 이후에는 영문, 숫자, 점, 밑줄, 하이픈만 가능합니다. 예시: ds_example가져오기 또는 입력 방법: 워크스페이스 데이터 소스 관리자가 데이터 소스 상세에서 제공합니다. |
|
| queries[*].query.mode | string | native는 하위 쿼리 언어를 사용하고 dql은 QueryHub DQL을 사용합니다. 최초 제출 시 반드시 선택해야 하며 두 페이로드를 함께 전달할 수 없습니다. 예시: native가져오기 또는 입력 방법: 대상 데이터 소스에서 활성화된 기능에 따라 native 또는 dql을 선택합니다. |
|
| queries[*].query.expectedRevision | integer | 선택적 구성 버전이며 1~2^64-1입니다. 일치하지 않으면 거부되어 이전 연결 구성으로 쿼리하는 것을 방지합니다. 예시: 1가져오기 또는 입력 방법: 저장된 데이터 소스 구성의 revision에서 가져오며 임의로 증가시키지 마세요. |
|
| queries[*].query.native | object | mode=native일 때 필수입니다. language에 따라 아래 표에서 해당하는 필드만 제출합니다. 예시: {"language": "sql", "statement": "SELECT 1 AS value", "parameters": []}가져오기 또는 입력 방법: 수신 데이터베이스/엔진이 지원하는 읽기 전용 네이티브 쿼리를 사용합니다. |
|
| queries[*].query.native.language | string | sql은 MySQL/Postgres, promql은 Prometheus, elasticsearch는 ES, mongodb는 MongoDB에 사용하며 데이터 소스와 일치해야 합니다. 예시: sql가져오기 또는 입력 방법: 구성된 데이터 소스 유형에 따라 선택합니다. |
|
| queries[*].query.native.statement | string | SQL 또는 PromQL 문이며 비어 있지 않고 최대 16384자입니다. ES/Mongo는 이 필드를 사용하지 않습니다. 예시: SELECT 1 AS value가져오기 또는 입력 방법: 검증된 비즈니스 쿼리에서 구성하고 값 파라미터는 문과 분리합니다. |
|
| queries[*].query.native.parameters | array | SQL 전용입니다. 최대 128개의 스칼라 바인딩 값이며 전체 JSON은 최대 32768바이트입니다. string/number/boolean/null을 지원하고 중첩 객체는 지원하지 않습니다. 예시: []가져오기 또는 입력 방법: SQL 자리 표시자 순서에 따라 비즈니스 입력 값을 제공하며 자리 표시자 구문은 대상 데이터 소스를 따릅니다. |
|
| queries[*].query.native.parameters[*] | JSON 스칼라 | SQL 단일 바인딩 값입니다. 예시: production가져오기 또는 입력 방법: 해당 비즈니스 입력을 사용하고 SQL 문자열에 이어 붙이지 않습니다. |
|
| queries[*].query.native.operation | string | Prometheus는 query/query_range, ES는 search, Mongo는 find/count이며 SQL은 전달하지 않습니다. 예시: query_range가져오기 또는 입력 방법: 선택한 language에 따라 지원되는 작업을 선택합니다. |
|
| queries[*].query.native.arguments | object | PromQL/ES/Mongo 작업 파라미터이며 language 및 operation에 따라 선택합니다. JSON은 최대 32768바이트입니다. 예시: {"start": 1785427200, "end": 1785430800, "step": "60s"}가져오기 또는 입력 방법: 아래 각 필드의 적용 조건에 따라 제공합니다. |
|
| queries[*].query.native.arguments.time | number 또는 string | PromQL query에서만 선택적으로 사용하는 평가 시각이며 엔진 시간 문자열 또는 Unix 초를 지원합니다. 예시: 1785427200가져오기 또는 입력 방법: 비즈니스에 필요한 인스턴트 시각에서 가져오며 밀리초를 초로 직접 전달할 수 없습니다. |
|
| queries[*].query.native.arguments.start | number 또는 string | PromQL query_range의 필수 시작 시간이며 Unix 초 또는 엔진 시간 문자열입니다. 예시: 1785427200가져오기 또는 입력 방법: 비즈니스 쿼리 시작 시각을 선택합니다. |
|
| queries[*].query.native.arguments.end | number 또는 string | PromQL query_range의 필수 종료 시간이며 Unix 초 또는 엔진 시간 문자열입니다. 예시: 1785430800가져오기 또는 입력 방법: 비즈니스 쿼리 종료 시각을 선택하며 엔진 요구 사항에 따라 시작보다 늦어야 합니다. |
|
| queries[*].query.native.arguments.step | number 또는 string | PromQL query_range의 필수 스텝입니다. 숫자는 양수여야 하며 문자열은 엔진 기간 형식을 사용합니다. 예시: 60s가져오기 또는 입력 방법: 결과 샘플링 밀도에 따라 초 수 또는 단위가 포함된 기간을 선택합니다. |
|
| queries[*].query.native.arguments.body | object | ES search의 필수 쿼리 DSL 객체이며 pit 필드를 포함할 수 없습니다. 예시: {"query": {"match_all": {}}, "size": 5}가져오기 또는 입력 방법: 대상 인덱스에서 검증한 ES 쿼리 DSL입니다. |
|
| queries[*].query.native.arguments.body.动态字段 | JSON 값 | 대상 ES가 지원하는 쿼리 DSL 필드입니다. 구체적인 구문은 데이터 소스 엔진에서 정의하며 Studio는 고정 하위 필드 표를 제공하지 않습니다. 예시: {"match_all": {}}가져오기 또는 입력 방법: 대상 ES 버전의 네이티브 DSL에 따라 구성합니다. |
|
| queries[*].query.native.arguments.filter | object | Mongo find/count의 선택적 필터 문서입니다. 예시: {"env": "production"}가져오기 또는 입력 방법: 컬렉션의 실제 필드에 따라 Mongo 필터를 구성합니다. |
|
| queries[*].query.native.arguments.projection | object | Mongo find에서만 선택적으로 사용하는 필드 프로젝션입니다. 예시: {"_id": 0, "env": 1}가져오기 또는 입력 방법: 반환할 필드에 따라 Mongo 프로젝션 문서를 구성합니다. |
|
| queries[*].query.native.arguments.sort | object | Mongo find에서만 선택적으로 사용하는 정렬입니다. JSON 키 순서가 정렬 우선순위입니다. 예시: {"time": -1}가져오기 또는 입력 방법: 필요한 정렬 우선순위에 따라 필드 순서가 있는 객체를 구성합니다. |
|
| queries[*].query.native.arguments.skip | integer | Mongo find에서만 사용하는 건너뛸 수이며 음수가 아닌 정수입니다. 예시: 0가져오기 또는 입력 방법: 이전에 읽은 수에 따라 설정합니다. |
|
| queries[*].query.native.arguments.limit | integer | Mongo find에서만 사용하는 수 제한이며 음수가 아닌 정수입니다. 실제 0의 의미는 하위 엔진에서 결정합니다. 예시: 5가져오기 또는 입력 방법: 작은 양의 정수를 명시적으로 지정하는 것이 좋습니다. |
|
| queries[*].query.dql | object | mode=dql일 때만 필수이며 QueryHub DQL 객체이고 일반 query.q와 동일하지 않습니다. 예시: {"dqlVersion": "queryhub/v1", "dql": "queryhub(source=\"mysql\", datasource=\"orders\")::orders:(id) {status = $status}", "parameters": {"status": "paid"}}가져오기 또는 입력 방법: 데이터 소스가 이미 지원하는 QueryHub DQL 구문과 테이블 이름을 사용하고 먼저 기능을 검증합니다. |
|
| queries[*].query.dql.dqlVersion | string | QueryHub DQL 프로토콜 버전이며 생략하면 기본값 queryhub/v1이고 이 값만 지원합니다. 예시: queryhub/v1가져오기 또는 입력 방법: queryhub/v1을 고정적으로 사용합니다. |
|
| queries[*].query.dql.dql | string | 비어 있지 않은 QueryHub DQL 문이며 최대 16384자입니다. 예시: queryhub(source="mysql", datasource="orders")::orders:(id) {status = $status}가져오기 또는 입력 방법: 검증된 QueryHub 데이터 소스 쿼리에서 가져오며 모든 일반 DQL 구문을 사용할 수 있다고 가정할 수 없습니다. |
|
| queries[*].query.dql.parameters | object | 최대 128개의 파라미터 이름이 있으며 이름은 비어 있지 않고 최대 128자입니다. 값은 스칼라 또는 비어 있지 않은 스칼라 배열이며 전체 JSON은 최대 32768바이트입니다. 예시: {"env": "production"}가져오기 또는 입력 방법: 문의 파라미터 이름에 따라 비즈니스 값을 제공합니다. |
|
| queries[*].query.dql.parameters.动态参数名 | JSON 스칼라 또는 스칼라 배열 | 하나의 명명된 파라미터 값이며 중첩 객체나 빈 배열은 지원하지 않습니다. 예시: production가져오기 또는 입력 방법: 문에서 실제 파라미터 이름을 사용하여 동적 키를 대체합니다. |
|
| queries[*].query.showLabel | boolean | 일반 쿼리의 태그 표시 스위치이며 쿼리 엔진에 전달됩니다. 생략하면 엔진 기본값을 유지합니다. 예시: true가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.disable_slimit | boolean | 일반 쿼리의 시리즈 수 제한 비활성화 전달 스위치이며 사이트 리소스 한도를 우회한다는 의미는 아닙니다. 예시: false가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.is_optimized | boolean | 일반 쿼리 최적화 스위치이며 대상 쿼리 엔진에 직접 전달되고 보통 생략합니다. 예시: true가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.skipTracingDataQueryRule | boolean | 트레이스 쿼리의 데이터 쿼리 규칙 제어 표시입니다. 권한 검사를 우회하는 방식으로 사용하지 않으며 일반 호출에서는 생략합니다. 예시: false가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.highlight | JSON 값 | 일반 쿼리의 하이라이트 제어입니다. Studio는 원래 값을 유지하며 구체적인 유형과 효과는 대상 엔진 지원에 따라 결정되고 보통 생략합니다. 예시: true가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.sls_query | JSON 값 | SLS 쿼리 전용 구성이며 그대로 전달합니다. 이미 SLS 쿼리 템플릿이 있을 때만 템플릿에 따라 제공하며 다른 엔진에는 사용하지 않습니다. 예시: {}가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.orderby | JSON 값 | 일반 쿼리 레코드 정렬의 이전 필드이며 Studio는 비어 있지 않은 값을 그대로 전달합니다. 검증된 q 문에서 직접 정렬을 지정하는 것이 좋으며 기존 클라이언트는 원래 형식을 유지합니다. 예시: []가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.sorderby | JSON 값 | 일반 쿼리 시리즈 정렬의 이전 필드이며 비어 있지 않은 값을 그대로 전달합니다. 기존 쿼리 템플릿이 있을 때만 제공합니다. 예시: []가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.order_by | array | 일반 Doris 호환 정렬 배열이며 요소는 {column:필드 이름,order:DESC 또는 ASC} 형식입니다. 기존 엔진에 다른 정렬 프로토콜이 있으면 검증된 형식을 유지하세요. 예시: [{"column": "time", "order": "DESC"}]가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.sorder_by | array | 일반 Doris 호환 정렬 배열이며 요소는 {column:필드 이름,order:DESC 또는 ASC} 형식입니다. 기존 엔진에 다른 정렬 프로토콜이 있으면 검증된 형식을 유지하세요. 예시: [{"column": "time", "order": "DESC"}]가져오기 또는 입력 방법: 현재 엔진/기존 호출자에서 검증된 해당 구성만 재사용하고 서로 다른 엔진 구조를 혼용하지 않습니다. |
|
| queries[*].query.appScopes | array<object> |
명시적 RUM 애플리케이션 범위이며 비어 있지 않은 배열입니다. 각 워크스페이스는 한 번만 나타나야 하며 이번 승인 워크스페이스 범위에 있어야 합니다. 이 필드를 포함하면 workspaceUUID와 workspaceUUIDs를 동시에 제공할 수 없습니다. 예시: [{"workspaceUUID": "wksp_example", "appIds": ["app_example"]}]가져오기 또는 입력 방법: RUM 애플리케이션 구성에서 워크스페이스 UUID와 애플리케이션 ID를 가져오며 표시 이름이나 all을 사용할 수 없습니다. |
|
| queries[*].query.appScopes[*] | object | 단일 대상 워크스페이스의 RUM 애플리케이션 범위입니다. 예시: {"workspaceUUID": "wksp_example", "appIds": ["app_example"]}가져오기 또는 입력 방법: 대상 워크스페이스에 승인된 실제 RUM 애플리케이션 구성에 따라 구성합니다. |
|
| queries[*].query.appScopes[*].workspaceUUID | string | 이번 승인 범위 내의 워크스페이스 UUID입니다. 예시: wksp_example가져오기 또는 입력 방법: 현재 워크스페이스 또는 승인된 대상 워크스페이스에서 가져옵니다. |
|
| queries[*].query.appScopes[*].appIds | array<string> |
해당 워크스페이스의 비어 있지 않은 애플리케이션 ID 배열이며 중복 제거됩니다. 영문, 숫자, 밑줄, 하이픈만 가능하고 최대 128자이며 all은 지원하지 않습니다. 예시: ["app_example"]가져오기 또는 입력 방법: 대상 워크스페이스의 RUM 애플리케이션 구성에서 실제 애플리케이션 ID를 가져옵니다. |
|
| queries[*].query.appScopes[*].appIds[*] | string | 실제 RUM 애플리케이션 ID 하나입니다. 예시: app_example가져오기 또는 입력 방법: 해당 워크스페이스의 RUM 애플리케이션 식별자를 복사합니다. |
|
| queries[*].query.disableMultipleField | boolean | 일반 결과 포맷의 다중 필드 제어이며 실제 값은 현재 결과 변환 규칙에서 읽습니다. 예시: true가져오기 또는 입력 방법: 일반적으로 생략하고 기존 쿼리 템플릿의 명확한 구성을 사용합니다. |
|
| fieldTagDescNeeded | boolean | 일반 쿼리의 필드/태그 설명 보충이며 기본값은 false입니다. 모든 쿼리에서 설명 필드가 추가되는 것은 아닙니다. null 허용: False 예시: false가져오기 또는 입력 방법: SHOW_FIELD 등의 결과에 유형, 단위 및 설명이 필요할 때 true로 설정합니다. |
|
| queries | array | 일반 쿼리는 최소 한 항목을 권장하며 생략/[] 시 성공적인 빈 data와 호환됩니다. QueryHub를 포함하면 1~20개 항목이어야 합니다. null 허용: False 예시: [{"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}}]가져오기 또는 입력 방법: 아래 표에 따라 각 항목을 구성하고 쿼리 항목과 응답 항목의 순서 대응을 유지합니다. |
파라미터 추가 설명¶
새 쿼리는 반드시 async_id를 생략해야 합니다. content.data[i].is_running=true이고 해당 항목의 async_id가 비어 있지 않은 경우에만 동일한 queries[i]에 다시 넣어 폴링합니다. 일반 쿼리는 원래 query, 대상 워크스페이스 및 targetRegion을 변경하지 않고 유지합니다. QueryHub 이어보기는 qtype=queryhub와 async_id를 유지하며 query는 생략할 수 있습니다. is_running=false이면 폴링을 중지하며, 이전 ID가 응답에 여전히 나타나더라도 마찬가지입니다. async_id는 세션 ID도 아니고 페이지 커서도 아니며, 새 쿼리나 다른 쿼리 항목에 재사용해서는 안 됩니다. 실행 중인데 ID가 없으면 과거 ID를 대신 사용할 수 없으며, traceId를 기록하고 제한적으로 재시도하거나 지원팀에 문의해야 합니다.
일반 크로스 워크스페이스 쿼리에서 workspaceUUIDs가 비어 있지 않으면 workspaceUUID보다 우선하며, 하나의 배치는 동일한 targetRegion만 쿼리합니다. 대상 워크스페이스 UUID와 targetRegion은 /wksp_share/granted_ws_list의 동일한 그룹에 있는 workspaceUUID와 regionCode에서 가져와야 합니다. 와일드카드 workspaceUUID="*" 또는 workspaceUUIDs=["*"]는 비어 있지 않은 targetRegion을 명시적으로 제공해야 하며, 해당 사이트에서 승인된 워크스페이스만 쿼리합니다. 콘솔 도메인이나 toRegionCode를 regionCode로 사용하지 마세요. 전체 단계는 OpenAPI 사이트 간 데이터 쿼리 및 승인된 워크스페이스 목록을 참고하세요. QueryHub는 이러한 크로스 워크스페이스 필드를 지원하지 않습니다.
일반 로그 쿼리는 warnings에서 DQLDataAccessScopeRestricted를 반환할 수 있습니다. details[].metadata.namespace는 logging이며, restriction=partial은 권한이 있는 인덱스만 반환됨을, all은 관련 로그 인덱스 모두 권한이 없어 빈 결과가 반환됨을 의미합니다. HTTP 200의 빈 데이터를 전체 워크스페이스에 데이터가 없는 것으로 간주해서는 안 됩니다. 미복구 이벤트 쿼리를 참고하세요.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"qtype":"dql","async_timeout":"5s","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 | 아직 실행 중인지 여부입니다. true일 때만 폴링을 계속합니다. false이면 async_id가 여전히 비어 있지 않더라도 중지합니다. |
| 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 | 워크스페이스 선언입니다. |
| content.data[].query_status | string | QueryHub는 pending, running, success, failed입니다. 일부 일반 성공 응답에는 이 필드가 없습니다. |
| content.data[].query_error.message | string | QueryHub 단일 항목의 오류 메시지입니다. |
| content.data[].series[].columnTypes | array<string> |
QueryHub 열 유형이며 columns와 일대일로 대응합니다. |
| content.data[].uuid | string 또는 null | QueryHub 쿼리 항목의 클라이언트 식별자입니다. |
| content.data[].truncated | boolean | QueryHub 성공 결과가 잘렸는지 여부입니다. |
| content | object | 순서가 있는 배치 결과 객체입니다. |
| content.data[].async_id | string | 아직 실행 중인 항목의 작업 ID입니다. QueryHub 종료 상태에서는 비워지며, 일반 실패 항목은 비어 있지 않은 ID가 유지될 수 있습니다. is_running과 오류 필드로 계속할지 판단합니다. |
| content.data[].query_error.errorSource | string | 일반 외부 쿼리 오류 출처: studio, transport, func, datasource 또는 unknown. |
| content.data[].query_error.errorStage | string | 일반 외부 쿼리 실패 단계입니다. |
| content.data[].query_error.taskId | string | 진단용 원래 작업 ID이며 종료 상태에서 유지될 수 있습니다. |
| content.data[].query_error.upstreamTraceId | string | 업스트림에서 제공하는 추적 ID이며 생략될 수 있습니다. |
| content.data[].query_error.redacted | boolean | 진단 정보에 민감한 값 마스킹이 적용되었는지 여부이며 생략될 수 있습니다. |
| content.data[].query_error.errorDetails | object | 공개가 허용된 오류 진단 스칼라입니다. |
| content.data[].errorInfo | object | 일부 일반 외부 쿼리에서 유지되는 호환 오류 객체입니다. message는 query_error.error에 대응하며 다른 진단 필드도 유사합니다. |
| content.data[].warnings[].code | string | 쿼리 경고 코드이며 HTTP 200에서도 반환될 수 있습니다. |
| content.data[].warnings[].message | string | 현지화된 경고 메시지입니다. |
| content.data[].warnings[].details | JSON 값 | 엔진에서 제공하는 추가 정보이며 실제 응답에 따라 읽습니다. |
| content.data[].queryTimeRangeAdjusted | object | 일반 로그 장기 저장 규칙이 쿼리 범위를 조정할 때 나타납니다. |
| content.data[].queryTimeRangeAdjusted.adjusted | boolean | 조정 표시이며, 나타나면 true입니다. |
| content.data[].queryTimeRangeAdjusted.reason | string | 현재는 log_long_storage_policy입니다. |
| content.data[].queryTimeRangeAdjusted.originalTimeRange | array | 원래 쿼리 시간 범위입니다. |
| content.data[].queryTimeRangeAdjusted.queryTimeRange | array | 실제 쿼리 범위이며, 빈 배열은 조회 가능한 데이터가 없음을 의미합니다. |
| content.data[].queryTimeRangeAdjusted.mode | string | standard_window, long_storage_day 또는 empty입니다. |
| content.data[].queryTimeRangeAdjusted.standardDuration | string | 표준 저장 기간이며 일 단위입니다. |
| content.data[].queryTimeRangeAdjusted.retentionDuration | string | 전체 보존 기간이며 일 단위입니다. |
| content.data[].series[].values[] | array | columns와 일대일로 대응하는 단일 행이며, 셀은 JSON 값 또는 null일 수 있습니다. QueryHub 큰 정수는 정밀도 손실을 피하기 위해 문자열을 사용할 수 있습니다. |
| content.data[].series[].values[][] | JSON 값 | 특정 열 셀 값이며, 유형은 열 설명 및 원본 데이터와 일치합니다. |
| content.data[].series[].value_desc | object | 일부 일반 SHOW_FIELD 쿼리에서 fieldTagDescNeeded=true일 때 필드 메타 정보를 제공합니다. |
| content.data[].series[].value_desc.字段名 | object | 필드 유형, 단위 및 설명입니다. |
| content.data[].series[].value_desc.字段名.name | string | 필드 이름입니다. |
| content.data[].series[].value_desc.字段名.type | string | 필드 유형입니다. |
| content.data[].series[].value_desc.字段名.unit | string | 단위이며 구성이 없으면 비어 있을 수 있습니다. |
| content.data[].series[].value_desc.字段名.desc | string | 필드 설명이며 구성이 없으면 비어 있을 수 있습니다. |
| content.data[].query_error.errorDetails.message | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].query_error.errorDetails.reason | string | 일반 네이티브 쿼리 바인딩 실패 시 resubmit_required일 수 있으며, 새 쿼리를 만들어야 하고 이전 ID를 폴링할 수 없습니다. |
| content.data[].query_error.errorDetails.error | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].query_error.errorDetails.status | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].query_error.errorDetails.taskStatus | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].query_error.errorDetails.exceptionType | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].query_error.errorDetails.exception | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.errorType | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.errorCode | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.message | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.errorSource | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.errorStage | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.taskId | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.upstreamTraceId | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.redacted | JSON 스칼라 | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| content.data[].errorInfo.errorDetails | object | 선택적 진단 필드이며 실제 응답에 따라 제공됩니다. 진단 상태를 이번 HTTP 상태로 간주하지 마세요. |
| 응답 헤더 | 유형 | 설명 |
|---|---|---|
| Content-Type | string | application/json. |
| Cache-Control | string | QueryHub 자체 성공 및 캡처된 QueryHubError 응답은 no-store입니다. 혼합 배치에서 일반 쿼리가 다른 예외를 발생시키면 이 헤더가 보장되지 않습니다. 순수 일반 비동기 진입점에는 동기 v1의 추가 ETag 구성이 없으므로 동일한 캐시 헤더에 의존해서는 안 됩니다. |
{
"code": 200,
"content": {
"data": [
{
"async_id": "legacy-task-from-response",
"is_running": true,
"series": []
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
일반 작업 폴링
curl --request POST '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"qtype":"dql","async_timeout":"5s","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5},"async_id":"legacy-task-from-response"}]}'
QueryHub 최초 제출
curl --request POST '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"uuid":"db-query","qtype":"queryhub","query":{"datasourceId":"orders","mode":"native","native":{"language":"sql","statement":"SELECT 1 AS value","parameters":[]}}}]}'
QueryHub 제출 응답
{
"code": 200,
"content": {
"data": [
{
"uuid": "db-query",
"async_id": "qhtask_00000000000000000000000000000001",
"query_status": "pending",
"is_running": true,
"series": []
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
QueryHub 폴링(동일한 API Key 사용)
curl --request POST '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"uuid":"db-query","qtype":"queryhub","async_id":"qhtask_00000000000000000000000000000001"}]}'
QueryHub 완료 응답
{
"code": 200,
"content": {
"data": [
{
"uuid": "db-query",
"async_id": "",
"query_status": "success",
"is_running": false,
"truncated": false,
"series": [
{
"columns": [
"value"
],
"columnTypes": [
"Int64"
],
"values": [
[
1
]
]
}
]
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
QueryHub 작업이 없거나 만료된 단일 항목 실패
{
"code": 200,
"content": {
"data": [
{
"uuid": "db-query",
"async_id": "",
"query_status": "failed",
"is_running": false,
"series": [],
"query_error": {
"errorCode": "QueryHubTaskNotFound",
"message": "查询任务已失效,请重新提交。"
}
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
일반 GET 호출
curl --get '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'body={"queries":[{"qtype":"dql","async_timeout":"5s","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 파라미터가 필드 선언을 위반했습니다. | 메시지에 유효하지 않은 필드 또는 규칙이 표시됩니다. | 해당 파라미터 표에 따라 요청을 수정하세요. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문 오류입니다. | 요청 JSON 형식이 잘못되었습니다. content에 reason, line, column이 포함됩니다. | JSON 구문을 수정한 후 다시 시도하세요. |
| 400 | ft.TimeRangeUnitMismatch | timeRange의 시작 및 종료 시간이 서로 다른 단위를 사용합니다. | 시작 및 종료 시간 단위가 일치하지 않습니다. | 동일한 정밀도의 타임스탬프를 사용하세요. |
| 403 | ft.ForbiddenQuery | API Key에 대상 데이터를 쿼리할 권한이 없거나 대상 사이트가 권한 오류로 사이트 간 쿼리를 거부했습니다. | DQL 쿼리 권한이 없습니다. | 대상 워크스페이스 승인 및 대상 사이트를 확인하세요. |
| 403 | forethought.QueryHubForbidden | QueryHub 전체 호출 ID, 워크스페이스 또는 쿼리 권한이 허용되지 않습니다. | 현재 ID에는 해당 QueryHub 작업을 수행할 권한이 없습니다. | 동일한 워크스페이스의 원래 API Key를 사용하고 사이트/데이터 소스 권한을 확인하세요. 대상 워크스페이스 헤더나 오프라인 ID를 사용하지 마세요. |
| 400 | ft.JsonFormatError | 일반 쿼리 객체 또는 queries/query 구조가 예상 JSON 유형이 아닙니다. | 일부 json 파일 형식이 잘못되었습니다. | queries 배열을 제출하고 각 항목의 query는 객체를 사용하세요. |
| 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 및 실제 상태에 따라 백오프 재시도하세요. |
| 400 | forethought.QueryHubInvalidFields | QueryHub 배치 구조 오류, GET/비JSON/URL body 또는 1~20개가 아닌 배열입니다. | 메시지가 비어 있을 수 있습니다. | 이 페이지의 POST JSON 템플릿을 사용하고 최상위 query나 일반 GET body를 섞지 마세요. |
| 503 | forethought.QueryHubUnavailable | QueryHub 기능이 활성화되지 않았거나 서비스를 사용할 수 없습니다. | 쿼리 서비스 또는 데이터 소스를 일시적으로 사용할 수 없습니다. | 권한, 쿼리 기능 및 서비스 상태를 확인하세요. |
| 400 | ft.QueryActionLimit | 사이트의 느린 쿼리 보호가 현재 Key를 일시적으로 제한했습니다. | 느린 쿼리가 너무 많아 단시간 내 요청이 제한됩니다. | 제한이 해제될 때까지 기다리고, 초대형 쿼리를 줄이며 연속 재시도를 피하세요. |
| 406 | ft.IllegalDensity | density가 현재 사이트에서 허용하는 포인트 밀도 구성에 없습니다. | density가 유효하지 않습니다. 선택 가능한 값: {} | interval 또는 maxPointCount를 명시적으로 사용하는 것이 우선이며, density 사용 전에 사이트 구성을 확인하세요. |
| 403 | ft.Forbidden | 이 OpenAPI에서 공개하지 않는 호스팅 외부 데이터 소스 쿼리 채널을 사용했습니다. | 작업 권한이 없습니다. | 승인된 QueryHub 프로토콜 또는 사이트에서 명시적으로 지원하는 쿼리 방식을 사용하고 Front 요청을 그대로 따르지 마세요. |
| 500 | ft.InternalServerError | 제어되지 않은 쿼리 연결, 파라미터 구조 또는 내부 서비스 예외입니다. | 내부 오류입니다. | traceId와 마스킹된 요청을 보관하세요. 제출 타임아웃 시 작업이 이미 생성되었는지 먼저 확인하여 중복 제출을 피하세요. |
| 502 | forethought.QueryHubInvalidBatch | 혼합 배치의 일반 쿼리 결과 수와 요청 수가 일치하지 않습니다. | 메시지가 비어 있을 수 있습니다. | 일반 쿼리와 QueryHub 배치를 분리해 확인하고 traceId를 보관하세요. |
| 200 | QueryHubInvalidId | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 단일 항목 message가 비어 있거나 일반 쿼리 실패 메시지를 사용할 수 있습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubInvalidFields | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 데이터 소스 구성 필드 및 입력 형식을 확인하세요. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubUnsupportedMode | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 단일 항목 message가 비어 있거나 일반 쿼리 실패 메시지를 사용할 수 있습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubUnsupportedContract | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 단일 항목 message가 비어 있거나 일반 쿼리 실패 메시지를 사용할 수 있습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubForbidden | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리 권한이 없습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubDatasourceNotFound | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 단일 항목 message가 비어 있거나 일반 쿼리 실패 메시지를 사용할 수 있습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubRevisionConflict | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 단일 항목 message가 비어 있거나 일반 쿼리 실패 메시지를 사용할 수 있습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubSnapshotNotReady | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 데이터 소스 구성이 아직 적용되지 않았으니 나중에 다시 시도하세요. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubQueryRejected | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리 실행에 실패했습니다. 쿼리 조건과 데이터 소스 구성을 확인하세요. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubQueryTimeout | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리 시간이 초과되었습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubInvalidResult | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리 결과 형식이 비정상입니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubUnavailable | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리 서비스 또는 데이터 소스를 일시적으로 사용할 수 없습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubBusy | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리가 혼잡합니다. 나중에 다시 시도하세요. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubTaskNotFound | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리 작업이 만료되었습니다. 다시 제출하세요. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryHubTaskCancelled | QueryHub 단일 항목 실패이며 코드는 content.data[].query_error.errorCode에 있고 외부는 여전히 success=true일 수 있습니다. | 쿼리 작업이 취소되었습니다. | 종료 상태 항목의 폴링을 중지하세요. 작업이 없거나 만료된 경우 원래 요청으로 다시 제출하고, 혼잡/사용 불가 시 백오프하며, 권한/모드/버전 문제는 먼저 구성을 수정하세요. |
| 200 | QueryResultUnavailable | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | InvalidQueryResponse | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | NoFuncClient | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | FuncWorkerNoResponse | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | ExternalQueryTimeout | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | ExternalQueryExecutionFailed | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | ExternalQueryBindingUnavailable | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | WebSocketDispatchFailed | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 200 | DQLAsyncQueryBindingUnavailable | 일반 쿼리 단일 항목의 query_error/errorInfo가 실패했지만 외부는 여전히 성공일 수 있습니다. | 해당 항목의 error/message/reason 실제 텍스트를 기준으로 합니다. | is_running=false이면 폴링을 중지하세요. 캐시 또는 바인딩이 만료된 경우 데이터 소스/클라이언트 상태를 확인한 후 새 쿼리를 다시 제출하고 이전 async_id를 재시도하지 마세요. |
| 422 | ft.KodoAggregateOutputRowsLimitReached | 집계 중간 결과의 예상 행 수가 제한을 초과했습니다. | 집계 중간 결과가 최소 {}행을 생성할 것으로 예상되어 {}행 상한을 초과합니다. 시간 범위를 줄이거나 필터 조건을 추가하거나 그룹화를 줄이세요. 반환 건수만 줄여서는 이 제한을 피할 수 없습니다. | 시간 범위를 줄이고 필터를 추가하거나 그룹화를 줄이세요. limit만 줄인다고 해서 집계 중간 결과가 반드시 줄어들지는 않습니다. |
| 422 | ft.KodoScanRowLimitExceeded | 단일 실행 단계의 스캔 행 수가 초과되었습니다. | 쿼리의 단일 실행 단계가 {}행을 처리할 것으로 예상되어 {}행 상한을 초과합니다. 시간 범위를 줄이거나 샘플링 비율을 낮추세요. | 시간 범위를 줄이고 선택적 필터를 추가하거나 샘플링 범위를 줄이세요. |
| 422 | ft.KodoScanBytesLimitExceeded | 스캔 압축 해제 바이트 수가 제한을 초과했습니다. | 쿼리의 단일 실행 단계가 {}바이트(비압축)를 스캔할 것으로 예상되어 {}바이트 상한을 초과합니다. 시간 범위를 줄이거나 샘플링 비율을 낮추세요. | 스캔 시간과 인덱스 범위를 줄이세요. 반환 건수만 줄이지 마세요. |
| 422 | ft.KodoQueryEstimateLimitExceeded | 유휴 클러스터의 예상 쿼리 소요 시간이 제한에 도달했습니다. | 유휴 클러스터에서 예상 쿼리 소요 시간이 {}초로 {}초 제한에 도달했으며 {}행의 데이터가 관련됩니다. 시간 범위를 줄이거나 쿼리를 단순화하세요. | 쿼리를 단순화하거나 범위를 줄인 후 제출하고, 원래의 대형 쿼리를 연속 재시도하지 마세요. |
| 429 | ft.KodoServerOverloaded | 쿼리 서비스가 과부하 상태이거나 요청이 너무 많습니다. | 현재 요청이 너무 많으니 나중에 다시 시도하세요. | 백오프하고 동시성을 낮춘 후 재시도하세요. |
| 429 | ft.KodoQueryQueueAdmissionFailed | 쿼리 승인 대기열 처리에 실패했습니다. | 쿼리 승인 대기열이 요청 처리에 실패했습니다. 나중에 다시 시도하세요. | 백오프하고 동시성을 줄이세요. |
| 429 | ft.KodoUserDQLRateLimited | 빈번한 초대형 쿼리로 임시 제한이 발생했습니다. | 빈번하게 초대형 데이터 쿼리를 시작하여 쿼리가 일시적으로 제한되었습니다. {}분 후 다시 시도하세요. | 메시지의 제한 기간이 끝날 때까지 기다린 후 쿼리 범위를 줄여 재시도하세요. |
| 406 | ft.KodoOffsetWithCursorTime | offset과 cursor_time을 동시에 사용했습니다. | offset 파라미터는 cursor_time 파라미터와 함께 사용할 수 없습니다. | 오프셋 페이지네이션 또는 커서 페이지네이션 중 하나를 선택하고 두 제어 항목을 동시에 제출하지 마세요. |
| 406 | ft.KodoQueryNotFound | 일반 쿼리 작업이 없거나 만료되었습니다. | 쿼리가 없거나 만료되었습니다. | 이전 ID 폴링을 중지하고, 결과를 더 가져올 필요가 없는지 확인한 후 원래 파라미터로 새 쿼리를 만드세요. |
| 406 | ft.KodoRequestDeadlineExceeded | 쿼리가 백엔드 실행 기한을 초과했습니다. | 데이터 쿼리 시간이 초과되었습니다. 원인은 다음과 같을 수 있습니다: 데이터 양이 너무 많음, 네트워크 지연, 서버 부하 과다. 다음 방법으로 해결할 수 있습니다: 1. 필터 조건을 추가하거나 시간 범위를 줄인 후 다시 쿼리합니다. 2. 잠시 기다린 후 다시 쿼리합니다. |
시간 범위, 그룹화 및 스캔 데이터 양을 줄인 후 다시 제출하세요. |
| 406 | ft.KodoTooManyRows | 쿼리 데이터 양이 상한을 초과했습니다. | 쿼리 데이터 양이 최대 수량 제한을 초과했습니다. 필터 조건을 추가하거나 시간 범위를 줄인 후 다시 쿼리하세요. | 필터를 추가하거나 시간 범위를 줄이세요. |