DQL 데이터 쿼리¶
POST /api/v1/df/query_data_v1
GET /api/v1/df/query_data_v1
개요¶
쿼리 배치 단위로 DQL 또는 PromQL 데이터를 가져옵니다. POST는 QueryHub 데이터 소스를 통한 쿼리도 지원합니다.
호출 전 확인 및 사용 단계¶
일반 DQL 또는 PromQL은 POST JSON을 권장합니다. GET은 동일한 JSON 객체를 URL 인코딩한 body에 담아 전달합니다. QueryHub는 POST JSON만 사용하며, 해당 쿼리 언어를 지원하는 데이터 소스가 현재 워크스페이스에서 활성화되어 있어야 합니다. 동기 혼합 배치는 최대 20개 항목, QueryHub 쿼리는 최대 1개입니다. QueryHub 쿼리가 여러 개 필요하면 비동기 쿼리를 사용하세요.
예시의 메저먼트와 필드는 워크스페이스에 수집된 데이터로 교체해야 하며, 메저먼트 목록 및 메저먼트 스키마에서 확인할 수 있습니다. 시간 범위는 데이터가 존재하는 구간으로 변경하세요. 응답을 파싱할 때는 항목별로 warnings 또는 query_error를 확인하고, 다음 페이지는 해당 항목 자체의 커서를 사용합니다.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 현재 워크스페이스의 OpenAPI Key입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 쿼리 권한이 있는 자격 증명을 발급받습니다. |
Query 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| body | string | GET 쿼리에 사용하는 전체 JSON 객체 문자열입니다. 생략하고 다른 쿼리도 제출하지 않으면 빈 결과를 반환합니다. 예시: {"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}가져오기 또는 입력 방법: 쿼리 객체를 한 번 직렬화한 뒤 URL 인코딩합니다. 예: curl --data-urlencode. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| queries | array | 비즈니스 쿼리는 최소 1개를 전달해야 합니다. 생략하거나 빈 배열이면 빈 데이터를 반환합니다. null 허용: False 예시: [{"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}}]가져오기 또는 입력 방법: 일반 쿼리 및 QueryHub 예시를 참고하여 쿼리 항목을 구성하며, qtype이 쿼리 유형을 결정합니다. |
|
| fieldTagDescNeeded | boolean | 기본값 false입니다. null 허용: False 예시: false가져오기 또는 입력 방법: 필드 또는 Tag 설명도 함께 읽어야 할 때 true를 전달합니다. |
파라미터 추가 설명¶
QueryHub는 POST JSON으로만 제출합니다. queries[].qtype에 queryhub를 전달하고, query에 datasourceId, mode 그리고 동일한 이름의 native 또는 dql 객체를 전달합니다. API Key의 routine.defaultAccess 및 현재 공간의 인스턴스 쿼리 권한이 필요합니다. 동기 배치에는 QueryHub 쿼리를 최대 1개까지 포함할 수 있습니다. 항목별 오류는 content.data[].query_error에, 성공 시에는 series와 truncated에 반환됩니다.
쿼리 설명
이 API는 POST와 GET을 모두 지원하며, 두 방식은 동일한 JSON object 파라미터 구조를 사용합니다:
- POST: 전체 파라미터를
application/jsonrequest 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을 지정할 수 있으며, 전달하지 않으면 현재 사이트에서 권한이 부여된 공간과 현재 공간을 쿼리합니다. 호환 표기인workspaceUUID="*"도 계속 지원되며 동일한 규칙을 따릅니다.- 대상 워크스페이스와
targetRegion은/api/v1/wksp_share/granted_ws_list를 통해 가져와야 합니다. 전체 예시는 다음을 참고하세요: OpenAPI 크로스 사이트 데이터 쿼리.
1、 파라미터 설명
| 파라미터명 | type | 필수 | 기본값 / 생략 시 동작 | 설명 |
|---|---|---|---|---|
| queries | array | [] (빈 데이터 반환) |
다중 명령 쿼리로, 내용은 query 객체로 구성된 목록입니다. 비즈니스 쿼리는 최소 하나의 query를 전달해야 합니다. | |
| fieldTagDescNeeded | boolean | false |
field 또는 tag 설명 정보가 필요한지 여부입니다. |
2、 queries[*] 구성원 파라미터 구조 설명
| 파라미터명 | type | 필수 | 기본값 / 생략 시 동작 | 설명 |
|---|---|---|---|---|
| qtype | string | dql |
쿼리 문의 유형입니다. dql: DQL 유형 쿼리 문을 의미합니다.promql: PromQL 유형 쿼리 문을 의미합니다. 예시 dql. |
|
| query | json | Y | - | 유효한 쿼리에 필수입니다. 누락되거나 query.q가 비어 있으면 유효한 다운스트림 쿼리가 생성되지 않습니다. 예시 {"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는 캐시 사용을 의미합니다. 예시 false. |
|
| query.disable_streaming_aggregation | boolean | false |
스트리밍 집계 비활성화 여부입니다. 명시적으로 true를 전달하면 비활성화되고, false를 전달하면 사용이 허용됩니다. 예시 false. |
|
| query.promqlType | enum | rangeQuery |
qtype=promql일 때 적용되며, 선택 가능한 값은 instantQuery, rangeQuery입니다. 예시 rangeQuery. |
|
| query.highlight | boolean | false |
하이라이트 데이터 표시 여부입니다. 예시 false. |
|
| query.timeRange | array | [] |
외부 시간 범위입니다. DQL에서 전달하지 않으면 문 내의 창을 덮어쓰지 않으며, 현재 일반 Select 메인 체인은 GuanceDB가 최근 30분을 폴백합니다. PromQL은 두 개의 시간 지점을 명시적으로 전달해야 하며, 다른 엔진은 동작이 다를 수 있습니다. DQL / PromQL의 시작 및 종료 시간은 동일한 단위(초, 밀리초, 마이크로초 또는 나노초)를 사용해야 하며, 혼용하면 HTTP 400 ft.TimeRangeUnitMismatch가 반환됩니다. 페이지네이션 커서는 독립적으로 유지됩니다. 예시 [1785427200000,1785430800000]. 필요한 쿼리 창을 동일한 정밀도의 두 타임스탬프로 교체하며, Unix 밀리초를 권장합니다. |
|
| query.disableMultipleField | bool | true |
단일 열 모드 사용 여부입니다. 예시 true. |
|
| query.showLabel | bool | false |
객체의 labels 표시 여부입니다. 예시 false. |
|
| query.funcList | array | [] |
DQL 반환 값을 다시 집계하여 수정합니다. 선택한 집계 함수에 따라 처리됩니다. 예시 ["last"]. |
|
| query.slimit | integer | DQL / 다운스트림 설정에 따름 | 시계열 그룹 크기로, 메트릭 쿼리에만 유효합니다. 예시 10. |
|
| query.soffset | integer | DQL의 값, DQL에도 설정되지 않은 경우 추가 오프셋 없음 | 시계열 그룹 오프셋입니다. 현재 파서는 양수 외부 값으로만 DQL에 설정되지 않은 오프셋을 보충하며, 0은 DQL의 기존 값을 지우지 않습니다. 예시 10. |
|
| query.limit | integer | DQL / 다운스트림 설정에 따름 | 페이지네이션 크기입니다. 예시 5. |
|
| query.offset | integer | DQL의 값, DQL에도 설정되지 않은 경우 추가 오프셋 없음 | 페이지네이션 오프셋입니다. 현재 파서는 양수 외부 값으로만 DQL에 설정되지 않은 오프셋을 보충하며, 0은 DQL의 기존 값을 지우지 않습니다. 예시 5. |
|
| query.orderby | array | DQL / 쿼리 엔진에 따름 | 정렬 목록으로, 구조는 {fieldName: method}입니다. 메저먼트 쿼리는 fieldName=time만 지원하며, method는 desc, asc를 선택할 수 있습니다. 예시 [{"time":"desc"}]. |
|
| query.sorderby | array | DQL / 쿼리 엔진에 따름 | 정렬 목록입니다. column은 min, max, last, avg, p90, p95, count 등 단일 값을 반환하는 집계 함수를 지원합니다. | |
| query.order_by | array | DQL / 쿼리 엔진에 따름 | Doris 엔진 호환 정렬 목록으로, 구조는 [{"column": "field", "order": "DESC"}]입니다. 예시 [{"column":"time","order":"DESC"}]. |
|
| query.sorder_by | array | DQL / 쿼리 엔진에 따름 | Doris 엔진 호환 시계열 정렬 목록으로, 구조는 [{"column": "field", "order": "DESC"}]입니다. 예시 [{"column":"usage_idle","order":"DESC"}]. |
|
| query.density | string | DQL / 쿼리 엔진에 따름 | 응답 포인트 밀도로, DQL 문 내의 제어 파라미터보다 우선합니다. 예시 medium. |
|
| query.interval | number | DQL / 쿼리 엔진에 따름 | 시간 분할 간격으로, Kodo int64 범위로 변환 가능하고 1ms 이상인 정수만 허용합니다. 단위는 interval_unit으로 지정합니다. 예시 60. |
|
| query.interval_unit | string | s |
interval의 단위로, s, ms를 선택할 수 있습니다. 예시 s. |
|
| query.align_time | boolean | false |
쿼리 엔진의 시간 그리드에 맞춰 시간 분할을 정렬할지 여부입니다. 예시 false. |
|
| query.tz | string | Asia/Shanghai |
쿼리 시간대입니다. 예시 Asia/Shanghai. |
|
| query.search_after | array | 페이지네이션 마커 미설정 | 심층 페이지네이션 파라미터입니다. 다음 요청에는 이전 응답의 search_after를 전달해야 합니다. 예시 [1785427200000,"cursor-example"]. 다음 페이지에서는 이전 동일 쿼리가 실제로 반환한 배열을 그대로 복사해야 합니다. |
|
| query.maxPointCount | integer | DQL / 쿼리 엔진에 따름 | 최대 포인트 수입니다. 예시 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로 가져옵니다. 명시적 크로스 사이트 쿼리 시 전달을 권장하며, 와일드카드이고 생략된 경우 현재 사이트를 사용합니다. 호환 표기 workspaceUUID="*"도 동일한 규칙을 따릅니다. 예시 example-region. |
|
| query.output_format | string | 기존 JSON 응답 형식 | lineprotocol로 설정하면 항목별 쿼리 내용이 라인 프로토콜을 사용할 수 있으며, 외부 응답은 여전히 JSON입니다. 예시 lineprotocol. |
|
| query.cursor_time | integer | 커서 미설정 | 첫 번째 분할 쿼리 시 end_time으로 설정하며, 이후에는 응답의 next_cursor_time을 전달합니다. 예시 1785430800000. 다음 페이지에서는 응답의 next_cursor_time을 사용합니다. |
|
| query.cursor_token | string | 토큰 미설정 | 페이지네이션 시 이전 응답의 next_cursor_token을 전달합니다. 전달하지 않으면 동일한 타임스탬프의 데이터가 페이지 전환 시 건너뛰어질 수 있습니다. 예시 cursor-example. 다음 페이지에서는 응답의 next_cursor_token을 사용합니다. |
|
| query.disable_sampling | bool | false |
샘플링 비활성화 여부입니다. 예시 false. |
|
| query.disable_truncate | bool | false |
반환 내용 잘림 비활성화 여부입니다. false는 잘림을 허용함을 의미합니다. 예시 false. |
3、 응답 포인트 밀도 density 파라미터 값 설명
| 선택 가능한 값 | 설명 |
|---|---|
| lower | 낮음, 60개 포인트 |
| low | 낮음, 180개 포인트 |
| medium | 중간, 360개 포인트 |
| high | 높음, 720개 포인트 |
- 포인트 밀도 파라미터의 우선순위에 유의하세요. 최대 밀도
density[high]* interval은 density 및 DQL의 포인트 밀도 설정보다 우선합니다. maxPointCount는 도출된 포인트 수를 추가로 제한할 수 있습니다.
4、 일반적인 쿼리 설명
데이터 가시 범위는 API Key의 유효 권한, 워크스페이스 권한 부여 및 데이터 액세스 규칙에 따라 달라집니다.
5、 요청 JSON 형식 오류
요청 본문이 유효한 JSON이 아니면 API는 쿼리 처리에 진입하기 전에 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-..."
}
QueryHub 요청 필드¶
| 파라미터 | 입력 방법 |
|---|---|
| queries[].qtype | QueryHub 쿼리 항목에는 queryhub를 입력합니다. |
| queries[].uuid | 선택적 클라이언트 쿼리 식별자입니다(예: demo-query). 응답에 그대로 반환됩니다. |
| queries[].query.datasourceId | 현재 공간의 통합 "외부 데이터 소스"에서 이미 적용된 데이터 소스 ID를 가져옵니다(예: orders). |
| queries[].query.mode | 필수이며, native 또는 dql 중 하나를 선택하고 mode와 동일한 이름의 객체만 입력합니다. |
| queries[].query.native | MySQL 또는 PostgreSQL의 경우 language=sql 및 statement를 입력할 수 있습니다(예: SELECT 1 AS value). parameters 배열을 추가로 제공할 수 있습니다. |
| queries[].query.dql | QueryHub DQL 쿼리 객체입니다. dql 문을 입력하고 dqlVersion(기본값 queryhub/v1) 및 parameters 객체를 추가할 수 있습니다. |
| queries[].query.expectedRevision | 선택적 양의 정수로, 호출자가 알고 있는 데이터 소스 설정 버전에 따라 검증할 때 사용합니다. |
요청 예시¶
curl 'https://openapi.guance.com/api/v1/df/query_data_v1' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'
QueryHub 네이티브 SQL 예시
curl 'https://openapi.guance.com/api/v1/df/query_data_v1' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"qtype":"queryhub","uuid":"demo-query","query":{"datasourceId":"orders","mode":"native","native":{"language":"sql","statement":"SELECT 1 AS value"}}}]}'
응답¶
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 | 워크스페이스 선언입니다. |
| content.data[].query_status | string | QueryHub 항목별 상태로, 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 성공 결과가 잘렸는지 여부입니다. |
| 응답 헤더 | 타입 | 설명 |
|---|---|---|
| Cache-Control | string | QueryHub 분기의 응답은 no-store입니다. |
{
"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"
}
QueryHub 성공 예시
{"code": 200, "content": {"data": [{"uuid": "demo-query", "query_status": "success", "is_running": false, "truncated": false, "series": [{"columns": ["value"], "columnTypes": ["integer"], "values": [[1]]}]}], "declaration": null}, "errorCode": "", "message": "", "success": true, "traceId": "TRACE-EXAMPLE"}
HTTP 200에서의 QueryHub 항목별 실패
{"code": 200, "content": {"data": [{"uuid": "demo-query", "query_status": "failed", "is_running": false, "series": [], "query_error": {"errorCode": "QueryHubForbidden", "message": "쿼리 권한이 없습니다."}}], "declaration": null}, "errorCode": "", "message": "", "success": true, "traceId": "TRACE-EXAMPLE"}
오류 응답¶
인증, 속도 제한 및 공용 요청 오류는 공용 오류 정의를 참고하세요.
QueryHub 항목별 실패는 query_error.errorCode를 확인해야 합니다. 데이터 소스 미승인, 타임아웃 또는 쿼리 거부 시 각각 QueryHubForbidden, QueryHubQueryTimeout 또는 QueryHubQueryRejected가 해당될 수 있습니다. 항목별 오류 식별자에는 forethought. 접두사가 붙지 않습니다.
| 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 요청에 필요한 쿼리 권한이 없음 | 쿼리 권한이 없습니다. | API Key와 인스턴스 쿼리 권한을 확인합니다. |
| 400 | ft.JsonFormatError | JSON 최상위 또는 쿼리 항목 구조가 유효하지 않거나 요청 내용이 너무 깊음 | 일부 JSON 파일 형식 오류입니다. | 최상위 및 쿼리 항목의 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/URL body로 QueryHub를 제출함 | 메시지가 비어 있을 수 있습니다. | POST JSON으로 1~20개의 쿼리 항목을 제출합니다. |
| 422 | forethought.QueryHubUseAsync | 동기 요청에 여러 QueryHub 쿼리가 포함됨 | 메시지가 비어 있을 수 있습니다. | 비동기 API를 사용합니다. |
| 503 | forethought.QueryHubUnavailable | QueryHub 기능이 활성화되지 않았거나 서비스를 사용할 수 없음 | 쿼리 서비스 또는 데이터 소스를 일시적으로 사용할 수 없습니다. | 권한, 쿼리 기능 및 서비스 상태를 확인합니다. |