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 リクエストでは<>Null許容パラメーターを指定できなくなりました。これは、実行のために SQL ステートメントを送信する POST リクエストでのみ指定できます。

    例:

    POST /api/statements?nullable=false

  • pageSize パラメーターは廃止されました。Snowflakeは各応答でデータのパーティションを返し、Snowflakeは返されるパーティションのサイズを決定します。パーティションのサイズは可変で、特定の SQL クエリに対してSnowflakeから返されるデータの量に基づいています。

  • ページパラメーターは、パーティションパラメーターに置き換えられます。ページパラメーターを使用して返すデータの次のページを指定するのではなく、パーティションパラメーターを使用して返すデータの次のパーティションを指定します。

    データの最初のパーティションを含む応答を受信した後に、partition=<パーティション番号>を使用してリクエストを送信すると、残りのパーティションを取得できます。ここで、<パーティション番号>は、返すデータのパーティションを識別します。パーティション番号0は、最初のリクエストで返されるデータの最初のパーティションを識別します。

    たとえば、データの最初のパーティションを受信した後に、パーティションパラメーターを1に設定してリクエストを送信すると、データの2番目のパーティションを取得できます。

    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 フィールドの最初のオブジェクトは、この応答のデータフィールドにあるデータのパーティションを記述します。

    • 2番目のオブジェクトは、47387行を含み、リクエスト GET /api/statements/<ハンドル>?partition=1 を送信して取得できる、データの2番目のパーティションを記述します。

    • 3番目のオブジェクトは、47386行を含み、リクエスト GET /api/statements/<ハンドル>?partition=2 を送信して取得できる、データの3番目のパーティションを記述します。

  • 追加のパーティションは圧縮形式で返されます。 GET /api/statements/<ハンドル>?partition=<パーティション番号> リクエストの応答では、本文に JSON データが圧縮形式で含まれています（gzipを使用）。

    応答には、 HTTP ヘッダーContent-Encoding:gzipが含まれます。これは、応答の本文が圧縮されていることを示します。

    これらの応答には、メタデータは含まれません。すべてのパーティションのメタデータは、最初の非圧縮パーティションで提供されます。

  • 廃止された page、 pageSize、および numPages フィールドは、応答の本文の resultSetMetaData オブジェクトに含まれなくなりました。

    新しい機能により、 SQL API はページでデータを返さなくなります。代わりに、 SQL API はパーティション内のデータを返し、 resultSetMetaData オブジェクトの partitionInfo フィールドを使用して、パーティションの数と各パーティションの行数を決定します。

  • 行番号は結果セットに含まれなくなりました。

    応答に行番号を含めるには、クエリで SEQUENCE または ROW_NUMBER ウィンドウ関数を呼び出して行番号を生成します。

  • ブール値は1か0かではなく、trueかfalseで返されるようになりました。

言語: 日本語