SQL 문 실행 요청 제출하기

이 항목에서는 SQL API에 요청을 제출하는 방법을 설명합니다.

이 항목의 내용:

실행할 SQL 문을 제출하려면 /api/v2/statements/ 엔드포인트에 POST 요청을 보내십시오. 자세한 내용은 POST /api/v2/statements 섹션을 참조하십시오.

POST /api/v2/statements HTTP/1.1
(request body)

요청 설정하기

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

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

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

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

    단일 요청에서 여러 문을 제출하려면 문 사이에 세미콜론(;)을 사용하십시오. 자세한 내용은 단일 요청에서 여러 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"

여기서,

이 예에서 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 역할을 사용해야 함을 지정합니다.

조직의 계정 이름을 사용하여 URL에 쿼리 제출하기(OAuth만 해당)

조직의 계정 이름을 지정하는 URL(예: myorganization-myaccount.snowflakecomputing.com)을 사용하고 OAuth로 서버를 인증하는 경우 Snowflake-Account 헤더를 사용하여 POST 요청에 계정 이름을 명시적으로 지정해야 합니다.

참고

계정 식별자에 리전(예: xy12345.us-east-2.aws.snowflakecomputing.com)이 포함되어 있거나 OAuth를 사용하여 서버를 인증하지 않는 경우 Snowflake-Account 헤더를 지정할 필요가 없습니다.

다음 curl 명령은 POST 요청에서 Snowflake-Account 헤더를 지정하는 방법을 보여줍니다.

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Agent: myApplicationName/1.0" \
  -H "X-Snowflake-Authorization-Token-Type: OAUTH" \
  -H "Snowflake-Account: xy12345" \
  --data '{"statement":"select 1", "timeout": 1000, "warehouse": "TESTWH", \
  "database": "TESTDB", "schema": "TESTSCHEMA", "role": "SYSADMIN"}' \
  "https://myorg-myaccount.snowflakecomputing.com:443/api/statements"

Snowflake-Account 헤더에 계정 별칭을 지정할 수 없습니다.

조직의 계정 이름을 포함한 URL에 이 헤더를 생략하거나 헤더에 계정 별칭을 지정하면 서버에서 다음 오류를 반환합니다.

HTTP/1.1 401 Unauthorized
{
  "code" : "390100",
  "message" : "Incorrect username or password was specified."
}

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

문에서 바인드 변수(? 자리 표시자)를 사용하려는 경우, 삽입해야 하는 값을 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 데이터 타입의 열에 데이터를 삽입할 수 없습니다.

다양한 Snowflake 데이터 타입에 대해 지원되는 바인딩 유형

Snowflake 데이터 타입

INT / NUMBER

FLOAT

VARCHAR

BINARY

BOOLEAN

DATE

TIME

TIMESTAMP_TZ

TIMESTAMP_LTZ

TIMESTAMP_NTZ

바인딩 . 유형

FIXED

정수

정수

정수

0(false) / 0이 아님(true)

REAL

정수

정수 또는 부동 소수점

정수 또는 부동 소수점

0/0이 아님

TEXT

정수

정수 또는 부동 소수점

모든 텍스트

16진수

"true"/ "false"

아래 참고 사항 참조

아래 참고 사항 참조

아래 참고 사항 참조

아래 참고 사항 참조

아래 참고 사항 참조

BINARY

16진수

BOOLEAN

true/false, 0/1

true/false

DATE

Epoch(밀리초)

Epoch(밀리초)

Epoch(밀리초)

Epoch(밀리초)

Epoch(밀리초)

TIME

Epoch(나노)

Epoch(나노)

TIMESTAMP_TZ

Epoch(나노)

Epoch(나노)

Epoch(나노)

Epoch(나노)

TIMESTAMP_LTZ

Epoch(나노)

Epoch(나노)

Epoch(나노)

Epoch(나노)

Epoch(나노)

Epoch(나노)

TIMESTAMP_NTZ

Epoch(나노)

Epoch(나노)

Epoch(나노)

Epoch(나노)

Epoch(나노)

Epoch(나노)

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

  • 바인드 변수의 값은 문자열이어야 합니다(예: 값 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를 사용하는 것은 동일한 요청을 다시 제출하고 있음을 서버에 알리는 것입니다.

참고

retry=true 매개 변수는 Snowflake가 문 기록의 문을 스캔하고 일치시켜야 하기 때문에 SQL 문 처리에 오버헤드를 추가합니다. 문 재시도가 필요한 경우에만 이 매개 변수를 사용하십시오.

맨 위로 이동