SQL 쿼리 실행과 결과 조회
SQL Query는 Foundry에서 실행한 SQL 쿼리를 나타냅니다. 데이터셋을 대상으로 Spark SQL 방언의 SELECT 문을 실행하고, 쿼리 ID로 상태나 결과를 조회합니다. 쿼리를 실행한 사용자만 해당 쿼리를 조작할 수 있습니다.
| 작업 | 기능 |
|---|---|
| Execute SQL Query | 새 SQL 쿼리를 제출하고 상태를 받습니다. |
| Get Status SQL Query | 제출한 쿼리의 상태를 확인합니다. |
| Get Results SQL Query | 실행할 때 선택한 Arrow 또는 CSV 형식으로 결과를 받습니다. |
| Cancel SQL Query | 실행 중인 쿼리를 취소합니다. |
요청 순서와 결과 형식
실행 요청에 SQL 문과 결과 직렬화 형식을 지정합니다. 기본 형식은 ARROW이며 CSV를 선택할 수 있습니다. 데이터셋은 경로나 RID로 참조합니다. 반환 결과는 기본적으로 100만 행까지이며 더 높은 한도가 필요하면 Palantir 담당자와 협의합니다.
실행 응답이 running 또는 succeeded이면 queryId를 보관합니다. 상태 조회로 진행 상태를 확인하거나 결과 조회를 사용합니다. 결과 조회는 최대 1분 동안 대기하는 long polling을 제공하며, 쿼리가 계속 실행 중일 때 타임아웃된 결과 조회는 안전하게 다시 요청할 수 있습니다. 쿼리가 필요 없어지면 취소합니다. 이미 실행이 끝난 쿼리에는 취소 요청이 추가 상태 변경을 일으키지 않습니다.
QueryStatus
상태 응답은 type으로 구분합니다.
| type | 의미 | 추가 필드 |
|---|---|---|
running | 실행 중 | 필수 문자열 queryId |
canceled | 취소됨 | 없음 |
failed | 실패 | 필수 문자열 errorMessage |
succeeded | 성공 | 필수 문자열 queryId |
errorMessage는 쿼리가 실패한 이유를 설명합니다. 상태 응답과 HTTP 오류 응답은 각각 처리하며, 각 엔드포인트의 오류 표에서 상태 코드와 오류 매개변수를 확인합니다.
쿼리 ID의 URL 인코딩
sqlQueryId는 URL에 그대로 넣을 수 있는 형식이 아니므로 경로에 넣기 전에 퍼센트 인코딩해야 합니다. queryId를 URL 전체가 아닌 경로 조각 하나로 인코딩합니다. 예를 들어 형식 설명용 ID a/b+c=는 a%2Fb%2Bc%3D가 됩니다.
상태, 취소 및 결과 조회 예제의 SQL_QUERY_ID_URL_ENCODED 환경 변수에는 이처럼 인코딩한 ID를 제공합니다. 이미 인코딩한 값을 다시 인코딩하지 않습니다. FOUNDRY_HOST에는 프로토콜을 제외한 Foundry 호스트를, FOUNDRY_TOKEN에는 쿼리를 실행한 사용자의 유효한 토큰을 제공합니다.
기본 브랜치와 대체 브랜치
실행 본문의 fallbackBranchIds는 우선 대상 브랜치에서 실행할 수 없을 때 사용할 대체 브랜치 이름 목록입니다. SQL 문에 브랜치를 명시하지 않으면 목록에서 존재하는 첫 브랜치를 사용합니다. 대체 목록을 생략하면 기본 브랜치를 사용합니다. 많은 플랫폼 인스턴스에서는 기본 브랜치가 master입니다.
온톨로지 Query Functions 실행은 등록한 함수의 API 이름과 매개변수를 사용합니다. 이 SQL API에서는 query에 SQL 문 자체를 전달합니다.
Ontology SQL
Execute Ontology SQL Query는 객체 저장소를 대상으로 하는 별도의 프리뷰 경로입니다. preview=true가 필요하며 결과를 Arrow 바이너리로 동기 반환합니다. 객체 집합 테이블 제공자, 자료형을 지정한 매개변수, 브랜치와 시나리오의 조건은 해당 실행 계약을 따릅니다.