Snowflake SQL API 引用¶

本主题记录了 SQL API 的操作、请求和响应。

操作¶

`POST /api/v2/statements`¶

若要提交一个或多个要执行的 SQL 语句，请向 /api/v2/statements 发送 POST 请求。您可以指定以异步方式执行语句。

请求语法¶

POST /api/v2/statements
(request body)

查询参数¶


参数	描述
`requestId`	（可选） API 请求的唯一 ID ( UUID (link removed))。请参阅重新提交执行 SQL 语句的请求。
`async`	（可选）设置为 `true` 可异步执行语句并返回语句句柄。如果未指定该参数或将其设置为 false，则执行语句，如果在 45 秒内执行完毕，则返回执行结果。如果语句执行需要更长的时间才能完成，则返回语句句柄。
`nullable`	（可选）设置为 `false` 时， SQL NULL 值将以字符串 `"null"` 的形式返回，而不是以值 `null` 的形式返回。备注不能在 GET 请求中指定此参数。默认情况下，SQL NULL 值返回为值 `null`： "data" : [ [ null ], ... ] 将此查询参数设置为 false 时（例如 `/api/v2/statements?nullable=false`），SQL NULL 值返回为字符串 `"null"`： "data" : [ [ "null" ], ... ]

请求标头¶

请求必须包含所有操作的请求标头中所列的标头。

请求正文¶

（必填）请求正文必须包含:ref:`label-sql_api_reference_post_statements_request_body`中指定的对象。

响应¶

此操作可以返回下面列出的响应代码。


代码	描述
200	语句已成功执行。对于此响应代码，响应可以具有以下标头： Link 如果在请求中提交了单个 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` 字段仅包含“Multiple statements executed successfully”这一消息。响应中包含字段 `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}`¶

要查看语句的执行状态，请向 /api/v2/statements/{statementHandle} 发送 GET 请求。如果语句已成功执行，则响应正文将包含一个 ResultSet 对象，其中包含了请求的数据。

请求语法¶

GET /api/v2/statements/{statementHandle}

路径参数¶


参数	描述
`statementHandle`	（必填）要查看的语句的句柄。可以通过执行语句的请求的响应中返回的 QueryStatus 对象获取该句柄。

查询参数¶


`requestId`	（可选） API 请求的唯一 ID ( UUID (link removed))。请参阅重新提交执行 SQL 语句的请求。
`partition`	（可选）要返回的分区号。每个分区的大小由 Snowflake 确定。有关更多信息，请参阅从响应中获取结果。

请求标头¶

请求必须包含所有操作的请求标头中所列的标头。

响应¶

此操作可以返回下面列出的响应代码。

代码	描述
200	语句已成功执行。对于此响应代码，响应可以具有以下标头： Link 响应正文包含一个 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

语句已成功执行。

对于此响应代码，响应可以具有以下标头：

Link

响应正文包含一个 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`¶

要取消对语句的执行，请向 /api/v2/statements/{statementHandle}/cancel 发送 POST 请求。

请求语法¶

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

路径参数¶


参数	描述
`statementHandle`	（必填）要查看的语句的句柄。可以通过执行语句的请求的响应中返回的 QueryStatus 对象获取该句柄。

查询参数¶


参数	描述
`requestId`	（可选） API 请求的唯一 ID ( UUID (link removed))。请参阅重新提交执行 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 <https://tools.ietf.org/html/rfc7231#section-5.5.3 (https://tools.ietf.org/html/rfc7231#section-5.5.3)> `_ 的值。
`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），其正文是一个 JSON 对象，用于指定要执行的 SQL 语句、语句上下文和结果集中的数据格式。您可以在请求正文中使用此对象来执行语句。

字段¶


字段	描述
`statement`	（可选）要执行的 SQL 语句。请参阅 SQL API 的限制，了解受支持和不受支持的语句列表。类型：字符串
`timeout`	（可选）语句执行超时（以秒为单位）。如果语句的执行时间超过指定的超时时间，则自动取消执行。若要将超时设置为最大值（604800 秒），请将超时设置为 0。如果未设置此字段，系统将使用 STATEMENT_TIMEOUT_IN_SECONDS 参数指定的超时。类型：64 位带符号整数示例：`10`
`database`	（可选）应在其中执行语句的数据库。此字段中的值区分大小写。如果省略此字段， SQL API 将使用用户 :code:`DEFAULT_NAMESPACE 属性 </sql-reference/sql/alter-user>` 值中的数据库。类型：字符串示例：`TESTDB`
`schema`	（可选）应在其中执行语句的架构。此字段中的值区分大小写。如果省略此字段， SQL API 将使用用户 :code:`DEFAULT_NAMESPACE 属性 </sql-reference/sql/alter-user>` 值中的架构。类型：字符串示例：`TESTSCHEMA`
`warehouse`	（可选）执行语句时要使用的仓库。此字段中的值区分大小写。如果省略此字段， SQL API 将使用用户 :code:`DEFAULT_WAREHOUSE 属性 </sql-reference/sql/alter-user>` 的值。类型：字符串示例：`TESTWH`
`role`	（可选）执行语句时要使用的角色。此字段中的值区分大小写。如果省略此字段， SQL API 将使用用户 :code:`DEFAULT_ROLE 属性 </sql-reference/sql/alter-user>` 的值。类型：字符串示例：`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 请求正文的 parameters 字段中（请参阅向 /api/v2/statements/ 发送的 POST 请求正文）。

备注

SQL API 仅支持下表中列出的会话参数。

字段¶


字段	描述
`binary_output_format`	（可选）指定由 BINARY 到 VARCHAR 转换函数作为输出返回的 VARCHAR 值的格式。有关详细信息，请参阅 BINARY_OUTPUT_FORMAT。类型：字符串示例：`HEX`
`client_result_chunk_size`	（可选）指定要下载的每个查询结果集（或块）的大小上限（以 MB 为单位）。有关详细信息，请参阅 <label-client_result_chunk_size>` 。类型：整型示例：`100`
`date_output_format`	（可选）指定 DATE 数据类型的显示格式。有关详细信息，请参阅 <label-date_output_format>` 。有关使用参数确定查询结果输出格式的详细信息，请参阅设置查询结果输出格式。类型：字符串示例：`YYYY-MM-DD`
`multi_statement_count`	（在请求中指定多个 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<label-rows_per_resultset> 参数 `。类型：整型示例：200
`time_output_format`	（可选）指定 TIME 数据类型的显示格式。有关详细信息，请参阅 <label-time_output_format>` 。有关使用参数确定查询结果输出格式的详细信息，请参阅设置查询结果输出格式。类型：字符串示例：`HH24:MI:SS`
`timestamp_ltz_output_format`	（可选）指定 TIMESTAMP_LTZ 数据类型的显示格式。有关详细信息，请参阅 <label-timestamp_ltz_output_format>` 。有关使用参数确定查询结果输出格式的详细信息，请参阅设置查询结果输出格式。类型：字符串示例：`YYYY-MM-DD HH24:MI:SS.FF3`
`timestamp_ntz_output_format`	（可选）指定 TIMESTAMP_NTZ 数据类型的显示格式。有关详细信息，请参阅 <label-timestamp_ntz_output_format>` 。有关使用参数确定查询结果输出格式的详细信息，请参阅设置查询结果输出格式。类型：字符串示例：`YYYY-MM-DD HH24:MI:SS.FF3`
`timestamp_output_format`	（可选）指定 TIMESTAMP 数据类型别名的显示格式。有关详细信息，请参阅 <label-timestamp_output_format>` 。有关使用参数确定查询结果输出格式的详细信息，请参阅设置查询结果输出格式。类型：字符串示例：`YYYY-MM-DD HH24:MI:SS.FF3 TZHTZM`
`timestamp_tz_output_format`	（可选）指定 TIMESTAMP_TZ 数据类型的显示格式。有关详细信息，请参阅 <label-timestamp_tz_output_format>` 。有关使用参数确定查询结果输出格式的详细信息，请参阅设置查询结果输出格式。类型：字符串示例：`YYYY-MM-DD HH24:MI:SS.FF3`
`timezone`	（可选）执行语句时要使用的时区。有关详细信息，请参阅 TIMEZONE<label-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	无效网关。服务器充当网关或代理，从上游服务器收到无效响应。您可以通过将 `requestId` 和 `retry` 参数设置为 `true` 来重试指数退避。有关更多信息，请参阅重新提交执行 SQL 语句的请求。
503	服务不可用。由于服务器超时，请求未得到处理。应用程序可能利用退避重试。建议使用指数抖动退避。
504	网关超时。由于服务器超时，请求未得到处理。应用程序可能利用退避重试。建议使用指数抖动退避。
522	无效 SSL 证书。服务器无法验证提供的 SSL 证书。

所有操作的响应标头¶

响应可以包含以下标头：


标头	描述
`Link`	此标头位于 :ref:` 执行语句的请求 <label-sql_api_reference_post_statements>` 和 :ref:` 查看语句执行状态的请求 <label-sql_api_reference_get_statements>` 的 200 响应中。此标头提供了指向其他结果分区（例如第一个分区、最后一个分区等）的链接。此标头可以包含多个 URL 条目，并使用不同的 `rel` 属性值来指定要返回的分区（`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 对象，其中包含有关取消语句执行的信息。此对象在 :ref:` 取消请求 <label-sql_api_reference_post_statements_cancel>` 的响应正文中返回。

字段¶


字段	描述
`code`	类型：字符串
`sqlState`	类型：字符串
`message` 示例：`successfully cancelled`	类型：字符串
`statementHandle`	正在执行的语句的唯一标识符。类型：字符串 ( UUID (link removed)) 示例：`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 对象，其中包含有关执行语句失败的信息。此对象在 :ref:` 执行语句的请求 <label-sql_api_reference_post_statements>` 的 422 响应正文中返回。

字段¶


字段	描述
`code`	类型：字符串示例：`0`
`sqlState`	类型：字符串
`message`	类型：字符串示例：`successfully executed`
`statementHandle`	正在执行的语句的唯一标识符。类型：字符串 ( UUID (link removed)) 示例：`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 对象，其中包含有关语句执行状态的信息。此对象在以下内容中返回：

:ref:` 执行语句的请求 <label-sql_api_reference_post_statements>` 的 202 和 408 响应正文。
:ref:` 查看语句执行状态的请求 <label-sql_api_reference_get_statements>` 的 202 和 422 响应正文。

字段¶


字段	描述
`code`	类型：字符串示例：`0`
`sqlState`	类型：字符串
`message`	类型：字符串示例：`successfully executed`
`statementHandle`	正在执行的语句的唯一标识符。类型：字符串 ( UUID (link removed)) 示例：`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 对象，其中包含语句执行结果。此对象在 :ref:` 执行语句的请求 <label-sql_api_reference_post_statements>` 和 :ref:` 查看语句执行状态的请求 <label-sql_api_reference_get_statements>` 的 200 响应正文中返回。

字段¶


字段	描述
`code`	类型：字符串示例：`0`
`sqlState`	类型：字符串
`message`	类型：字符串示例：`successfully executed`
`statementHandle`	正在执行的语句的唯一标识符。如果在请求中指定了多个语句，则此句柄对应于这些语句集。有关请求中各个语句的句柄，请参阅 `statementHandles` 字段。类型：字符串 ( UUID (link removed)) 示例：`536fad38-b564-4dc5-9892-a4543504df6c`
`statementHandles`	为此请求执行的语句的唯一标识符数组。类型：字符串数组 (UUID (link removed)) 示例：`[ "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 格式的数组构成的数组：每个数组对应一行。行中的元素对应该行的列中的值。数据以 JSON 字符串的形式进行编码，与 Snowflake 数据类型无关。类型：数组构成的数组示例： [ ["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 语句，则此字段仅包含“Multiple statements executed successfully”这一消息。若要检索请求中每个语句的结果，请从 `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`	指定列是否可为空。类型：布尔

示例¶

{
 "name":"ACCOUNT_NAME",
 "type":"TEXT",
 "length":1024,
 "precision":0,
 "scale":0,
 "nullable":false
}

`ResultSet_stats`¶

ResultSet_stats 是一个 JSON 对象，其中包含有关 DML 语句执行情况的统计信息。此对象位于 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`¶