Snowflake SQL API リファレンス¶

このトピックでは、SQL API の操作、リクエスト、および応答について説明します。

操作¶

`POST /api/v2/statements`¶

実行のために1つ以上の SQL ステートメントを送信するには、 POST リクエストを /api/v2/statements に送信します。ステートメントを非同期で実行するように指定できます。

リクエスト構文¶

POST /api/v2/statements
(request body)

クエリパラメーター¶


パラメーター	説明
`requestId`	（オプション） API リクエストの一意な ID （UUID）。 SQL ステートメントの実行リクエストの再送信をご参照ください。
`async`	（オプション）ステートメントを非同期で実行し、ステートメントハンドルを返すには、 `true` に設定します。パラメーターが指定されていないか、falseに設定されている場合は、ステートメントが実行され、実行が45秒以内に完了すると結果が返されます。ステートメントの実行が完了するまでに時間がかかる場合は、ステートメントハンドルが返されます。
`nullable`	（オプション） `false` に設定すると、値 `null` ではなく、文字列 `"null"` として SQL NULL 値が返されます。注釈 GET リクエストでこのパラメーターを指定することはできません。デフォルトでは、SQL NULL の値は `null` の値として返されます。 "data" : [ [ null ], ... ] このクエリパラメーターをfalseに設定します（例: `/api/v2/statements?nullable=false` は SQL NULL 値を文字列 `"null"` として返す）。 "data" : [ [ "null" ], ... ]

リクエストヘッダー¶

リクエストには、すべての操作のリクエストヘッダーにリストされているヘッダーを含める必要があります。

リクエスト本文¶

（必須）リクエストの本文には、 /api/v2/statements/ へのリクエスト POST の本文で指定されたオブジェクトが含まれている必要があります。

応答¶

この操作は、以下にリストされている応答コードを返すことができます。


コード	説明
200	ステートメントは正常に実行されました。この応答コードには、次のヘッダーを応答に含めることができます。リンクリクエストで単一の SQL ステートメントが送信された場合、応答の本文には、リクエストされたデータを含む ResultSet オブジェクトが含まれます。注釈応答の `code` フィールドが `391908` に設定されている場合は、結果セットが大きすぎるため、 . 応答に結果セット全体が含まれません。以下は、結果が単一のパーティションに返される単一の SQL ステートメントに対する応答の例です。ここで、 `{handle}` はステートメントハンドルであり、 `{id1}`、 `{id2}`、および `{id3}` は一意に生成されたリクエスト IDs です。 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 } 以下は、結果を複数のパーティションで返す必要がある単一の SQL ステートメントの応答の例です。ここで、 `{handle}` はステートメントハンドルであり、 `{id1}`、 `{id2}`、 `{id3}`、および `{id4}` は一意に生成されたリクエスト IDs です。 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 } 複数の SQL ステートメントがリクエストで送信された場合、応答の本文には、複数のステートメントの実行ステータスに関する詳細を含む ResultSet オブジェクトが含まれます。この場合、応答にはリクエストされたデータが含まれていません。代わりに、 `data` フィールドには「複数のステートメントが正常に実行されました」というメッセージが含まれているだけです。応答には `statementHandles` フィールドが含まれています。これは、個々のステートメントの結果を取得するために使用できるステートメントハンドルの配列です。以下は、複数の SQL ステートメントを指定するリクエストの応答の例です。ここで、 `{handle}` は、ステートメントのセットのステートメントハンドルです。 `{handle1}`、 `{handle2}`、および `{handle3}` は、リクエストにある個々の SQL ステートメントのハンドルです。 `{id1}`、 `{id2}`、および `{id3}` は、一意に生成されたリクエスト IDs です。 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 }
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" }
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" }

この操作によって返される他の応答コードについては、すべての操作の応答コードをご参照ください。

`GET /api/v2/statements/{statementHandle}`¶

ステートメントの実行のステータスを確認するには、 GET リクエストを /api/v2/statements/{statementHandle} に送信します。ステートメントが正常に実行された場合、応答の本文には、リクエストされたデータを含む ResultSet オブジェクトが含まれます。

リクエスト構文¶

GET /api/v2/statements/{statementHandle}

パスパラメーター¶


パラメーター	説明
`statementHandle`	（必須）チェックするステートメントのハンドル。このハンドルは、ステートメント実行のリクエストに対する応答として返された QueryStatus オブジェクトから取得できます。

クエリパラメーター¶


`requestId`	（オプション） API リクエストの一意な ID （UUID）。 SQL ステートメントの実行リクエストの再送信をご参照ください。
`partition`	（オプション）返すパーティション番号。各パーティションのサイズはSnowflakeによって決定されます。詳細については、応答からの結果の取得をご参照ください。

リクエストヘッダー¶

リクエストには、すべての操作のリクエストヘッダーにリストされているヘッダーを含める必要があります。

応答¶

この操作は、以下にリストされている応答コードを返すことができます。

コード	説明
200	ステートメントは正常に実行されました。この応答コードには、次のヘッダーを応答に含めることができます。リンク応答の本文には、リクエストされたデータを含む ResultSet オブジェクトがあります。以下は応答の例です。ここで、 `{handle}` はステートメントハンドルであり、 `{id1}`、 `{id2}`、 `{id3}`、 `{id4}`、および `{id5}}` は一意に生成されたリクエスト IDs です。 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 }
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" }
422	ステートメントの実行中にエラーが発生しました。詳細はエラーコードとエラーメッセージを確認してください。応答の本文には、エラーに関する詳細を含む QueryFailureStatus オブジェクトが含まれています。

コード

説明

200

ステートメントは正常に実行されました。

この応答コードには、次のヘッダーを応答に含めることができます。

リンク

応答の本文には、リクエストされたデータを含む ResultSet オブジェクトがあります。

以下は応答の例です。ここで、 {handle} はステートメントハンドルであり、 {id1}、 {id2}、 {id3}、 {id4}、および {id5}} は一意に生成されたリクエスト IDs です。

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
}

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"
}

422

ステートメントの実行中にエラーが発生しました。詳細はエラーコードとエラーメッセージを確認してください。

応答の本文には、エラーに関する詳細を含む QueryFailureStatus オブジェクトが含まれています。

この操作によって返される他の応答コードについては、すべての操作の応答コードをご参照ください。

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

ステートメントの実行をキャンセルするには、 POST リクエストを /api/v2/statements/{statementHandle}/cancel に送信します。

リクエスト構文¶

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

パスパラメーター¶


パラメーター	説明
`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" }
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" }

コード

説明

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"
}

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"
}

この操作によって返される他の応答コードについては、すべての操作の応答コードをご参照ください。

すべての操作のリクエストヘッダー¶

次のリクエストヘッダーは、すべての操作に適用されます。


ヘッダー	必須か、またはオプションか。	説明
`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`	オプション	これを次のいずれかの値にセットします。 `KEYPAIR_JWT`、キーペア認証を使用している場合。 `OAUTH`、 OAuth を使用している場合。 `X-Snowflake-Authorization-Token-Type` ヘッダーを省略した場合、Snowflakeはトークンを調べてトークンのタイプを決定します。このヘッダーはオプションですが、このヘッダーを指定することもできます。ヘッダーは以下の値のいずれかにセットできます。 `KEYPAIR_JWT` （キーペア認証用） `OAUTH` （ OAuthの場合） `PROGRAMMATIC_ACCESS_TOKEN` （プログラムアクセストークン用）

リクエスト本文のオブジェクトの型¶

`/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"}}
`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"
    }
  }
}

`statements_parameters`¶

statements_parameters は、このリクエストに設定するセッションパラメーターを指定するために使用する JSON オブジェクトです。このオブジェクトは、 /api/v2/statements エンドポイントへの POST リクエスト本文の /api/v2/statements/ へのリクエスト POST の本文フィールドにある必要があります（parameters を参照）。

注釈

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`	（リクエストに1つ以上の 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." }
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" }
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
415	リクエストヘッダー `Content-Type` に、サポートされていないメディアタイプが含まれています。
422	リクエストは整形式（つまり構文的に正しい）であったが、処理できませんでした。 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." }
500	内部サーバーエラー。サーバーで回復不能なシステムエラーが発生しました。応答本文には、詳細なガイダンスとしてエラーコードとメッセージが含まれる場合があります。 `requestId` と `retry` パラメーターを `true` に設定することで、指数バックオフを再試行できます。詳細については、 SQL ステートメントの実行リクエストの再送信をご参照ください。
502	Bad Gateway。サーバーがゲートウェイまたはプロキシとして動作し、アップストリームサーバーから無効な応答を受信しました。 `requestId` と `retry` パラメーターを `true` に設定することで、指数バックオフを再試行できます。詳細については、 SQL ステートメントの実行リクエストの再送信をご参照ください。
503	サービスは利用できません。サーバーでタイムアウトが発生したため、リクエストは処理されませんでした。アプリケーションはバックオフで再試行する場合があります。指数関数的にジッターをともなうバックオフが推奨です。
504	Gatewayのタイムアウト。サーバーでタイムアウトが発生したため、リクエストは処理されませんでした。アプリケーションはバックオフで再試行する場合があります。指数関数的にジッターをともなうバックオフが推奨です。
522	無効な SSL 証明書。サーバーは提供された SSL 証明書を検証できませんでした。

すべての操作の応答ヘッダー¶

応答には、次のヘッダーを含めることができます。


ヘッダー	説明
`Link`	このヘッダーは、ステートメント実行のリクエストと、ステートメント実行のステータスをチェックするリクエストの200応答に含まれています。このヘッダーは、結果の他のパーティション（例: 最初のパーティション、最後のパーティションなど）へのリンクを提供します。ヘッダーには、返すパーティションを指定する異なる `rel` 属性値を持つ複数の URL エントリを含めることができます（`first`、 `next`、 `prev`、および `last`）。例: 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">

応答本文のオブジェクトの型¶

`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"
}

`QueryFailureStatus`¶

QueryFailureStatus は、ステートメントの実行の失敗に関する情報を含む JSON オブジェクトです。このオブジェクトは、ステートメント実行のリクエストに対する422応答の本文で返されます。

フィールド¶


フィールド	説明
`code`	型: 文字列例: `0`
`sqlState`	型: 文字列
`message`	型: 文字列例: `successfully executed`
`statementHandle`	実行中のステートメントの一意な識別子。型: 文字列（UUID）例: `536fad38-b564-4dc5-9892-a4543504df6c`
`createdOn`	ステートメントの実行が開始される時刻を指定するタイムスタンプ。タイムスタンプは、エポック以降のミリ秒で表されます。型: 64ビットの符号付き整数例: `1597090533987`
`statementStatusUrl`	ステートメントのステータスと結果セットを取得する URL。型: 文字列（URL）例: `/api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c`

例¶

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

`QueryStatus`¶

QueryStatus は、ステートメントの実行のステータスに関する情報を含む JSON オブジェクトです。このオブジェクトは次のように返されます。

ステートメント実行のリクエストに対する202および408応答の本文。
ステートメントの実行のステータスを確認するリクエストに対する202および422応答の本文。

フィールド¶


フィールド	説明
`code`	型: 文字列例: `0`
`sqlState`	型: 文字列
`message`	型: 文字列例: `successfully executed`
`statementHandle`	実行中のステートメントの一意な識別子。型: 文字列（UUID）例: `536fad38-b564-4dc5-9892-a4543504df6c`
`createdOn`	ステートメントの実行が開始される時刻を指定するタイムスタンプ。タイムスタンプは、エポック以降のミリ秒で表されます。型: 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"
}

`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`	ステートメントの実行が開始される時刻を指定するタイムスタンプ。タイムスタンプは、エポック以降のミリ秒で表されます。例: `1597090533987`
`statementStatusUrl`	ステートメントのステータスと結果セットを取得する URL。型: 文字列（URL）例: `/api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c`
`resultSetMetaData`	返される結果セットに関するメタデータ。型: オブジェクト（ResultSet_resultSetMetaData）
`data`	リクエストに単一の SQL ステートメントが含まれている場合、このフィールドには結果セットデータが含まれます。結果セットの形式は、 JSON にある配列の配列です。各配列は1つの行に対応します。行の要素は、その行の列の値に対応します。 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"] ] リクエストに複数の 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} ]

`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
}

`ResultSet_stats`¶

ResultSet_stats は、 DML ステートメントの実行に関する統計を含む JSON オブジェクトです。このオブジェクトは ResultSet_resultSetMetaData オブジェクトの stats フィールドにあります。

フィールド¶


フィールド	説明
`numRowsInserted`	挿入された行数。型: 64ビットの符号付き整数例: `12`
`numRowsUpdated`	更新された行数。型: 64ビットの符号付き整数例: `9`
`numRowsDeleted`	削除された行数。型: 64ビットの符号付き整数例: `8`
`numDuplicateRowsUpdated`	更新された重複行の数。型: 64ビットの符号付き整数例: `20`

Snowflake SQL API リファレンス¶

操作¶

POST /api/v2/statements¶

リクエスト構文¶

クエリパラメーター¶

リクエストヘッダー¶

リクエスト本文¶

応答¶

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

リクエスト構文¶

パスパラメーター¶

クエリパラメーター¶

リクエストヘッダー¶

応答¶

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

リクエスト構文¶

パスパラメーター¶

クエリパラメーター¶

リクエストヘッダー¶

応答¶

すべての操作のリクエストヘッダー¶

リクエスト本文のオブジェクトの型¶

/api/v2/statements/ へのリクエスト POST の本文¶

フィールド¶

例¶

statements_parameters¶

フィールド¶

すべての操作の応答コード¶

すべての操作の応答ヘッダー¶

応答本文のオブジェクトの型¶

CancelStatus¶

フィールド¶

例¶

QueryFailureStatus¶

フィールド¶

例¶

QueryStatus¶

フィールド¶

例¶

ResultSet¶

フィールド¶

ResultSet_resultSetMetaData¶

フィールド¶

ResultSet_resultSetMetaData_rowType¶

フィールド¶

例¶

ResultSet_stats¶

フィールド¶

`POST /api/v2/statements`¶

`GET /api/v2/statements/{statementHandle}`¶

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

`/api/v2/statements/` へのリクエスト `POST` の本文¶

`statements_parameters`¶

`CancelStatus`¶

`QueryFailureStatus`¶

`QueryStatus`¶

`ResultSet`¶

`ResultSet_resultSetMetaData`¶

`ResultSet_resultSetMetaData_rowType`¶

`ResultSet_stats`¶