Snowflake SQL API リファレンス

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

このトピックの内容:

操作

POST /api/v2/statements

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

リクエスト構文

POST /api/v2/statements
(request body)
Copy

クエリパラメーター

パラメーター

説明

requestId

（オプション） API リクエストの一意な ID （UUID）。 SQL ステートメントの実行リクエストの再送信 をご参照ください。

async

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

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

nullable

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

注釈

GET リクエストでこのパラメーターを指定することはできません。

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

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

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

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

リクエストヘッダー

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

リクエスト本文

（必須）リクエストの本文には、 /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
}
Copy

以下は、結果を複数のパーティションで返す必要がある単一の 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
}
Copy

複数の 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
}
Copy

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

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

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

GET /api/v2/statements/{statementHandle}

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

リクエスト構文

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

パスパラメーター

パラメーター

説明

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

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

422

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

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

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

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

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

リクエスト構文

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

パスパラメーター

パラメーター

説明

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

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

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

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

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

ヘッダー

必須か、またはオプションか。

説明

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

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

OAuth でオプション

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

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

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

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

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

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

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

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
Copy

415

リクエストヘッダー Content-Type に、サポートされていないメディアタイプが含まれています。

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

500

内部サーバーエラー。

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

503

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

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

504

Gatewayのタイムアウト。

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

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

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

ヘッダー

説明

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

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

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

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" : "002140",
  "sqlState" : "42601",
  "message" : "SQL compilation error",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
}
Copy

QueryStatus

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

フィールド

フィールド

説明

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

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"]
]
Copy

リクエストに複数の 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}
]
Copy

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

ResultSet_stats

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

フィールド

フィールド

説明

numRowsInserted

挿入された行数。

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

例: 12

numRowsUpdated

更新された行数。

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

例: 9

numRowsDeleted

削除された行数。

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

例: 8

numDuplicateRowsUpdated

更新された重複行の数。

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

例: 20
言語: 日本語