Snowflake SQL API: SQL ステートメントの送信プロセスへの変更¶
このリリースにより、Snowflake SQL API は、 SQL API の処理効率を改善するように設計された変更を導入します。
これらの変更の一環として、この記事で説明されているように、いくつかの機能が廃止されています。
新しい SQL API 機能の有効化¶
特定のリクエストに対して新しい SQL API 機能を有効にするには、次の例に示すように、 resultSetMetaData の形式フィールドをJSONv2に設定します。
{
"statement": "select * from mytable",
"resultSetMetaData": {
"format": "jsonv2"
},
...
}
廃止された機能を使用して結果を処理するには、 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"] ] }
この例では、
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で返されるようになりました。