단일 요청에서 여러 SQL 문 제출하기

이 항목에서는 Snowflake SQL API에 여러 개의 문이 포함된 요청을 제출하는 방법을 설명합니다.

이 항목의 내용:

소개

어떤 경우에는 요청에 여러 SQL 문을 지정해야 할 수 있습니다. 예를 들어, 다음을 수행해야 할 수 있습니다.

  • 명시적 트랜잭션 정의

  • 요청의 문에서 세션 변수 설정 및 사용

  • 요청의 문에서 임시 테이블 만들기 및 사용

  • 요청의 문에 대한 데이터베이스, 스키마, 웨어하우스 또는 역할 변경

다음 섹션에서는 여러 SQL 문이 포함된 요청을 제출하는 방법을 설명합니다.

요청에서 여러 SQL 문 지정하기

단일 요청에서 여러 SQL 문을 제출하려면:

  • statement 필드에서 각 문 사이에 세미콜론(;)을 사용합니다.

  • parameters 필드에서 MULTI_STATEMENT_COUNT 필드를 요청의 SQL 문의 수로 설정합니다.

예:

POST /api/v2/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

{
  "statement": "alter session set QUERY_TAG='mytesttag'; select count(*) from mytable",
  ...
  "parameters": {
      "MULTI_STATEMENT_COUNT": "2"
  }
}
Copy

이 예에서 MULTI_STATEMENT_COUNT 는 제출되는 SQL 문의 수에 해당하는 2 로 설정됩니다.

statement 필드에 다양한 수의 SQL 문을 제출하려면 MULTI_STATEMENT_COUNT0 으로 설정하십시오. 이는 제출된 SQL 문의 수를 런타임 시 알 수 없는 애플리케이션에서 유용합니다.

MULTI_STATEMENT_COUNT 값이 statement 필드에 지정된 SQL 문의 수와 일치하지 않으면 SQL API는 다음 오류를 반환합니다.

Actual statement count <actual_count> did not match the desired statement count <desired_count>.
Copy

Where

  • actual_countstatement 필드에 지정된 문의 수입니다.

  • desired_countMULTI_STATEMENT_COUNT 의 값입니다.

statement 필드에 여러 SQL 문을 지정하지만 MULTI_STATEMENT_COUNT 필드를 지정하지 않은 경우, SQL API는 다음 오류를 반환합니다.

Actual statement count 3 did not match the desired statement count 1.
Copy

참고

Snowflake는 현재 다중 문 SQL 요청에서 변수 바인딩을 지원하지 않습니다.

요청의 각 SQL 문에 대한 결과 가져오기

여러 SQL 문이 있는 요청이 성공적으로 처리되는 경우, 응답에는 개별 문 실행에서 반환된 데이터가 포함되지 않습니다. 대신 응답에는 개별 문에 대한 핸들 배열이 있는 statementHandles 필드가 포함됩니다.

참고

statementHandles 필드는 statementHandle 필드와 다릅니다.

  • statementHandle 필드는 요청의 SQL 문 세트에 대한 핸들을 지정합니다.

  • statementHandles 필드는 요청의 개별 SQL 문에 대한 핸들의 배열입니다.

예를 들어, 실행할 두 개의 SQL 문을 지정하는 요청을 보낸다고 가정합니다.

POST /api/v2/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

{
  "statement": "select * from A; select * from B",
  ...
}
Copy

응답에는 개별 문에 대한 핸들 배열이 있는 statementHandles 필드가 포함됩니다.

HTTP/1.1 200 OK
...
{
  ...
  "statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
  ...
}
Copy

상태를 확인하고 개별 문에 대한 데이터를 검색하려면 /api/v2/statements/ 엔드포인트에 GET 요청을 보내고 URL 경로에 각 문에 대한 핸들을 추가하십시오. 자세한 내용은 문 실행 상태 확인 및 데이터 검색하기 섹션을 참조하십시오.

GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02412
...
Copy
GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02416
...
Copy

요청에 여러 문 지정 시 오류 처리하기

요청에 여러 SQL 문을 지정했고 문 실행 시 오류가 발생한 경우, Snowflake는 QueryFailureStatus 오브젝트와 함께 HTTP 응답 코드 422를 반환합니다.

이 오브젝트에서 오류에 대한 세부 정보 를 가져올 수 있습니다.

예를 들어 요청이 두 번째 INSERT 문에 오류가 포함된 다음 문을 지정한다고 가정합니다.

{
  "statement": "create or replace table table1 (i int); insert into table1 (i) values (1); insert into table1 (i) values ('This is not a valid integer.'); insert into table1 (i) values (2); select i from table1 order by i",
  ...
}
Copy

Snowflake는 HTTP 응답 코드 422 및 오류에 대한 세부 정보가 포함된 QueryFailureStatus 오브젝트와 함께 응답을 반환합니다.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
...
{
  "code" : "100132",
  "message" : "JavaScript execution error: Uncaught Execution of multiple statements failed on statement \"insert into table1 (i) values ...\" (at line 1, position 75).\nNumeric value 'This is not a valid integer.' is not recognized in SYSTEM$MULTISTMT at '    throw `Execution of multiple statements failed on statement {0} (at line {1}, position {2}).`.replace('{1}', LINES[i])' position 4\nstackstrace: \nSYSTEM$MULTISTMT line: 10",
  "sqlState" : "P0000",
  "statementHandle" : "019d6e97-0502-317e-0000-096d0041f036"
}
Copy

위의 예에서 오류가 있는 INSERT 문은 statement 필드 의 문자 위치 75에서 시작합니다.

오류가 있는 문 앞의 문은 성공적으로 실행됩니다(이 예에서는 CREATE TABLE 및 첫 번째 INSERT 문). 오류가 있는 문 뒤의 문은 실행되지 않습니다.