SQL 문 실행 요청 제출하기¶

요청 설정하기¶

요청 URL에서 쿼리 매개 변수를 다음과 같이 설정할 수 있습니다.

• 이 요청을 다른 요청과 구별하는 요청 ID를 지정합니다.

• 문을 비동기적으로 실행합니다.

요청 본문 의 경우, 다음 필드를 설정하십시오.

• 실행하려는 SQL 문으로 statement 필드를 설정하십시오. 예:

  {
    "statement": "select * from my_table",
    ...
  }
  

  Copy

  단일 요청에서 여러 문을 제출하려면 문 사이에 세미콜론(;)을 사용하십시오. 자세한 내용은 단일 요청에서 여러 SQL 문 제출하기 섹션을 참조하십시오.

• 문에 바인드 변수(? 자리 표시자)를 포함하는 경우, bindings 필드를 각 변수에 해당하는 Snowflake 데이터 타입과 값을 지정하는 오브젝트로 설정하십시오.

  자세한 내용은 문에서 바인드 변수 사용하기 섹션을 참조하십시오.

• 사용할 웨어하우스, 데이터베이스, 스키마, 역할을 지정하려면 warehouse, database, schema, role 필드를 설정하십시오.

  이 필드의 값은 대/소문자를 구분합니다.

  이러한 필드를 생략할 경우 SQL API는 사용자에 대한 해당 속성의 값을 사용합니다(즉, 사용자의 DEFAULT_WAREHOUSE, DEFAULT_NAMESPACE, DEFAULT_ROLE 속성).

• 문 실행에 대한 시간 제한을 설정하려면 timeout 필드를 최대 대기 시간(초)으로 설정하십시오. timeout 필드가 설정되지 않은 경우, STATEMENT_TIMEOUT_IN_SECONDS 매개 변수로 지정된 시간 제한이 사용됩니다.

요청의 예¶

예를 들어, 다음 curl 명령은 실행할 SQL 문을 보냅니다. 이 예에서는 request-body.json 파일을 사용하여 요청 본문을 지정합니다.

curl -i -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt>" \
    -H "Accept: application/json" \
    -H "User-Agent: myApplicationName/1.0" \
    -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
    -d "@request-body.json" \
    "https://<account_identifier>.snowflakecomputing.com/api/v2/statements"

여기서,

• jwt 는 인증을 위해 생성한 JWT 입니다.

• myApplicationName 은 애플리케이션에 대한 식별자의 예입니다.

• account_identifier 는 계정 식별자 입니다.

이 예에서 request-body.json 에는 요청 본문 이 포함되어 있습니다.

{
  "statement": "select * from T where c1=?",
  "timeout": 60,
  "database": "TESTDB",
  "schema": "TESTSCHEMA",
  "warehouse": "TESTWH",
  "role": "TESTROLE",
  "bindings": {
    "1": {
      "type": "FIXED",
      "value": "123"
    }
  }
}

위 예의 요청 본문에서:

• statement 필드는 실행할 SQL 문을 지정합니다.

  문에는 bindings 필드에 지정된 첫 번째 바인딩("1")으로 평가되는 바인드 변수 ("cl=?" 의 물음표)가 포함됩니다.

• timeout 필드는 문이 실행되는 데 서버가 60초를 허용하도록 지정합니다.

• database, schema, warehouse, role 필드는 문을 실행할 때 TESTDB 데이터베이스, TESTSCHEMA 스키마, TESTWH 웨어하우스, TESTROLE 역할을 사용해야 함을 지정합니다.

문에서 바인드 변수 사용하기¶

문에서 바인드 변수(? 자리 표시자)를 사용하려는 경우, 삽입해야 하는 값을 bindings 필드를 사용하여 지정하십시오.

이 필드를 각 바인드 변수에 대한 Snowflake 데이터 타입 및 값을 지정하는 JSON 오브젝트로 설정하십시오.

...
"statement": "select * from T where c1=?",
...
"bindings": {
  "1": {
    "type": "FIXED",
    "value": "123"
  }
},
...

바인딩하는 값의 유형에 해당하는 바인딩 유형을 선택하십시오. 예를 들어, 값이 날짜를 나타내는 문자열 (예: 2021-04-15)이고 DATE 열에 값을 삽입하려는 경우, TEXT 바인딩 유형을 사용하십시오.

다음 테이블은 이 미리 보기 릴리스의 다양한 Snowflake 데이터 타입 에 바인딩하기 위해 사용할 수 있는 type 필드의 값을 지정합니다.

• 왼쪽의 첫 번째 열은 사용할 수 있는 바인딩 유형을 지정합니다.

• 나머지 열은 데이터를 삽입할 열의 Snowflake 데이터 타입을 지정합니다.

• 각 셀은 특정 Snowflake 데이터 타입의 열에 데이터를 삽입하기 위해 바인딩 유형과 함께 사용할 수 있는 값 유형을 지정합니다.

  바인딩 유형 및 Snowflake 데이터 타입의 셀이 비어 있는 경우, 지정된 바인딩 유형을 사용하여 해당 Snowflake 데이터 타입의 열에 데이터를 삽입할 수 없습니다.

다음 사항을 참고하십시오.

• 바인드 변수의 값은 문자열이어야 합니다(예: 값 1.0의 경우 "1.0").

• DATE 바인딩 유형을 사용하는 경우, Epoch 이후의 시간(밀리초)을 지정하십시오.

• TIME 또는 TIMESTAMP* 바인딩 유형을 사용하는 경우, Epoch 이후의 시간(나노초)를 지정하십시오.

• TIMESTAMP_TZ 바인딩 유형을 사용하는 경우, Epoch 이후의 시간(나노초) 뒤에 공백 및 타임존 오프셋(분 단위)이 나열되도록 지정하십시오(예: 1616173619000000000 960).

• TEXT 바인딩 유형을 사용할 때:

  • DATE 열에 데이터를 삽입하기 위해 AUTO 감지에서 지원하는 모든 날짜 형식 을 사용할 수 있습니다.

  • TIME 열에 데이터를 삽입하기 위해 AUTO 감지에서 지원하는 모든 시간 형식 을 사용할 수 있습니다.

  • TIMEZONE* 열에 데이터를 삽입하기 위해 AUTO 감지에서 지원하는 모든 날짜-시간 형식 을 사용할 수 있습니다.

값이 Snowflake에서 지원하지 않는 형식인 경우, API는 다음 오류를 반환합니다.

{
  code: "100037",
  message: "<bind type> value '<value>' is not recognized",
  sqlState: "22018",
  statementHandle: "<ID>"
}

동시 요청 제출하기¶

Snowflake SQL API는 서버에 동시 요청 보내기를 지원합니다. API에서의 동시성 제한은 Snowflake에서 적용하는 동시성 제한을 기준으로 결정됩니다.

현재 서버 부하에 따라 서버가 현재 너무 많은 요청을 수신하고 있음을 나타내는 HTTP 429 오류를 수신할 수 있습니다.

애플리케이션이 429 오류를 올바르게 처리하도록 보장하려면 재시도 논리 내에 동시 요청을 래핑합니다.

SQL 문 실행 요청 다시 제출하기¶

어떤 경우에는 Snowflake가 API 요청에서 SQL 문을 실행했는지 명확하지 않을 수 있습니다(예: 네트워크 오류 또는 시간 제한으로 인한 경우). Snowflake가 문을 실행하지 않은 경우 Snowflake에 동일한 요청을 다시 제출하도록 선택할 수 있습니다.

그러나 Snowflake가 초기 요청에서 이미 문을 실행한 경우, 요청을 다시 제출하면 문이 두 번 실행됩니다. 일부 유형의 요청의 경우, 동일한 문을 반복적으로 실행하면 의도치 않은 결과가 발생할 수 있습니다(예: 테이블에 중복 데이터 삽입).

요청을 다시 제출할 때 Snowflake가 동일한 문을 두 번 실행하지 않도록 요청 ID를 사용하여 해당 요청을 다른 요청과 구별할 수 있습니다. 다시 제출된 요청의 retry=true 매개 변수와 함께 초기 요청에서 동일한 요청 ID를 지정하는 경우, 문이 이미 성공적으로 실행된 경우 Snowflake는 해당 문을 다시 실행하지 않습니다.

요청 ID를 지정하려면 UUID(Universally Unique Identifier) 를 생성합니다. 그런 다음 requestId 쿼리 매개 변수에 이 식별자를 포함할 수 있습니다. 다음 예와 같이 요청의 일부로 retry=true 매개 변수도 지정해야 합니다.

POST /api/v2/statements?requestId=ea7b46ed-bdc1-8c32-d593-764fcad64e83&retry=true HTTP/1.1

Snowflake가 요청을 처리하지 못하는 경우, 동일한 요청을 동일한 요청 ID로 다시 제출할 수 있습니다. 동일한 요청 ID를 사용하는 것은 동일한 요청을 다시 제출하고 있음을 서버에 알리는 것입니다.