Snowflake SQL API: SQL 문 제출 프로세스 변경 사항

이 릴리스에서는 Snowflake SQL API가 SQL API의 처리 효율성 개선을 위해 고안된 변경 사항을 도입합니다.

이러한 변경 사항의 일부로, 이 문서에 설명된 대로 일부 기능이 더 이상 사용되지 않습니다.

새 SQL API 기능 활성화

주어진 요청에 대해 새 SQL API 기능을 활성화하려면 다음 예에 표시된 것처럼 resultSetMetaData의 형식 필드를 jsonv2로 설정하십시오.

{
  "statement": "select * from mytable",
  "resultSetMetaData": {
     "format": "jsonv2"
    },
  ...
 }
Copy

더 이상 사용되지 않는 기능을 결과 처리에 사용하려면 resultSetMetaData 필드를 생략하거나 형식 필드를 json으로 설정하십시오.

  • 참고: 앞으로는 SQL API가 이 새로운 기능을 기본적으로 사용할 것입니다. SQL API가 GA(일반 공급)용으로 출시되면 사용되지 않는 기능이 더 이상 지원되지 않습니다.

변경되고 사용되지 않는 기능

Snowflake SQL API는 더 이상 일관된 크기의 페이지에서 데이터를 반환하지 않습니다. 대신 SQL API는 데이터의 단일 물리적 청크인 파티션을 반환합니다. 각 파티션의 크기는 가변적이며 런타임에서 Snowflake가 자동으로 결정합니다.

이러한 변경 사항으로 다음 사항이 적용됩니다.

  • GET 요청에서 더 이상 <>nullable 매개 변수를 지정할 수 없습니다. 이 매개 변수는 실행할 SQL 문을 제출하기 위한 POST 요청에서만 지정할 수 있습니다.

    예:

    POST /api/statements?nullable=false

  • pageSize 매개 변수는 더 이상 사용되지 않습니다. Snowflake는 각 응답에서 데이터 파티션을 반환하고 반환되는 파티션의 크기를 결정합니다. 파티션의 크기는 가변적이며 특정 SQL 쿼리에 대해 Snowflake에서 반환되는 데이터의 양을 기반으로 합니다.

  • 페이지 매개 변수는 파티션 매개 변수로 바뀝니다. 페이지 매개 변수를 사용하여 반환할 데이터의 다음 페이지를 지정하는 대신, 파티션 매개 변수를 사용하여 반환할 데이터의 다음 파티션을 지정하십시오.

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

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

    GET /api/statements/<핸들>?partition=1

  • 쿼리 실행 요청을 제출하면 응답에는 데이터의 첫 번째 파티션뿐 아니라 응답 전체에 걸친 데이터의 분할 방식을 설명하는 메타데이터가 포함됩니다.

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

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

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

     {
     "resultSetMetaData": {
      "numRows: 1300,
      "format": "jsonv2"
      "rowType": {
        ... // column metadata. No change
      },
      "partitionInfo": [{
          "rowCount": 12344,
          "uncompressedSize": 14384873,
        },{
          "rowCount": 47387,
          "uncompressedSize": 76483423,
          "compressedSize": 4342748
        },{
          "rowCount": 43746,
          "uncompressedSize": 43748274,
          "compressedSize": 746323
      }]
    },
    "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"]
    ]
    }
    
    Copy
  • 이 예에서는 다음과 같습니다.

    • partitionInfo 필드의 첫 번째 오브젝트는 이 응답의 데이터 필드에 있는 데이터의 파티션을 설명합니다.

    • 두 번째 오브젝트는 47,387개의 행이 있고 요청 GET /api/statements/<핸들>?partition=1 을 보내어 검색할 수 있는 데이터의 두 번째 파티션을 설명합니다.

    • 세 번째 오브젝트는 47,386개의 행이 있고 요청 GET /api/statements/<핸들>?partition=2 을 보내어 검색할 수 있는 데이터의 세 번째 파티션을 설명합니다.

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

    응답에는 응답의 본문이 압축된 상태임을 나타내는 HTTP 헤더 Content-Encoding: gzip이 포함됩니다.

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

  • 사용되지 않는 page, pageSize, numPages 필드는 응답 본문의 resultSetMetaData 오브젝트에 더 이상 포함되지 않습니다.

    이 새로운 기능에서는 SQL API가 더 이상 데이터를 페이지로 반환하지 않습니다. 대신에 SQL API는 데이터를 파티션으로 반환하며, resultSetMetaData 오브젝트에서 partitionInfo 필드를 사용하여 파티션 수와 각 파티션의 행 수를 결정합니다.

  • 행 번호는 더 이상 결과 세트에 포함되지 않습니다.

    응답에 행 번호를 포함하려면 쿼리에서 SEQUENCE 또는 ROW_NUMBER 윈도우 함수를 호출하여 행 번호를 생성하십시오.

  • 이제 부울 값이 1 또는 0이 아닌 true 또는 false로 반환됩니다.