응답 처리¶

실행 흐름 이해하기¶

기본적으로 Snowflake는 문을 동기적으로 실행하고 아래 순서도에 표시된 응답 코드 중 하나를 반환합니다.

위의 순서도에서 볼 수 있듯이:

• 성공적으로 실행된 단일 문을 제출한 경우, Snowflake는 HTTP 응답 코드 200과 결과의 행을 ResultSet 오브젝트에 반환합니다.

  ResultSet 오브젝트를 사용하여 결과를 검색 하십시오.

• 단일 요청에서 여러 문 을 제출하고 요청이 성공적으로 처리된 경우, Snowflake는 HTTP 응답 코드 200과 ResultSet 오브젝트를 반환합니다.

  ResultSet 오브젝트에는 결과의 행이 포함되어 있지 않습니다. 대신, data 필드에는 “여러 문이 성공적으로 실행되었습니다.”라는 메시지만 포함됩니다.

  데이터를 검색하려면 statementHandles 필드에서 요청의 개별 문에 대한 핸들을 가져와야 합니다. 각 문 핸들에 대해 문 실행 상태를 확인하는 요청을 보내십시오. 문 실행 상태 확인 및 데이터 검색하기 섹션을 참조하십시오.

  여러 SQL 문을 지정하는 요청의 응답을 처리하는 프로세스에 대한 자세한 내용은 요청의 각 SQL 문에 대한 결과 가져오기 를 참조하십시오.

• 문이 실행되는 데 45초 넘게 걸리거나 문이 비동기식으로 실행되도록 지정한 경우, Snowflake는 QueryStatus 오브젝트와 함께 HTTP 응답 코드 202를 반환합니다.

  QueryStatus 오브젝트의 statementStatusUrl 필드에 지정된 엔드포인트로 요청을 보내 문 실행 상태를 확인할 수 있습니다. 문 실행 상태 확인 및 데이터 검색하기 섹션을 참조하십시오.

  문 실행을 취소하려면 QueryStatus 오브젝트의 statementHandle 필드에서 문 핸들을 사용하여 /api/v2/statements/statementHandle/cancel 에 요청을 보낼 수 있습니다. SQL 문 실행 취소하기 섹션을 참조하십시오.

문 실행 상태 확인 및 데이터 검색하기¶

어떤 경우에는 문 실행 상태를 확인하기 위해 요청을 보내야 합니다.

• 실행을 위해 SQL 문을 제출 할 때 문 실행이 아직 완료되지 않았거나 비동기 쿼리를 제출한 경우 Snowflake는 202 응답 코드를 반환합니다.

  문이 실행을 완료했는지 확인하려면 문 상태를 확인하는 요청을 보내야 합니다.

• 단일 요청에서 여러 SQL 문을 제출 한 경우, 문 상태를 확인하는 요청을 보내 각 개별 문에 대한 결과를 가져옵니다.

이러한 두 경우 모두에서 사용자는 /api/v2/statements/ 엔드포인트에 GET 요청을 보내고 URL 경로 끝에 경로 매개 변수로 문 핸들을 추가합니다. 자세한 내용은 GET /api/v2/statements/{statementHandle} 섹션을 참조하십시오.

GET /api/v2/statements/{statementHandle}

{statementHandle} 은 확인하려는 문에 대한 핸들입니다. 문 핸들을 가져오려면 다음을 수행하십시오.

• 202 응답 코드가 포함된 응답을 받은 경우, 응답 본문에 QueryStatus 오브젝트가 포함됩니다. 이 오브젝트의 statementHandle 필드에서 문 핸들을 가져올 수 있습니다.

  이 오브젝트의 statementStatusUrl 필드에서 요청에 대한 전체 URL을 가져올 수도 있습니다.

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

  Copy

• 여러 SQL 문을 포함하는 요청을 제출한 경우, 응답 본문에는 statementHandles 필드가 포함된 ResultSet 오브젝트가 포함됩니다. 이 필드에서 개별 문에 대한 핸들을 가져올 수 있습니다.

  {
    ...
    "statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
    ...
  }
  

  Copy

예를 들어, 다음 curl 명령은 e4ce975e-f7ff-4b5e-b15e-bf25f59371ae 핸들을 사용하여 문 상태를 확인합니다.

curl -i -X GET \
    -H "Authorization: Bearer <jwt>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "User-Agent: myApplicationName/1.0" \
    -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
    "https://<account_identifier>.snowflakecomputing.com/api/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"

여기서,

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

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

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

상태 확인 요청을 보내면 Snowflake는 아래 순서도에 표시된 응답 코드 중 하나를 반환합니다.

위의 순서도에서 볼 수 있듯이:

• 문이 성공적으로 실행되면 Snowflake는 HTTP 응답 코드 200과 결과의 행을 ResultSet 오브젝트에 반환합니다.

  ResultSet 오브젝트를 사용하여 결과를 검색 하십시오.

• 문이 실행을 완료하지 않은 경우, Snowflake는 QueryStatus 오브젝트와 함께 HTTP 응답 코드 202를 반환합니다.

  이 오브젝트를 사용하여 문 실행 상태를 확인 하십시오.

• 문을 실행할 때 오류가 발생하면 Snowflake는 QueryFailureStatus 오브젝트와 함께 HTTP 응답 코드 422를 반환합니다.

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

응답에서 결과 가져오기¶

실행을 위해 SQL 문을 제출 하거나 문 실행 상태를 확인 하는 경우, Snowflake는 문이 성공적으로 실행된 경우 응답 본문에 ResultSet 오브젝트를 반환합니다.

Snowflake API는 파티션의 데이터를 반환합니다. Snowflake는 반환되는 각 파티션의 크기와 파티션 수를 결정합니다. 파티션의 크기는 가변적이며 특정 SQL 쿼리에 대해 Snowflake에서 반환되는 데이터의 양을 기반으로 합니다.

요청을 제출하면 이 응답의 본문에 partitionInfo 필드가 포함됩니다. 이 필드에는 각각 데이터의 파티션을 설명하는 오브젝트 배열이 포함됩니다. 이 첫 번째 오브젝트는 이 응답에서 반환되는 데이터의 파티션을 설명합니다. 나머지 오브젝트는 partition=partition_number 와 함께 후속 요청을 제출하여 검색할 수 있는 추가 파티션을 설명합니다.

배열의 각 오브젝트는 파티션의 행 수와 크기를 지정합니다. 애플리케이션은 이 파티션 메타데이터를 사용하여 후속 요청에 대해 반환되는 파티션의 처리 방법을 결정할 수 있습니다.

다음은 응답의 일부를 예로 보여줍니다.

{
  "code": "090001",
  "statementHandle": "536fad38-b564-4dc5-9892-a4543504df6c",
  "sqlState": "00000",
  "message": "successfully executed",
  "createdOn": 1597090533987,
  "statementStatusUrl": "/api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c",
  "resultSetMetaData" : {
    "numRows" : 50000,
    "format" : "jsonv2",
    "partitionInfo" : [ {
      "rowCount" : 12288,
      "uncompressedSize" : 124067,
      "compressedSize" : 29591
    }, {
      "rowCount" : 37712,
      "uncompressedSize" : 414841,
      "compressedSize" : 84469
    }],
  },
  "data": [
    ["customer1", "1234 A Avenue", "98765", "2021-01-20
    12:34:56.03459878"],
    ["customer2", "987 B Street", "98765", "2020-05-31
    01:15:43.765432134"],
    ["customer3", "8777 C Blvd", "98765", "2019-07-01
    23:12:55.123467865"],
    ["customer4", "64646 D Circle", "98765", "2021-08-03
    13:43:23.0"]
  ]
}

결과에 대한 메타데이터 가져오기¶

응답에서 반환된 ResultSet 오브젝트에서, resultSetMetaData 필드에는 결과 세트(예: 결과 형식, 반환된 파티션 수 등)를 설명하는 ResultSet_resultSetMetaData 오브젝트가 포함됩니다.

{
 "resultSetMetaData": {
  "numRows": 1300,
  "rowType": [
   {
    "name":"ROWNUM",
    "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
   }],
  "partitionInfo": [{
    ... // Partition metadata
  }]
 }
}

  {
    "resultSetMetaData": {
    "numRows: 103477,
    "format": "jsonv2"
    "rowType": {
      ... // Column metadata.
    },
    "partitionInfo": [{
        "rowCount": 12344,
        "uncompressedSize": 14384873,
      },{
        "rowCount": 47387,
        "uncompressedSize": 76483423,
        "compressedSize": 4342748
      },{
        "rowCount": 43746,
        "uncompressedSize": 43748274,
        "compressedSize": 746323
    }]
  },
  ...
}

결과에서 데이터 가져오기¶

응답의 ResultSet 오브젝트에서 결과는 data 필드에 있습니다. data 필드에는 JSON 문자열 배열의 배열이 포함됩니다. 예:

{
  ...
  "data": [
    ["customer1", "1234 A Avenue", "98765", "2021-01-20 12:34:56.03459878"],
    ["customer2", "987 B Street", "98765", "2020-05-31 01:15:43.765432134"],
    ["customer3", "8777 C Blvd", "98765", "2019-07-01 23:12:55.123467865"],
    ["customer4", "64646 D Circle", "98765", "2021-08-03 13:43:23.0"]
  ],
  ...
}

배열 내의 각 배열에는 행에 대한 데이터가 포함됩니다. 각 배열의 요소는 행의 데이터를 나타냅니다.

결과 세트의 데이터는 열의 Snowflake 데이터 타입과 관계없이, 문자열로 표현된 JSON으로 인코딩됩니다.

예를 들어, NUMBER 열의 값 1.0 은 문자열 "1.0" 으로 반환됩니다. 다른 예로, 타임스탬프는 Epoch 이후의 시간(나노초)으로 반환됩니다. 예를 들어, 2021년 1월 28일 목요일 10:09:37.123456789 PM의 타임스탬프는 "1611871777123456789" 로 반환됩니다.

사용자는 문자열을 적절한 데이터 타입으로 변환할 책임이 있습니다.

Snowflake는 Snowflake 데이터 타입 에 따라 값을 다음 형식의 문자열로 반환합니다(POST 제출 문 요청에 출력 형식 매개 변수 가 지정되지 않은 경우).

INT / NUMBER:

문자열의 10진수입니다.

FLOAT:

문자열의 정수 또는 부동 소수점입니다.

VARCHAR:

문자열.

BINARY:

문자열의 16진수입니다.

BOOLEAN:

문자열의 “false” 또는 “true”입니다.

DATE:

Epoch 이후의 시간(일)에 대한 정수 값(문자열)입니다(예: 18262).

TIME, TIMESTAMP_LTZ, TIMESTAMP_NTZ:

Epoch 이후의 시간(초)에 대한 부동 소수점 값(소수점 9자리 포함)입니다(예: 82919.000000000).

TIMESTAMP_TZ:

Epoch 이후의 시간(초)에 대한 부동 소수점 값(소수점 9자리 포함)으로, 그 뒤에 공백 및 타임존 오프셋(분 단위)이 나열됩니다(예: 1616173619000000000 960).

추가 파티션 검색하기¶

Snowflake SQL API는 파티션의 데이터를 반환합니다. 첫 번째 파티션은 JSON 형식으로 반환되며, 특정 쿼리에 대해 반환된 모든 파티션에 대한 메타데이터를 포함합니다. 애플리케이션은 이 파티션 메타데이터를 사용하여 후속 요청에 대해 반환되는 파티션의 처리 방법을 결정할 수 있습니다.

데이터의 첫 번째 파티션을 포함한 응답을 받은 후, partition=partition_number 와 함께 요청을 제출하여 나머지 파티션을 가져올 수 있으며, 여기서 partition_number 는 반환할 데이터의 파티션을 식별하는 번호입니다. 파티션 번호 0 은 초기 요청에서 반환되는 데이터의 첫 번째 파티션을 식별합니다.

예를 들어, 데이터의 첫 번째 파티션을 수신한 후, 파티션 매개 변수를 1 로 설정한 요청을 제출하여 두 번째 데이터 파티션을 얻을 수 있습니다.

GET /api/v2/statements/<handle>?partition=1

GET /api/v2/statements/<handle>?partition=partition_number 요청에 대한 응답의 본문에 JSON 데이터가 압축된 형식(gzip 사용)으로 포함됩니다.

응답에는 응답 본문이 압축되었음을 나타내는 HTTP 헤더 Content-Encoding: gzip 이 포함됩니다.

이러한 응답은 메타데이터를 포함하지 않습니다. 모든 파티션에 대한 메타데이터는 첫 번째 파티션에서 제공됩니다.

SQL NULL 값을 문자열로서 반환하기¶

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

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

이러한 값을 대신 "null" 문자열로서 반환하려는 경우, POST 요청에서 nullable 쿼리 매개 변수를 false 로 설정하여 실행을 위해 SQL 문을 제출합니다. 예:

POST /api/v2/statements?nullable=false

이는 SQL NULL 값을 "null" 로 반환합니다.

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

쿼리 결과 출력 형식 지정하기¶

Snowflake SQL API는 출력 형식 지정을 위한 매개 변수를 지원합니다(예: 날짜, 시간 및 타임스탬프에 대한 세션 매개 변수).

예를 들어, 기본적으로 2019-03-27과 같은 DATE 값은 “17982”로 반환됩니다(2019-03-27은 epoch로부터 17,982일 후임). 요청에서 DATE_OUTPUT_FORMAT이 “MM/DD/YY”여야 한다고 지정하는 경우:

{
  "statement": "select date_column from mytable",
  "resultSetMetaData": {
    "format": "jsonv2",
  },
  "parameters": {
    "DATE_OUTPUT_FORMAT": "MM/DD/YYYY"
  }
  ...
}

DATE 값은 “03/ 27/2019”로 반환됩니다.

요청 본문의 parameters 필드에서, 데이터의 출력 형식을 결정하는 다음 매개 변수를 설정할 수 있습니다.

• BINARY_OUTPUT_FORMAT

• DATE_OUTPUT_FORMAT

• TIME_OUTPUT_FORMAT

• TIMESTAMP_LTZ_OUTPUT_FORMAT

• TIMESTAMP_NTZ_OUTPUT_FORMAT

• TIMESTAMP_TZ_OUTPUT_FORMAT

• TIMESTAMP_OUTPUT_FORMAT

• TIMEZONE

resultSet 오브젝트에 행 번호 포함하기¶

행 번호는 결과 세트에 반환되지 않습니다. 응답에 행 번호를 포함하려면 쿼리에서 SEQUENCE 또는 ROW_NUMBER 윈도우 함수를 호출하여 행 번호를 생성하십시오.