Snowflake SQL API 참조

이 항목은 SQL API에 대한 작업, 요청, 응답을 설명합니다.

이 항목의 내용:

작업

POST /api/v2/statements

실행을 위해 하나 이상의 SQL 문을 제출하려면 /api/v2/statements 에 POST 요청을 보내십시오. 문이 비동기적으로 실행되도록 지정할 수 있습니다.

요청 구문

POST /api/v2/statements
(request body)
Copy

쿼리 매개 변수

매개 변수

설명

requestId

(선택 사항) API 요청의 고유 ID(UUID)입니다. SQL 문 실행 요청 다시 제출하기 섹션을 참조하십시오.

async

(선택 사항) 문을 비동기적으로 실행하고 문 핸들을 반환하려면 true 로 설정하십시오.

매개 변수를 지정하지 않거나 false로 설정하는 경우, 문이 실행된 후 45초 이내에 실행이 완료되면 결과가 반환됩니다. 문 실행을 완료하는 데 시간이 더 오래 걸리면 문 핸들이 반환됩니다.

nullable

(선택 사항) SQL NULL 값을 null 값이 아닌 "null" 문자열로 반환하려면 false 로 설정하십시오.

참고

GET 요청에서 이 매개 변수를 지정할 수 없습니다.

기본적으로 SQL NULL 값은 다음과 같이 null 값으로 반환됩니다.

"data" : [ [ null ], ... ]
Copy

이 쿼리 매개 변수를 false로 설정합니다(예: /api/v2/statements?nullable=false 는 SQL NULL 값을 다음과 같이 "null" 문자열로 반환합니다.

"data" : [ [ "null" ], ... ]
Copy

헤더 요청

요청에는 모든 작업에 대한 요청 헤더 에 나열된 헤더가 포함되어야 합니다.

요청 본문

(필수) 요청 본문은 /api/v2/statements/ 에 대한 POST 요청 본문 에 지정된 오브젝트를 포함해야 합니다.

응답

이 작업은 아래 나열된 응답 코드를 반환할 수 있습니다.

코드

설명

200

문이 성공적으로 실행되었습니다.

이 응답 코드의 경우, 응답에는 다음 헤더가 있을 수 있습니다.

요청에 단일 SQL 문이 제출된 경우, 응답 본문에는 요청된 데이터가 포함된 ResultSet 오브젝트가 포함됩니다.

참고

응답의 code 필드가 391908 로 설정된 경우, 결과 세트가 너무 커서 . 응답에 전체 결과 세트가 포함되지 않습니다.

다음은 결과가 단일 파티션에서 반환되는 단일 SQL 문에 대한 응답의 예입니다. {handle} 은 문 핸들이고 {id1}, {id2}, {id3} 은 고유하게 생성된 요청 ID입니다.

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:06:24 GMT
Content-Type: application/json
Link:
  </api/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=0>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 4,
    "format" : "jsonv2",
    "rowType" : [ {
      "name" : "COLUMN1",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 4,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16,
      "collation" : null
    }, {
      "name" : "COLUMN2",
      "database" : "",
      "schema" : "",
      "table" : "\"VALUES\"",
      "scale" : 0,
      "precision" : 1,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    } ],
    "partitionInfo": [{
      "rowCount": 4,
      "uncompressedSize": 1438,
    }]
  },
  "data" : [ [ "test", "2" ], [ "test", "3" ], [ "test", "4" ], [ "test", "5" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id3}&partition=0",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151584132
}
Copy

다음은 여러 파티션에서 결과를 반환해야 하는 단일 SQL 문에 대한 응답의 예입니다. 여기서 {handle} 은 문 핸들이고 {id1}, {id2}, {id3}, {id4} 는 고유하게 생성된 요청 ID입니다.

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:08:15 GMT
Content-Type: application/json
Link:
  </api/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=1>; rel="next",
  </api/v2/statements/{handle}?requestId={id3}&partition=1>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 56090,
    "format" : "jsonv2",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
      "rowCount": 43746,
      "uncompressedSize": 43748274,
      "compressedSize": 746323
    }]
  },
  "data" : [ [ "0", "QqKow2xzdJ....." ],.... [ "98", "ZugTcURrcy...." ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id4}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}
Copy

요청에 단일 SQL 문이 제출된 경우, 응답 본문에는 여러 문의 실행 상태에 대한 세부 정보가 있는 ResultSet 오브젝트가 포함되어 있습니다.

이 경우, 응답에는 요청된 데이터가 포함되지 않습니다. 대신, data 필드에는 《여러 문이 성공적으로 실행되었습니다.》라는 메시지만 포함됩니다.

응답에는 개별 문의 결과를 검색 하는 데 사용할 수 있는 문 핸들의 배열인 statementHandles 필드가 포함됩니다.

다음은 여러 SQL 문을 지정하는 요청에 대한 응답의 예입니다. 여기서

  • {handle} 은 문 세트에 대한 문 핸들입니다.

  • {handle1}, {handle2}, {handle3} 은 요청의 개별 SQL 문에 대한 핸들입니다.

  • {id1}, {id2}, {id3} 은 고유하게 생성된 요청 ID입니다.

HTTP/1.1 200 OK
Date: Mon, 31 May 2021 22:50:31 GMT
Content-Type: application/json
Link:
  </api/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=1>; rel="last"

{
  "resultSetMetaData" : {
  "numRows" : 56090,
  "format" : "jsonv2",
  "rowType" : [ {
      "name" : "multiple statement execution",
      "database" : "",
      "schema" : "",
      "table" : "",
      "type" : "text",
      "scale" : null,
      "precision" : null,
      "byteLength" : 16777216,
      "nullable" : false,
      "collation" : null,
      "length" : 16777216
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
     "rowCount": 43746,
     "uncompressedSize": 43748274,
     "compressedSize": 746323
    }]
  },
  "data" : [ [ "Multiple statements executed successfully." ] ],
  "code" : "090001",
  "statementHandles" : [ "{handle1}", "{handle2}", "{handle3}" ],
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id3}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1622501430333
}
Copy

202

문 실행이 아직 진행 중입니다. GET /api/v2/statements/{statementHandle} 을 사용하여 문 실행 상태를 확인하십시오. 자세한 내용은 GET /api/v2/statements/{statementHandle} 섹션을 참조하십시오.

응답 본문에는 문 실행 상태에 대한 세부 정보가 있는 QueryStatus 오브젝트가 포함되어 있습니다.

다음은 응답의 예입니다.

HTTP/1.1 202 Accepted
Date: Tue, 04 May 2021 18:12:37 GMT
Content-Type: application/json
Content-Length: 285
{
  "code" : "333334",
  "message" :
      "Asynchronous execution in progress. Use provided query id to perform query monitoring and management.",
  "statementHandle" : "019c06a4-0000-df4f-0000-00100006589e",
  "statementStatusUrl" : "/api/v2/statements/019c06a4-0000-df4f-0000-00100006589e"
}
Copy

408

문 실행이 제한 시간을 초과했습니다. 문 실행이 취소되었습니다.

응답 본문에는 문 실행 취소에 대한 세부 정보가 있는 QueryStatus 오브젝트가 포함되어 있습니다.

422

문을 실행할 때 오류가 발생했습니다. 자세한 내용은 오류 코드 및 오류 메시지를 확인하십시오.

응답 본문에는 오류에 대한 세부 정보가 있는 QueryFailureStatus 오브젝트가 포함되어 있습니다.

다음은 응답의 예입니다.

HTTP/1.1 422 Unprocessable Entity
Date: Tue, 04 May 2021 20:24:11 GMT
Content-Type: application/json
{
  "code" : "000904",
  "message" : "SQL compilation error: error line 1 at position 7\ninvalid identifier 'AFAF'",
  "sqlState" : "42000",
  "statementHandle" : "019c0728-0000-df4f-0000-00100006606e"
}
Copy

이 작업에서 반환된 다른 응답 코드는 모든 작업에 대한 응답 코드 를 참조하십시오.

GET /api/v2/statements/{statementHandle}

문 실행 상태를 확인하려면 /api/v2/statements/{statementHandle} 에 GET 요청을 보내십시오. 문이 성공적으로 실행되면 응답 본문에는 요청된 데이터가 있는 ResultSet 오브젝트가 포함됩니다.

요청 구문

GET /api/v2/statements/{statementHandle}
Copy

경로 매개 변수

매개 변수

설명

statementHandle

(필수) 확인하려는 문의 핸들입니다. 문 실행 요청 에 대한 응답으로 반환된 QueryStatus 오브젝트에서 이 핸들을 가져올 수 있습니다.

쿼리 매개 변수

requestId

(선택 사항) API 요청의 고유 ID(UUID)입니다. SQL 문 실행 요청 다시 제출하기 섹션을 참조하십시오.

partition

(선택 사항) 반환할 파티션 번호입니다. 각 파티션의 크기는 Snowflake에 의해 결정됩니다.

자세한 내용은 응답에서 결과 가져오기 섹션을 참조하십시오.

헤더 요청

요청에는 모든 작업에 대한 요청 헤더 에 나열된 헤더가 포함되어야 합니다.

응답

이 작업은 아래 나열된 응답 코드를 반환할 수 있습니다.

코드

설명

200

문이 성공적으로 실행되었습니다.

이 응답 코드의 경우, 응답에는 다음 헤더가 있을 수 있습니다.

응답의 본문에는 요청된 데이터를 포함하는 ResultSet 오브젝트가 있습니다.

다음은 응답의 예입니다. 여기서 {handle} 은 문 핸들이고 {id1}, {id2}, {id3}, {id4}, {id5}} 는 고유하게 생성된 요청 ID입니다.

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 20:25:46 GMT
Content-Type: application/json
Link:
  </api/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=0>; rel="prev",
  </api/v2/statements/{handle}?requestId={id3}&partition=1>; rel="next",
  </api/v2/statements/{handle}?requestId={id4}&partition=10>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 10000,
    "format" : "jsonv2",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
      "rowCount": 43746,
      "uncompressedSize": 43748274,
      "compressedSize": 746323
    }]
  },
  "data" : [ [ "10", "lJPPMTSwps......" ], ... [ "19", "VJKoHmUFJz......" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id5}&partition=10",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}
Copy

202

문 실행이 아직 진행 중입니다. 요청을 반복하여 문 실행 상태를 확인하십시오.

응답 본문에는 문 실행 상태에 대한 세부 정보가 있는 QueryStatus 오브젝트가 포함되어 있습니다.

다음은 응답의 예입니다.

HTTP/1.1 202 Accepted
Date: Tue, 04 May 2021 22:31:33 GMT
Content-Type: application/json
Content-Length: 285
{
  "code" : "333334",
  "message" :
      "Asynchronous execution in progress. Use provided query id to perform query monitoring and management.",
  "statementHandle" : "019c07a7-0000-df4f-0000-001000067872",
  "statementStatusUrl" : "/api/v2/statements/019c07a7-0000-df4f-0000-001000067872"
}
Copy

422

문을 실행할 때 오류가 발생했습니다. 자세한 내용은 오류 코드 및 오류 메시지를 확인하십시오.

응답 본문에는 오류에 대한 세부 정보가 있는 QueryFailureStatus 오브젝트가 포함되어 있습니다.

이 작업에서 반환된 다른 응답 코드는 모든 작업에 대한 응답 코드 를 참조하십시오.

POST /api/v2/statements/{statementHandle}/cancel

문 실행을 취소하려면 /api/v2/statements/{statementHandle}/cancel 에 POST 요청을 보내십시오.

요청 구문

POST /api/v2/statements/{statementHandle}/cancel
Copy

경로 매개 변수

매개 변수

설명

statementHandle

(필수) 확인하려는 문의 핸들입니다. 문 실행 요청 에 대한 응답으로 반환된 QueryStatus 오브젝트에서 이 핸들을 가져올 수 있습니다.

쿼리 매개 변수

매개 변수

설명

requestId

(선택 사항) API 요청의 고유 ID(UUID)입니다. SQL 문 실행 요청 다시 제출하기 섹션을 참조하십시오.

헤더 요청

요청에는 모든 작업에 대한 요청 헤더 에 나열된 헤더가 포함되어야 합니다.

응답

이 작업은 아래 나열된 응답 코드를 반환할 수 있습니다.

코드

설명

200

문 실행이 성공적으로 취소되었습니다.

응답 본문에는 문 취소에 대한 정보가 있는 CancelStatus 오브젝트가 포함되어 있습니다.

다음은 응답의 예입니다.

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 22:52:15 GMT
Content-Type: application/json
Content-Length: 230
{
  "code" : "000604",
  "sqlState" : "57014",
  "message" : "SQL execution canceled",
  "statementHandle" : "019c07bc-0000-df4f-0000-001000067c3e",
  "statementStatusUrl" : "/api/v2/statements/019c07bc-0000-df4f-0000-001000067c3e"
}
Copy

422

문을 실행할 때 오류가 발생했습니다. 자세한 내용은 오류 코드 및 오류 메시지를 확인하십시오.

응답 본문에는 오류에 대한 세부 정보가 있는 QueryFailureStatus 오브젝트가 포함되어 있습니다.

다음은 응답의 예입니다.

HTTP/1.1 422 Unprocessable Entity
Date: Tue, 04 May 2021 22:52:49 GMT
Content-Type: application/json
Content-Length: 183
{
  "code" : "000709",
  "message" : "Statement 019c07bc-0000-df4f-0000-001000067c3e not found",
  "sqlState" : "02000",
  "statementHandle" : "019c07bc-0000-df4f-0000-001000067c3e"
}
Copy

이 작업에서 반환된 다른 응답 코드는 모든 작업에 대한 응답 코드 를 참조하십시오.

모든 작업에 대한 요청 헤더

다음 요청 헤더는 모든 작업에 적용됩니다.

헤더

필수 또는 선택 사항 여부

설명

Authorization

필수

Bearer 로 설정하고, 그 뒤에는 Snowflake에 인증하는 데 사용되는 토큰을 설정하십시오.

  • 키 페어 인증 의 경우, 생성된 JWT를 토큰으로 사용하십시오.

  • OAuth 의 경우, 생성된 OAuth 토큰을 토큰으로 사용하십시오.

예:

Authorization: Bearer token

서버에 인증하기 섹션을 참조하십시오.

Accept

필수

응답 본문에서 허용되는 미디어 유형(MIME 유형) 목록으로 설정하십시오. application/json 유형을 포함하십시오(또는 모든 유형이 허용되는 경우 */* 로 설정).

Content-Type

필수

요청 본문의 미디어 유형(MIME 유형)으로 설정하십시오. application/json 으로 설정하십시오.

User-Agent

필수

애플리케이션의 이름과 버전으로 설정하십시오(예: applicationName/applicationVersion). RFC 7231 을 준수하는 값을 사용해야 합니다.

X-Snowflake-Authorization-Token-Type

키 페어 인증의 경우 필수

OAuth의 경우 선택 사항

키 페어 인증 을 사용하는 경우, 이 헤더는 필수 입니다. 이 헤더를 KEYPAIR_JWT 로 설정해야 합니다.

인증에 OAuth 를 사용하는 경우, 이 헤더는 선택 사항입니다. (이 헤더를 설정하려면 OAUTH 로 설정하십시오.)

요청 본문의 오브젝트 유형

/api/v2/statements/ 에 대한 POST 요청 본문

/api/v2/statements/ 엔드포인트에 대한 POST 요청 본문(POST /api/v2/statements 참조)은 실행할 SQL 문, 문 컨텍스트, 결과 세트의 데이터 형식을 지정하는 데 사용하는 JSON 오브젝트입니다. 문을 실행하기 위해 요청 본문에서 이 오브젝트를 사용합니다.

필드

필드

설명

statement

(선택 사항) 실행할 SQL 문입니다. 지원되거나 지원되지 않는 문 목록은 SQL API의 제한 사항 를 참조하십시오.

유형: 문자열

timeout

(선택 사항) 문 실행의 시간 제한(초)입니다. 문 실행이 지정된 시간 제한보다 오래 걸리면 실행이 자동으로 취소됩니다. 시간 제한을 최댓값(604800초)으로 설정하려면 시간 제한을 0으로 설정하십시오. 이 필드가 설정되지 않은 경우, STATEMENT_TIMEOUT_IN_SECONDS 매개 변수로 지정된 시간 제한이 사용됩니다.

유형: 64비트 부호 있는 정수

예: 10

database

(선택 사항) 문이 실행되어야 하는 데이터베이스입니다. 이 필드의 값은 대/소문자를 구분합니다.

이 필드를 생략할 경우 SQL API는 DEFAULT_NAMESPACE 사용자 속성 의 값에서 데이터베이스를 사용합니다.

유형: 문자열

예: TESTDB

schema

(선택 사항) 문이 실행되어야 하는 스키마입니다. 이 필드의 값은 대/소문자를 구분합니다.

이 필드를 생략할 경우 SQL API는 DEFAULT_NAMESPACE 사용자 속성 의 값에서 스키마를 사용합니다.

유형: 문자열

예: TESTSCHEMA

warehouse

(선택 사항) 문을 실행할 때 사용할 웨어하우스입니다. 이 필드의 값은 대/소문자를 구분합니다.

이 필드를 생략할 경우 SQL API는 DEFAULT_WAREHOUSE 사용자 속성 의 값을 사용합니다.

유형: 문자열

예: TESTWH

role

(선택 사항) 문을 실행할 때 사용할 역할입니다. 이 필드의 값은 대/소문자를 구분합니다.

이 필드를 생략할 경우 SQL API는 DEFAULT_ROLE 사용자 속성 의 값을 사용합니다.

유형: 문자열

예: TESTROLE

bindings

(선택 사항) SQL 문의 바인드 변수 값입니다. 문을 실행할 때 Snowflake는 문의 자리 표시자(? 및 :name)를 이러한 지정된 값으로 바꿉니다.

이 필드의 형식은 SQL API의 GA 릴리스에 따라 변경될 수 있습니다.

유형: 오브젝트

예:

{"1":{"type":"FIXED","value":"123"},"2":{"type":"TEXT","value":"teststring"}}
Copy

parameters

(선택 사항) 이 요청에 대해 설정하려는 세션 매개 변수 입니다.

유형: 오브젝트(statements_parameters)

예

다음은 본문 오브젝트의 예입니다.

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

statements_parameters

statements_parameters 는 이 요청에 대해 설정하려는 세션 매개 변수 를 지정하는 데 사용하는 JSON 오브젝트입니다. 이 오브젝트는 /api/v2/statements 엔드포인트에 대한 POST 요청 본문의 parameters 필드에 있어야 합니다(/api/v2/statements/ 에 대한 POST 요청 본문 참조).

참고

SQL API는 다음 표에 나열된 세션 매개 변수만 지원합니다.

필드

필드

설명

binary_output_format

(선택 사항) BINARY-VARCHAR 변환 함수에 의해 출력으로 반환되는 VARCHAR 값의 형식을 지정합니다. 자세한 내용은 BINARY_OUTPUT_FORMAT 섹션을 참조하십시오.

유형: 문자열

예: HEX

client_result_chunk_size

(선택 사항) 다운로드할 쿼리 결과의 각 세트(또는 청크)의 최대 크기(MB 단위)를 지정합니다. 자세한 내용은 CLIENT_RESULT_CHUNK_SIZE 섹션을 참조하십시오.

유형: 정수

예: 100

date_output_format

(선택 사항) DATE 데이터 타입의 표시 형식을 지정합니다. 자세한 내용은 DATE_OUTPUT_FORMAT 섹션을 참조하십시오. 매개 변수를 사용하여 쿼리 결과의 출력 형식을 결정하는 자세한 방법은 쿼리 결과 출력 서식 지정하기 를 참조하십시오.

유형: 문자열

예: YYYY-MM-DD

multi_statement_count

(요청에 둘 이상의 SQL 문을 지정할 때 필수) 다중 문 기능을 사용할 때 요청에 제출할 SQL 문 수를 지정합니다. 유효한 값은 다음과 같습니다.

  • 0: 다양한 수의 문이 요청에 포함될 수 있음을 나타냅니다.

  • 1: 단일 SQL 문이 요청에 포함될 수 있음을 나타냅니다. MULTI_STATEMENT_COUNT 필드를 지정하지 않은 경우 사용되는 기본값입니다.

  • > 1: 요청에서 제출된 SQL 문 수를 나타냅니다. 이 숫자는 statement 필드에 지정된 문의 수와 일치해야 합니다.

유형: 문자열

예: 2

query_tag

(선택 사항) SQL 문과 연결하려는 쿼리 태그입니다. 자세한 내용은 QUERY_TAG 매개 변수 를 참조하십시오.

유형: 문자열

예: tag-1234

rows_per_resultset

(선택 사항) 결과 세트에서 반환되는 최대 행 수를 지정하며, 기본값인 0은 최대값이 없음을 의미합니다. 자세한 내용은 ROWS_PER_RESULTSET 매개 변수 를 참조하십시오.

유형: 정수

예: 200

time_output_format

(선택 사항) TIME 데이터 타입의 표시 형식을 지정합니다. 자세한 내용은 TIME_OUTPUT_FORMAT 섹션을 참조하십시오. 매개 변수를 사용하여 쿼리 결과의 출력 형식을 결정하는 자세한 방법은 쿼리 결과 출력 서식 지정하기 를 참조하십시오.

유형: 문자열

예: HH24:MI:SS

timestamp_ltz_output_format

(선택 사항) TIMESTAMP_LTZ 데이터 타입의 표시 형식을 지정합니다. 자세한 내용은 TIMESTAMP_LTZ_OUTPUT_FORMAT 섹션을 참조하십시오. 매개 변수를 사용하여 쿼리 결과의 출력 형식을 결정하는 자세한 방법은 쿼리 결과 출력 서식 지정하기 를 참조하십시오.

유형: 문자열

예: YYYY-MM-DD HH24:MI:SS.FF3

timestamp_ntz_output_format

(선택 사항) TIMESTAMP_NTZ 데이터 타입의 표시 형식을 지정합니다. 자세한 내용은 TIMESTAMP_NTZ_OUTPUT_FORMAT 섹션을 참조하십시오. 매개 변수를 사용하여 쿼리 결과의 출력 형식을 결정하는 자세한 방법은 쿼리 결과 출력 서식 지정하기 를 참조하십시오.

유형: 문자열

예: YYYY-MM-DD HH24:MI:SS.FF3

timestamp_output_format

(선택 사항) TIMESTAMP 데이터 타입 별칭의 표시 형식을 지정합니다. 자세한 내용은 TIMESTAMP_OUTPUT_FORMAT 섹션을 참조하십시오. 매개 변수를 사용하여 쿼리 결과의 출력 형식을 결정하는 자세한 방법은 쿼리 결과 출력 서식 지정하기 를 참조하십시오.

유형: 문자열

예: YYYY-MM-DD HH24:MI:SS.FF3 TZHTZM

timestamp_tz_output_format

(선택 사항) TIMESTAMP_TZ 데이터 타입의 표시 형식을 지정합니다. 자세한 내용은 TIMESTAMP_TZ_OUTPUT_FORMAT 섹션을 참조하십시오. 매개 변수를 사용하여 쿼리 결과의 출력 형식을 결정하는 자세한 방법은 쿼리 결과 출력 서식 지정하기 를 참조하십시오.

유형: 문자열

예: YYYY-MM-DD HH24:MI:SS.FF3

timezone

(선택 사항) 문을 실행할 때 사용할 타임존입니다. 자세한 내용은 TIMEZONE 매개 변수 를 참조하십시오.

유형: 문자열

예: america/los_angeles

use_cached_result

(선택 사항) 원래 결과가 만료되지 않는 한 같은 쿼리의 연속 호출 간에 쿼리 결과를 재사용할 수 있는지 여부입니다. 자세한 내용은 USE_CACHED_RESULT 매개 변수 를 참조하십시오.

유형: 문자열

예: true

모든 작업에 대한 응답 코드

이 섹션에는 모든 작업에 적용되는 응답 코드가 나열됩니다.

코드

설명

400

잘못된 요청입니다.

요청 페이로드가 잘못되었거나 형식이 잘못되었습니다. 이는 애플리케이션이 올바른 요청 페이로드를 보내지 않은 경우에 발생합니다. 응답 본문에는 오류 코드와 실제 원인을 나타내는 메시지가 포함될 수 있습니다. 애플리케이션은 재시도를 위해 요청 본문을 재구성해야 합니다.

다음은 응답의 예입니다.

HTTP/1.1 400 Bad Request
Date: Tue, 04 May 2021 22:54:21 GMT
Content-Type: application/json
{
  "code" : "390142",
  "message" : "Incoming request does not contain a valid payload."
}
Copy

401

권한이 없습니다.

요청이 승인되지 않았습니다. 이는 연결된 액세스 토큰이 잘못되었거나 누락된 경우에 발생합니다. 응답 본문에는 오류 코드와 실제 원인(예: 만료된 잘못된 토큰)을 나타내는 메시지가 포함될 수 있습니다. 애플리케이션은 재시도를 위해 새 액세스 토큰을 얻어야 합니다.

서버에 인증하기 섹션을 참조하십시오.

다음은 응답의 예입니다.

HTTP/1.1 401 Unauthorized
Date: Tue, 04 May 2021 20:17:57 GMT
Content-Type: application/json
{
  "code" : "390303",
  "message" : "Invalid OAuth access token. ...TTTTTTTT"
}
Copy

403

금지되었습니다.

요청이 금지되어 있습니다. 이는 API가 사용되지 않은 경우에도 요청이 이루어지면 발생합니다.

404

찾을 수 없습니다.

요청 엔드포인트가 유효하지 않습니다. 이는 API 엔드포인트가 잘못된 경우에 발생합니다. 예를 들어, 존재하지 않는 /api/v2/hello 를 애플리케이션이 요청하면 서버는 이 코드를 반환합니다.

405

메서드가 허용되어 있지 않습니다.

지원되는 API와 요청 메서드가 일치하지 않습니다. 예를 들어, 애플리케이션이 GET 메서드를 사용하여 API를 호출하지만, 엔드포인트가 POST만 수락하는 경우에 이 상황이 발생합니다. 애플리케이션은 요청을 보낼 때 지원되는 메서드를 사용해야 합니다.

다음은 응답의 예입니다.

HTTP/1.1 405 Method Not Allowed
Date: Tue, 04 May 2021 22:55:38 GMT
Content-Length: 0
Copy

415

지원되지 않는 미디어 유형이 요청 헤더 Content-Type 에 포함되어 있습니다.

API는 application/json 만 지원합니다. Content-Type 을 지정하지 않은 경우, 요청 페이로드가 JSON으로 해석되지만, 다른 미디어 유형이 지정되면 이 오류가 반환됩니다.

429

요청이 너무 많습니다.

요청 수가 비율 제한에 도달했습니다. 애플리케이션은 API 엔드포인트로 전송되는 요청 빈도를 줄여야 합니다. 애플리케이션은 백오프를 사용하여 재시도할 수 있습니다. 기하급수적으로 지터가 발생하는 백오프가 권장됩니다.

이 응답은 서버가 너무 많은 동시 요청을 수신할 때도 발생할 수 있습니다. API에서의 동시성 제한은 Snowflake에서 적용하는 동시성 제한을 기준으로 결정됩니다.

다음은 응답의 예입니다.

HTTP/1.1 429 Too many requests
Content-Type: application/json
Content-Length: 69
{
  "code" : "390505",
  "message" : "Too many requests."
 }
Copy

500

인터넷 서버 오류입니다.

복구할 수 없는 시스템 오류가 서버에 발생했습니다. 응답 본문에는 오류 코드와 추가 지침을 위한 메시지가 포함될 수 있습니다.

503

서비스를 사용할 수 없습니다.

서버의 시간 제한으로 인해 요청이 처리되지 않았습니다. 애플리케이션은 백오프를 사용하여 재시도할 수 있습니다. 기하급수적으로 지터가 발생하는 백오프가 권장됩니다.

504

게이트웨이 시간 제한 초과입니다.

서버의 시간 제한으로 인해 요청이 처리되지 않았습니다. 애플리케이션은 백오프를 사용하여 재시도할 수 있습니다. 기하급수적으로 지터가 발생하는 백오프가 권장됩니다.

모든 작업에 대한 응답 헤더

응답에는 다음 헤더가 포함될 수 있습니다.

헤더

설명

Link

이 헤더는 문 실행 요청 및 문 실행 상태 확인 요청 에 대한 200 응답에 있습니다.

이 헤더는 결과의 다른 파티션(예: 첫 번째 파티션, 마지막 파티션 등)에 대한 링크를 제공합니다. 헤더에는 반환할 파티션(first, next, prev, last)를 지정하는 서로 다른 rel 속성 값이 있는 여러 URL 항목이 포함될 수 있습니다.

예:

Link: </api/v2/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?partition=1; rel="last">,
      </api/v2/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?partition=1; rel="next">,
      </api/v2/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?partition=0; rel="first">
Copy

응답 본문의 오브젝트 유형

CancelStatus

CancelStatus 는 문 실행 취소에 대한 정보를 포함하는 JSON 오브젝트입니다. 이 오브젝트는 취소 요청 에 대한 응답 본문에 반환됩니다.

필드

필드

설명

code

유형: 문자열

sqlState

유형: 문자열

message

예: successfully cancelled

유형: 문자열

statementHandle

실행 중인 문의 고유 식별자입니다.

유형: 문자열(UUID)

예: 536fad38-b564-4dc5-9892-a4543504df6c

statementStatusUrl

문 상태 및 결과 세트를 가져오는 URL입니다.

유형: 문자열(URL)

예: /api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c

예

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully canceled",
  "statementHandle" : "536fad38-b564-4dc5-9892-a4543504df6c",
  "statementStatusUrl" : "/api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c"
}
Copy

QueryFailureStatus

QueryFailureStatus는 문 실행 실패에 대한 정보를 포함하는 JSON 오브젝트입니다. 이 오브젝트는 문 실행 요청 에 대한 422 응답 본문에 반환됩니다.

필드

필드

설명

code

유형: 문자열

예: 0

sqlState

유형: 문자열

message

유형: 문자열

예: successfully executed

statementHandle

실행 중인 문의 고유 식별자입니다.

유형: 문자열(UUID)

예: 536fad38-b564-4dc5-9892-a4543504df6c

createdOn

문 실행이 시작된 시간을 지정하는 타임스탬프입니다. 타임스탬프는 Epoch 이후의 시간(밀리초)으로 표시됩니다.

유형: 64비트 부호 있는 정수

예: 1597090533987

statementStatusUrl

문 상태 및 결과 세트를 가져오는 URL입니다.

유형: 문자열(URL)

예: /api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c

예

{
  "code" : "002140",
  "sqlState" : "42601",
  "message" : "SQL compilation error",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
}
Copy

QueryStatus

QueryStatus 는 문 실행 상태에 대한 정보를 포함하는 JSON 오브젝트입니다. 이 오브젝트는 다음에서 반환됩니다.

필드

필드

설명

code

유형: 문자열

예: 0

sqlState

유형: 문자열

message

유형: 문자열

예: successfully executed

statementHandle

실행 중인 문의 고유 식별자입니다.

유형: 문자열(UUID)

예: 536fad38-b564-4dc5-9892-a4543504df6c

createdOn

문 실행이 시작된 시간을 지정하는 타임스탬프입니다. 타임스탬프는 Epoch 이후의 시간(밀리초)으로 표시됩니다.

유형: 64비트 부호 있는 정수

예: 1597090533987

statementStatusUrl

문 상태 및 결과 세트를 가져오는 URL입니다.

유형: 문자열(URL)

예: /api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c

예

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully executed",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
}
Copy

ResultSet

ResultSet 는 문 실행 결과를 포함하는 JSON 오브젝트입니다. 이 오브젝트는 문 실행 요청 및 문 실행 상태 확인 요청 에 대한 200 응답 본문에 반환됩니다.

필드

필드

설명

code

유형: 문자열

예: 0

sqlState

유형: 문자열

message

유형: 문자열

예: successfully executed

statementHandle

실행 중인 문의 고유 식별자입니다.

요청에 여러 문이 지정된 경우, 이 핸들은 이러한 문의 세트에 해당합니다. 요청에 있는 개별 문의 핸들에 대해서는 statementHandles 필드를 참조하십시오.

유형: 문자열(UUID)

예: 536fad38-b564-4dc5-9892-a4543504df6c

statementHandles

이 요청에 대해 실행 중인 문의 고유 식별자 배열입니다.

유형: 문자열 배열(UUID)

예: [ "019c9f9a-0502-f25e-0000-438300e0d046", "019c9f9a-0502-f25e-0000-438300e0d04a", "019c9f9a-0502-f25e-0000-438300e0d04e" ]

createdOn

문 실행이 시작된 시간을 지정하는 타임스탬프입니다. 타임스탬프는 Epoch 이후의 시간(밀리초)으로 표시됩니다.

예: 1597090533987

statementStatusUrl

문 상태 및 결과 세트를 가져오는 URL입니다.

유형: 문자열(URL)

예: /api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c

resultSetMetaData

반환된 결과 세트에 대한 메타데이터입니다.

유형: 오브젝트(ResultSet_resultSetMetaData)

data

요청에 단일 SQL 문이 포함된 경우, 이 필드에는 결과 세트 데이터가 포함됩니다.

결과 세트 형식은 JSON 배열의 배열입니다.

  • 각 배열은 단일 행에 해당합니다.

  • 행의 요소는 해당 행의 열 값에 해당합니다.

  • 데이터는 Snowflake 데이터 타입과 관계없이 JSON 문자열로 인코딩됩니다.

유형: 배열의 배열

예:

[
  ["customer1","1234 A Avenue","98765","1565481394123000000"],
  ["customer2","987 B Street","98765","1565516712912012345"],
  ["customer3","8777 C Blvd","98765","1565605431999999999"],
  ["customer4","64646 D Circle","98765","1565661272000000000"]
]
Copy

요청에 여러 SQL 문이 포함된 경우, 이 필드에는 《여러 문이 성공적으로 실행되었습니다.》라는 메시지만 포함됩니다. 요청의 각 문에 대한 결과를 검색하려면 statementHandles 필드에서 이러한 문에 대한 핸들을 가져오고, 각 문의 결과를 가져오도록 요청을 보내십시오.

stats

DML 문의 경우, 이 필드에는 작업의 영향을 받는 행 수에 대한 통계가 포함됩니다.

유형: 오브젝트(ResultSet_stats)

ResultSet_resultSetMetaData

ResultSet_resultSetMetaData 는 문 실행 결과에 대한 메타데이터를 포함하는 JSON 오브젝트입니다. 이 오브젝트는 ResultSet 오브젝트의 resultSetMetaData 필드에 있습니다.

필드

필드

설명

partition

반환할 파티션의 인덱스 번호(여기서 0 은 데이터의 첫 번째 파티션을 지정함)입니다. Snowflake는 파티션의 데이터를 반환합니다. Snowflake는 런타임에 파티션 수 및 각 파티션의 크기를 결정합니다. POST 요청에 대한 응답으로 resultSetMetaData 오브젝트에서 파티션 목록을 가져올 수 있습니다.

자세한 내용은 응답에서 결과 가져오기 섹션을 참조하십시오.

numRows

결과의 총 행 수입니다.

유형: 64비트 부호 있는 정수

예: 100

format

결과 세트의 데이터 형식입니다.

유형: 문자열

rowType

결과 세트의 열을 설명하는 ResultSet_resultSetMetaData_rowType 오브젝트의 배열입니다.

유형: ResultSet_resultSetMetaData_rowType 의 배열.

예:

[
 {"name":"ROWNUM","type":"FIXED","length":0,"precision":38,"scale":0,"nullable":false},
 {"name":"ACCOUNT_ID","type":"FIXED","length":0,"precision":38,"scale":0,"nullable":false},
 {"name":"ACCOUNT_NAME","type":"TEXT","length":1024,"precision":0,"scale":0,"nullable":false},
 {"name":"ADDRESS","type":"TEXT","length":16777216,"precision":0,"scale":0,"nullable":true},
 {"name":"ZIP","type":"TEXT","length":100,"precision":0,"scale":0,"nullable":true},
 {"name":"CREATED_ON","type":"TIMESTAMP_NTZ","length":0,"precision":0,"scale":3,"nullable":false}
]
Copy

ResultSet_resultSetMetaData_rowType

ResultSet_resultSetMetaData_rowType 은 결과 세트의 열을 설명하는 JSON 오브젝트입니다. 이러한 오브젝트의 배열은 ResultSet_resultSetMetaData 오브젝트의 rowType 필드에 있습니다.

필드

필드

설명

name

열의 이름입니다.

유형: 문자열

type

열의 Snowflake 데이터 타입 입니다.

유형: 문자열

length

열의 길이입니다.

유형: 64비트 부호 있는 정수

precision

열의 정밀도입니다.

유형: 64비트 부호 있는 정수

scale

열의 스케일입니다.

유형: 64비트 부호 있는 정수

nullable

열이 null을 허용하는지를 지정합니다.

유형: 부울

예

{
 "name":"ACCOUNT_NAME",
 "type":"TEXT",
 "length":1024,
 "precision":0,
 "scale":0,
 "nullable":false
}
Copy

ResultSet_stats

ResultSet_stats 는 DML 문 실행에 대한 통계를 포함하는 JSON 오브젝트입니다. 이 오브젝트는 ResultSet_resultSetMetaData 오브젝트의 stats 필드에 있습니다.

필드

필드

설명

numRowsInserted

삽입된 행 수입니다.

유형: 64비트 부호 있는 정수

예: 12

numRowsUpdated

업데이트된 행 수입니다.

유형: 64비트 부호 있는 정수

예: 9

numRowsDeleted

삭제된 행 수입니다.

유형: 64비트 부호 있는 정수

예: 8

numDuplicateRowsUpdated

업데이트된 중복 행 수입니다.

유형: 64비트 부호 있는 정수

예: 20
언어: 한국어