提交执行 SQL 语句的请求¶

设置请求¶

在请求 URL，可以将查询参数设置为：

• 指定将此请求与其他请求区分开来的请求 ID。

• 异步执行语句。

对于 请求正文，设置以下字段：

• 将 statement 字段设置为要执行的 SQL 语句。例如：

  {
    "statement": "select * from my_table",
    ...
  }
  

  Copy

  如果要在单个请求中提交多个语句，请在语句之间使用分号 (;)。有关详细信息，请参阅 在单个请求中提交多个 SQL 语句。

• 如果在语句中包含绑定变量（? 占位符），请将 bindings 字段设置为指定每个变量的相应 Snowflake 数据类型和值的对象。

  有关详细信息，请参阅 在语句中使用绑定变量。

• 要指定要使用的仓库、数据库、架构和角色，请设置 warehouse、database、schema 和 role 字段。

  这些字段中的值区分大小写。

  如果省略这些字段， SQL API 将使用用户的相应属性值（即 :doc:` 用户的 DEFAULT_WAREHOUSE、DEFAULT_NAMESPACE 和 DEFAULT_ROLE 属性 </sql-reference/sql/alter-user>` ）。

• 要设置语句执行的超时，请将 timeout 字段设置为要等待的最大秒数。如果未设置 timeout 字段，则使用 STATEMENT_TIMEOUT_IN_SECONDS 参数指定的超时。

请求示例¶

例如，以下 curl 命令发送要执行的 SQL 语句。该示例使用文件 request-body.json 指定请求的正文。

curl -i -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt>" \
    -H "Accept: application/json" \
    -H "User-Agent: myApplicationName/1.0" \
    -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
    -d "@request-body.json" \
    "https://<account_identifier>.snowflakecomputing.cn/api/v2/statements"

其中：

• jwt 是您 为身份验证生成的 JWT。

• myApplicationName 是应用程序标识符的示例。

• account_identifier 是您的 账户标识符。

在此示例中， request-body.json 包含 请求的正文：

{
  "statement": "select * from T where c1=?",
  "timeout": 60,
  "database": "TESTDB",
  "schema": "TESTSCHEMA",
  "warehouse": "TESTWH",
  "role": "TESTROLE",
  "bindings": {
    "1": {
      "type": "FIXED",
      "value": "123"
    }
  }
}

在上面示例的请求正文中：

• statement 字段指定要执行的 SQL 语句。

  该语句包括一个 :ref:` 绑定变量 <label-sql_api_bind_variables>` （"cl=?" 中的问号），其计算结果为 bindings 字段中指定的第一个绑定 ("1")。

• timeout 字段指定服务器允许 60 秒的时间执行语句。

• database、schema、warehouse 和 role 字段指定在执行语句时应使用的 TESTDB 数据库、TESTSCHEMA 架构、TESTWH 仓库和 TESTROLE 角色。

在语句中使用绑定变量¶

如果要在语句中使用绑定变量（? 占位符），请使用 bindings 字段指定应插入的值。

将此字段设置为指定每个绑定变量的 Snowflake 数据类型 和值的 JSON 对象。

...
"statement": "select * from T where c1=?",
...
"bindings": {
  "1": {
    "type": "FIXED",
    "value": "123"
  }
},
...

选择与要绑定的值的类型相对应的绑定类型。例如，如果值是表示日期的 :emph:` 字符串 ` （例如 2021-04-15），并且要将该值插入到 DATE 列中，请使用 TEXT 绑定类型。

下表指定可用于绑定到此预览版本的不同 Snowflake 数据类型 的 type 字段值。

• 左侧的第一列指定可以使用的绑定类型。

• 其余列指定计划插入数据的列的 Snowflake 数据类型。

• 每个单元格指定可用于绑定类型的值类型，以将数据插入到特定 Snowflake 数据类型的列中。

  如果绑定类型和 Snowflake 数据类型的单元格为空，则不能使用指定的绑定类型将数据插入到该 Snowflake 数据类型的列中。

请注意以下事项：

• 绑定变量的值必须是字符串（例如，值 1.0 为 "1.0" ）。

• 使用 DATE 绑定类型时，请指定自纪元以来的 毫秒 数。

• 使用 TIME 或 TIMESTAMP* 绑定类型时，请指定自纪元以来的 纳秒 数。

• 使用 TIMESTAMP_TZ 绑定类型时，请指定自纪元以来的 纳秒 数，后跟一个空格和时区偏移量（以分钟为单位）（例如 1616173619000000000 960）。

• 使用 TEXT 绑定类型时：

  • 若要将数据插入到 DATE 列中，可以使用 AUTO 检测支持的任何 日期格式。

  • 若要将数据插入到 TIME 列中，可以使用 AUTO 检测支持的任何 时间格式。

  • 若要将数据插入到 TIMEZONE* 列中，可以使用 AUTO 检测支持的任何 日期时间格式。

如果该值的格式不受 Snowflake 支持，则 API 返回错误：

{
  code: "100037",
  message: "<bind type> value '<value>' is not recognized",
  sqlState: "22018",
  statementHandle: "<ID>"
}

提交并发请求¶

Snowflake SQL API 支持向服务器发送并发请求。API 的并发限制由 Snowflake 强制执行的并发限制确定。

根据当前服务器负载，可能会收到 HTTP 429 错误，该错误指示服务器当前接收的请求过多。

要确保应用程序正确处理 429 错误，请将并发请求包装在重试逻辑中。

重新提交执行 SQL 语句的请求¶

在某些情况下，可能不清楚 Snowflake 是否在 API 请求中执行了 SQL 语句（例如，由于网络错误或超时）。可以选择再次向 Snowflake 重新提交相同的请求，以防 Snowflake 未执行该语句。

但是，如果 Snowflake 已在初始请求中执行了该语句，并且再次重新提交该请求，则该语句将执行两次。对于某些类型的请求，重复执行相同的语句可能会产生意想不到的后果（例如，将重复的数据插入到表中）。

要防止 Snowflake 在重新提交请求时两次执行相同的语句，可以使用请求 ID 将请求与其他请求区分开来。如果在初始请求中指定相同的请求 ID 以及重新提交的请求中的 retry=true 参数，则在语句已成功执行时，Snowflake 不会再次执行该语句。

要指定请求 ID，请生成一个 通用唯一标识符 (UUID) (link removed)。然后，可以在 requestId 查询参数中包含此标识符。还必须将 retry=true 参数指定为请求的一部分，如以下示例所示。

POST /api/v2/statements?requestId=ea7b46ed-bdc1-8c32-d593-764fcad64e83&retry=true HTTP/1.1

如果 Snowflake 无法处理请求，可以使用相同的请求 ID 再次提交相同的请求。使用相同的请求 ID 会向服务器指示您再次提交相同的请求。