Snowflake SQL API 引用¶

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

本主题内容：

操作¶

`POST /api/v2/statements`¶

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

请求语法¶

POST /api/v2/statements
(request body)

Copy

查询参数¶

参数

描述

requestId

（可选） API 请求的唯一 ID ( UUID (link removed))。请参阅重新提交执行 SQL 语句的请求。

async

（可选）设置为 true 可异步执行语句并返回语句句柄。

如果未指定该参数或将其设置为 false，则执行语句，如果在 45 秒内执行完毕，则返回执行结果。如果语句执行需要更长的时间才能完成，则返回语句句柄。

nullable

（可选）设置为 false 时， SQL NULL 值将以字符串 "null" 的形式返回，而不是以值 null 的形式返回。

备注

不能在 GET 请求中指定此参数。

默认情况下，SQL NULL 值返回为值 null：

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

Copy

将此查询参数设置为 false 时（例如 /api/v2/statements?nullable=false），SQL NULL 值返回为字符串 "null"：

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

Copy

请求标头¶

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

请求正文¶

（必填）请求正文必须包含: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 } 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` 字段仅包含“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 } 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}`¶

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

请求语法¶

GET /api/v2/statements/{statementHandle}

Copy

路径参数¶

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

查询参数¶

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

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 } 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 对象，其中包含有关错误的详细信息。

代码

描述

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
}

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

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

请求语法¶

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

Copy

路径参数¶

参数	描述
`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" } 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

代码

描述

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 <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`	对于密钥对身份验证为必填项对 OAuth 为可选项	如果您使用的是密钥对身份验证，则此标头为必填项。必须将此标头设置为 `KEYPAIR_JWT`。如果使用的是 OAuth 进行身份验证，则此标头为可选项。（如果选择设置此标头，请将其设置为 `OAUTH`。）

请求正文中的对象类型¶

向 `/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"}} 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 请求正文的 parameters 字段中（请参阅向 /api/v2/statements/ 发送的 POST 请求正文）。

备注

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`	（在请求中指定多个 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	网关超时。由于服务器超时，请求未得到处理。应用程序可能利用退避重试。建议使用指数抖动退避。

所有操作的响应标头¶

响应可以包含以下标头：

标头	描述
`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"> Copy

标头

描述

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

Copy

响应正文中的对象类型¶

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

Copy

`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" : "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 对象，其中包含有关语句执行状态的信息。此对象在以下内容中返回：

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

Copy

`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"] ] Copy 如果请求包含多个 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} ] Copy

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

Copy

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