在单个请求中提交多个 SQL 语句

本主题说明如何向 Snowflake SQL API 提交包含多个语句的请求。

本主题内容：

简介

在某些情况下，可能需要在请求中指定多个 SQL 语句。例如，您可能需要执行以下操作：

  • 定义显式事务

  • 在请求中的语句中设置和使用会话变量

  • 在请求中的语句中创建和使用临时表

  • 更改请求中语句的数据库、架构、仓库或角色

以下各部分说明如何提交包含多个 SQL 语句的请求。

在请求中指定多个 SQL 语句

要在单个请求中提交多个 SQL 语句，请执行以下操作：

  • 在 statement 字段中，在每个语句之间使用分号 (;)。

  • 在 parameters 字段中，将 MULTI_STATEMENT_COUNT 字段设置为请求中 SQL 语句的数量。

例如：

POST /api/v2/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

{
  "statement": "alter session set QUERY_TAG='mytesttag'; select count(*) from mytable",
  ...
  "parameters": {
      "MULTI_STATEMENT_COUNT": "2"
  }
}
Copy

在本例中，MULTI_STATEMENT_COUNT 已设为 2，对应于所提交的 SQL 语句数量。

若要在 statement 字段中提交可变数量的 SQL 语句，请将 MULTI_STATEMENT_COUNT 设置为 0。如果应用程序在运行时不知道提交的 SQL 语句数量，这种设置非常有用。

如果 MULTI_STATEMENT_COUNT 的值与 statement 字段中指定的 SQL 语句数量不匹配， SQL API 返回以下错误：

Actual statement count <actual_count> did not match the desired statement count <desired_count>.
Copy

其中

  • actual_count 是 statement 字段中指定的语句数量。

  • desired_count 是 MULTI_STATEMENT_COUNT 的值。

如果在 statement 字段中指定多个 SQL 语句，但未指定 MULTI_STATEMENT_COUNT 字段，则 SQL API 返回以下错误：

Actual statement count 3 did not match the desired statement count 1.
Copy

备注

Snowflake 目前不支持多语句 SQL 请求中的变量绑定。

获取请求中每个 SQL 语句的结果

如果成功处理了包含多个 SQL 语句的请求，则响应不包括执行各个语句返回的数据。相反，响应包含一个 statementHandles 字段，该字段包含各个语句的句柄数组。

备注

statementHandles 字段与 statementHandle 字段不同：

  • statementHandle 字段指定请求中 SQL 语句集的句柄。

  • statementHandles 字段是请求中各个 SQL 语句的句柄数组。

例如，假设发送了一个指定了两个要执行的 SQL 语句的请求：

POST /api/v2/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

{
  "statement": "select * from A; select * from B",
  ...
}
Copy

响应包含一个 statementHandles 字段，该字段包含各个语句的句柄数组。

HTTP/1.1 200 OK
...
{
  ...
  "statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
  ...
}
Copy

要检查各个语句的状态并检索数据，请向 /api/v2/statements/ 端点发送 GET 请求，并将每个语句的句柄追加到 URL 路径。有关详细信息，请参阅 检查语句执行状态并检索数据。

GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02412
...
Copy
GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02416
...
Copy

处理在请求中指定多个语句时的错误

如果在请求中指定了多个 SQL 语句，并且在执行任何语句时发生了错误，Snowflake 将返回 HTTP 响应代码 422 和 QueryFailureStatus 对象。

您可以从此对象获取 有关错误的详细信息。

例如，假设请求指定了以下语句，其中第二个 INSERT 语句包含错误：

{
  "statement": "create or replace table table1 (i int); insert into table1 (i) values (1); insert into table1 (i) values ('This is not a valid integer.'); insert into table1 (i) values (2); select i from table1 order by i",
  ...
}
Copy

Snowflake 返回一个 HTTP 响应，响应代码为 422，并带有一个包含有关错误的详细信息的 QueryFailureStatus 对象：

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
...
{
  "code" : "100132",
  "message" : "JavaScript execution error: Uncaught Execution of multiple statements failed on statement \"insert into table1 (i) values ...\" (at line 1, position 75).\nNumeric value 'This is not a valid integer.' is not recognized in SYSTEM$MULTISTMT at '    throw `Execution of multiple statements failed on statement {0} (at line {1}, position {2}).`.replace('{1}', LINES[i])' position 4\nstackstrace: \nSYSTEM$MULTISTMT line: 10",
  "sqlState" : "P0000",
  "statementHandle" : "019d6e97-0502-317e-0000-096d0041f036"
}
Copy

在上面的示例中，出错的 INSERT 语句从 statement 字段 值 中的字符位置 75 开始。

出错语句之前的语句执行成功（在本例中为 CREATE TABLE 和第一个 INSERT 语句）。不执行出错语句之后的语句。

语言: 中文