Snowflake SQL API リファレンス

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

このトピックの内容:

操作

POST /api/statements

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

リクエスト構文

POST /api/statements
(request body)

クエリパラメーター

パラメーター

説明

requestId

(オプション) API リクエストの一意な ID (UUID)。 リクエスト再送信向けの固有リクエスト ID の割り当て をご参照ください。

async

(オプション)ステートメントを非同期で実行し、ステートメントハンドルを返すには、 true に設定します。

パラメーターが指定されていないか、falseに設定されている場合は、ステートメントが実行され、実行が45秒以内に完了すると結果が返されます。ステートメントの実行が完了するまでに時間がかかる場合は、ステートメントハンドルが返されます。

ステートメントの実行が完了すると、結果には pageSize パラメーターで指定された最大行数が含まれることに注意してください。 ResultSet_resultSetMetaDatanumRows フィールドが結果の追加の行があることを示している場合は、 結果の追加ページの取得 をご参照ください。

pageSize

(オプション)ページ当たりで返す行数。ページサイズは、最小サポート数(10)からページ当たりでサポートされている最大数(10000)までの範囲です。デフォルトでは、返される行数はステートメントの実行によって異なります。

注意: クエリが大量の行を返す場合は、このパラメーターを設定します。そうしないと、行数がページ内のデフォルトの行数を超える可能性があります。

nullable

(オプション) false に設定すると、値 null ではなく、文字列 "null" として SQL NULL 値が返されます。

デフォルトでは、SQL NULL の値は null の値として返されます。

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

このクエリパラメーターをfalseに設定します(例: /api/statements?nullable=false は SQL NULL 値を文字列 "null" として返す)。

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

リクエストヘッダー

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

リクエスト本文

(必須)リクエストの本文には、 /api/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/statements/{handle}?requestId={id1}&page=0&pageSize=10>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=10>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 0,
    "pageSize" : 10,
    "numPages" : 1,
    "numRows" : 4,
    "format" : "json",
    "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
    } ]
  },
  "data" : [ [ "0", "test", "2" ], [ "1", "test", "3" ], [ "2", "test", "4" ], [ "3", "test", "5" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id3}&pageSize=10",
  "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/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=1&pageSize=-1>; rel="next",
  </api/statements/{handle}?requestId={id3}&page=7&pageSize=-1>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 0,
    "numPages" : 8,
    "numRows" : 10000,
    "format" : "json",
    "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
    } ]
  },
  "data" : [ [ "0", "0", "QqKow2xzdJ....." ],.... [ "98", "98", "ZugTcURrcy...." ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/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/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=-1>; rel="last"

{
  "resultSetMetaData" : {
  "page" : 0,
  "numPages" : 1,
  "numRows" : 1,
  "format" : "json",
  "rowType" : [ {
      "name" : "multiple statement execution",
      "database" : "",
      "schema" : "",
      "table" : "",
      "type" : "text",
      "scale" : null,
      "precision" : null,
      "byteLength" : 16777216,
      "nullable" : false,
      "collation" : null,
      "length" : 16777216
    } ]
  },
  "data" : [ [ "0", "Multiple statements executed successfully." ] ],
  "code" : "090001",
  "statementHandles" : [ "{handle1}", "{handle2}", "{handle3}" ],
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id3}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1622501430333
}

202

ステートメントの実行はまだ進行中です。 GET /api/statements/{statementHandle} を使用して、ステートメント実行のステータスを確認します。詳細については GET /api/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/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/statements/{statementHandle}

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

リクエスト構文

GET /api/statements/{statementHandle}

パスパラメータ

パラメーター

説明

statementHandle

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

クエリパラメーター

requestId

(オプション) API リクエストの一意な ID (UUID)。 リクエスト再送信向けの固有リクエスト ID の割り当て をご参照ください。

page

(オプション)結果のどのページを返すかを識別する番号。この数の範囲は、0から合計ページ数より1を引いたものまでです。

pageSize

(オプション)ページ当たりで返す行数。ページサイズは、最小サポート数(10)からページ当たりでサポートされている最大数(10000)までの範囲です。デフォルトでは、返される行数はステートメントの実行によって異なります。

リクエストヘッダー

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

応答

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

コード

説明

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/statements/{handle}?requestId={id1}&page=0&pageSize=10>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=10>; rel="prev",
  </api/statements/{handle}?requestId={id3}&page=2&pageSize=10>; rel="next",
  </api/statements/{handle}?requestId={id4}&page=999&pageSize=10>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 1,
    "pageSize" : 10,
    "numPages" : 1000,
    "numRows" : 10000,
    "format" : "json",
    "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
    } ]
  },
  "data" : [ [ "10", "10", "lJPPMTSwps......" ], ... [ "19", "19", "VJKoHmUFJz......" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id5}&pageSize=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/statements/019c07a7-0000-df4f-0000-001000067872"
}

422

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

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

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

POST /api/statements/{statementHandle}/cancel

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

リクエスト構文

POST /api/statements/{statementHandle}/cancel

パスパラメータ

パラメーター

説明

statementHandle

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

クエリパラメーター

パラメーター

説明

requestId

(オプション) API リクエストの一意な ID (UUID)。 リクエスト再送信向けの固有リクエスト ID の割り当て をご参照ください。

リクエストヘッダー

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

応答

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

コード

説明

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/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 トークン

サーバーへの認証 をご参照ください。

Accept

必須

これを応答の本文で受け入れられるメディアタイプ(MIME タイプ)のリストに設定します。タイプ application/json を含めます(または、すべてのタイプが受け入れられる場合は、これを */* に設定)。

Content-Type

必須

これをリクエストの本文のメディアタイプ(MIME タイプ)に設定します。これを application/json に設定します。

User-Agent

必須

これをアプリケーションの名前とバージョンに設定します(例: applicationName/applicationVersion)。 RFC 7231 に準拠した値を使用する必要があります。

X-Snowflake-Authorization-Token-Type

キーペア認証のサポートに必須

OAuth でオプション

キーペア認証 を使用している場合、このヘッダーは 必須 です。このヘッダーを KEYPAIR_JWT に設定する必要があります。

認証に OAuth を使用している場合、このヘッダーはオプションです。(このヘッダーを設定する場合は、 OAUTH に設定。)

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

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

/api/statements/ エンドポイントへの POST リクエストの本文(POST /api/statements を参照)は、実行する SQL ステートメント、ステートメントコンテキスト、および結果セットのデータ形式を指定するために使用する JSON オブジェクトです。このオブジェクトをリクエストの本文で使用して、ステートメントを実行します。

フィールド

フィールド

説明

statement

(オプション)実行する SQL ステートメント。サポートされているステートメントとサポートされていないステートメントのリストについては、 紹介 をご参照ください。

型: 文字列

timeout

(オプション)ステートメント実行のタイムアウト(秒)。ステートメントの実行に指定されたタイムアウトよりも時間がかかる場合、実行は自動的にキャンセルされます。タイムアウトを最大値(604800 秒)に設定するには、タイムアウトを0に設定します。このフィールドが設定されていない場合、 STATEMENT_TIMEOUT_IN_SECONDS パラメーターで指定されたタイムアウトが使用されます。

型: 64ビットの符号付き整数

例: 10

resultSetMetaData

(オプション)返される結果セットに関するメタデータ。

型: オブジェクト(statements_resultSetMetaData

database

(オプション)ステートメントが実行されるデータベース。このフィールドの値は大文字と小文字が区別されます。

型: 文字列

例: TESTDB

schema

(オプション)ステートメントが実行されるスキーマ。このフィールドの値は大文字と小文字が区別されます。

型: 文字列

例: TESTSCHEMA

warehouse

(オプション)ステートメントの実行時に使用するウェアハウス。このフィールドの値は大文字と小文字が区別されます。

型: 文字列

例: TESTWH

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,
  "resultSetMetaData" : {
    "format" : "json"
  },
  "database" : "TESTDB",
  "schema" : "TESTSCHEMA",
  "warehouse" : "TESTWH",
  "role" : "TESTROLE",
  "bindings" : {
    "1" : {
      "type" : "FIXED",
      "value" : "123"
    }
  }
}

statements_parameters

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

フィールド

フィールド

説明

timezone

(オプション)ステートメントの実行時に使用するタイムゾーン。詳細については、 TIMEZONE パラメーターのドキュメント をご参照ください。

型: 文字列

例: america/los_angeles

query_tag

(オプション) SQL ステートメントに関連付けるクエリタグ。詳細については、 QUERY_TAG パラメーターのドキュメント をご参照ください。

型: 文字列

例: tag-1234

statements_resultSetMetaData

statements_resultSetMetaData は、返される結果セットに関するメタデータを指定するために使用する JSON オブジェクトです。このオブジェクトは、 /api/statements エンドポイントへの POST リクエスト本文の /api/statements/ への POST リクエストの本文 フィールドにある必要があります(resultSetMetaData を参照)。

フィールド

フィールド

説明

format

(オプション)結果セット内のデータの形式。現在サポートされている値は、 json のみです。

型: 文字列

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

このセクションには、すべての操作に適用される応答コードがリストされています。

コード

説明

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/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 に、サポートされていないメディアタイプが含まれています。

API は application/json のみをサポートします。 Content-Type が指定されていない場合、リクエストペイロードは JSON と解釈されますが、他のメディアタイプが指定された場合は、このエラーが返されます。

429

制限超過。

リクエスト数がレート制限に達しました。アプリケーションは、 API エンドポイントに送信されるリクエストの頻度を減らす必要があります。

以下は、応答の例です。

HTTP/1.1 429 Too many requests
Content-Type: application/json
Content-Length: 69
{
  "code" : "390505",
  "message" : "Too many concurrent requests"
}

500

内部サーバーエラー。

サーバーで回復不能なシステムエラーが発生しました。応答本文には、詳細なガイダンスとしてエラーコードとメッセージが含まれる場合があります。

503

サービスは利用できません。

サーバーでタイムアウトが発生したため、リクエストは処理されませんでした。アプリケーションはバックオフで再試行する場合があります。指数関数的にジッターをともなうバックオフが推奨です。

504

Gatewayのタイムアウト。

サーバーでタイムアウトが発生したため、リクエストは処理されませんでした。アプリケーションはバックオフで再試行する場合があります。指数関数的にジッターをともなうバックオフが推奨です。

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

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

ヘッダー

説明

Link

このヘッダーは、 ステートメント実行のリクエスト と、 ステートメント実行のステータスをチェックするリクエスト の200応答に含まれています。

このヘッダーは、結果の他のページ(例: 最初のページ、最後のページなど)へのリンクを提供します。ヘッダーには、返すページを指定する異なる rel 属性値を持つ複数の URL エントリを含めることができます(firstnextprev、および last)。

例:

Link: </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=1; rel="last">,
      </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=1; rel="next">,
      </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=0; rel="first">

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

CancelStatus

CancelStatus は、ステートメントの実行のキャンセルに関する情報を含む JSON オブジェクトです。このオブジェクトは、 キャンセルリクエスト の応答の本文で返されます。

フィールド

フィールド

説明

code

型: 文字列

sqlState

型: 文字列

message

例: successfully cancelled

型: 文字列

statementHandle

実行中のステートメントの一意な識別子。

型: 文字列(UUID

例: 536fad38-b564-4dc5-9892-a4543504df6c

statementStatusUrl

ステートメントのステータスと結果セットを取得する URL。

型: 文字列(URL)

例: /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully canceled",
  "statementHandle" : "536fad38-b564-4dc5-9892-a4543504df6c",
  "statementStatusUrl" : "/api/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/statements/536fad38-b564-4dc5-9892-a4543504df6c

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

QueryStatus

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

フィールド

フィールド

説明

code

型: 文字列

例: 0

sqlState

型: 文字列

message

型: 文字列

例: successfully executed

statementHandle

実行中のステートメントの一意な識別子。

型: 文字列(UUID

例: 536fad38-b564-4dc5-9892-a4543504df6c

createdOn

ステートメントの実行が開始される時刻を指定するタイムスタンプ。タイムスタンプは、エポック以降のミリ秒で表されます。

型: 64ビットの符号付き整数

例: 1597090533987

statementStatusUrl

ステートメントのステータスと結果セットを取得する URL。

型: 文字列(URL)

例: /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

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

ResultSet

ResultSet は、ステートメントの実行の結果を含む JSON オブジェクトです。このオブジェクトは、 ステートメント実行のリクエスト と、 ステートメント実行のステータスをチェックするリクエスト の200応答の本文に含まれています。

フィールド

フィールド

説明

code

型: 文字列

例: 0

注釈

code391908 に設定されている場合は、 結果セットのページサイズが制限を超えているかどうかの判断 をご参照ください。

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/statements/536fad38-b564-4dc5-9892-a4543504df6c

resultSetMetaData

返される結果セットに関するメタデータ。

型: オブジェクト(ResultSet_resultSetMetaData

data

リクエストに単一の SQL ステートメントが含まれている場合、 このフィールドには結果セットデータが含まれます。

結果セットの形式は、 JSON にある配列の配列です。

  • 各配列は1つの行に対応します。

  • 行の最初の要素は、0から始まるシーケンス ID を含む JSON 文字列です。

  • 行の残りの要素は実際のデータです。

  • Snowflakeデータ型に関係なく、データは JSON 文字列としてエンコードされます。

型: 配列の配列

例:

[
  ["0","customer1","1234 A Avenue","98765","1565481394123000000"],
  ["1","customer2","987 B Street","98765","1565516712912012345"],
  ["2","customer3","8777 C Blvd","98765","1565605431999999999"],
  ["3","customer4","64646 D Circle","98765","1565661272000000000"]
]

リクエストに複数の SQL ステートメントが含まれる場合、 このフィールドには「複数のステートメントが正常に実行されました」というメッセージが含まれます。リクエスト内の各ステートメントの結果を取得するには、これらのステートメントのハンドルを statementHandles フィールドから取得し、 リクエストを送信して各ステートメントの結果を取得 します。

stats

DML ステートメントの場合、このフィールドには、操作によって影響を受ける行数に関する統計が含まれます。

型: オブジェクト(ResultSet_stats

ResultSet_resultSetMetaData

ResultSet_resultSetMetaData は、ステートメントの実行結果に関するメタデータを含む JSON オブジェクトです。このオブジェクトは ResultSet オブジェクトの resultSetMetaData フィールドにあります。

フィールド

フィールド

説明

page

結果の現在のページを識別する番号。

型: 64ビットの符号付き整数

例: 12

pageSize

ページ当たりの行の数。このフィールドは、 リクエストpageSize パラメーターを指定した場合にのみ設定されます。

型: 64ビットの符号付き整数

例: 10

numPages

結果のページ数。

型: 64ビットの符号付き整数

例: 10

numRows

結果の行の合計数。

型: 64ビットの符号付き整数

例: 100

format

結果セット内のデータの形式。現在サポートされている値は、 json のみです。

型: 文字列

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