绑定变量¶

应用程序可以接受来自用户的数据，并在 SQL 语句中使用该数据。例如，应用程序可能会要求用户输入联系信息，例如地址和电话号码。

要在 SQL 语句中指定此用户输入，您可以以编程方式构造一个字符串来表示该 SQL 语句，方法是将用户输入与其他语句部分拼接起来。或者，您可以使用 绑定变量。要绑定变量，请在 SQL 语句文本中放置一个或多个占位符，然后为每个占位符指定变量（要使用的值）。

绑定变量概述¶

使用绑定变量，您可以将 SQL 语句中的字面量替换为占位符。例如，以下 SQL 语句对插入的值使用字面量：

INSERT INTO t (c1, c2) VALUES (1, 'Test string');

Copy

以下 SQL 语句对插入的值使用占位符：

INSERT INTO t (c1, c2) VALUES (?, ?);

Copy

您的应用程序代码将数据与 SQL 语句中的每个占位符绑定在一起。使用占位符绑定数据的技术取决于编程语言。占位符的语法也因编程语言而异。可能是 ?、:varname，也可能是 %varname。

在 Javascript 存储过程中使用绑定变量¶

您可以使用 Javascript 来创建可执行 SQL 的存储过程。

要在 JavaScript 代码中指定绑定变量，请使用 ? 占位符。例如，以下 INSERT 语句可为插入到表行中的值指定绑定变量：

INSERT INTO t (col1, col2) VALUES (?, ?)

Copy

在 Javascript 代码中，您可以对大多数 SQL 语句中的值使用绑定变量。有关限制的信息，请参阅绑定变量的限制。

有关在 JavaScript 中使用绑定变量的更多信息，请参阅绑定变量。

在 Snowflake Scripting 中使用绑定变量¶

您可以使用 Snowflake Scripting 来创建执行 SQL 的过程代码，例如代码块和存储过程。要在 Snowflake Scripting 代码中指定绑定变量，请在变量名称前面加上冒号。例如，以下 INSERT 语句指定名为 variable1 的绑定变量：

INSERT INTO t (c1) VALUES (:variable1)

Copy

在 Snowflake Scripting 代码中，您可以对大多数 SQL 语句中的值使用绑定变量。有关限制的信息，请参阅绑定变量的限制。

有关在 Snowflake Scripting 中使用绑定变量的更多信息，请参阅在 SQL 语句中使用变量（绑定）和在 SQL 语句中使用实参（绑定）。

将绑定变量与 SQL API 结合使用¶

您可以使用 Snowflake SQL API 访问和更新 Snowflake 数据库中的数据。您可以创建使用 SQL API 的应用程序，以提交 SQL 语句并管理部署。

当您提交执行 SQL 语句的请求时，您可以对语句中的值使用绑定变量。有关更多信息，请参阅在语句中使用绑定变量。

将绑定变量与驱动程序一起使用¶

使用 Snowflake 驱动程序，您可以编写在 Snowflake 上执行操作的应用程序。驱动程序支持 Go、Java 和 Python 等编程语言。有关在应用程序中为特定驱动程序使用绑定变量的信息，请按照驱动程序的链接进行操作：

Go (https://pkg.go.dev/github.com/snowflakedb/gosnowflake#hdr-Binding_Parameters)
JDBC
.NET (https://github.com/snowflakedb/snowflake-connector-net/blob/master/doc/QueryingData.md#bind-parameter)
Node.js
ODBC
Python

备注

PHP 驱动程序不支持绑定变量。

将绑定变量与值数组结合使用¶

您可以将值数组绑定到 SQL 语句中的变量。使用此技术，您可以通过在单个批处理中插入多行来提高性能，从而避免网络往返和编译。数组绑定的使用也称为“批量插入”。

备注

Snowflake 支持建议使用的其他数据加载方法，而不是使用数组绑定。有关更多信息，请参阅将数据载入 Snowflake 和数据加载和卸载命令。

以下是 Python 代码中的数组绑定示例：

conn = snowflake.connector.connect( ... )
rows_to_insert = [('milk', 2), ('apple', 3), ('egg', 2)]
conn.cursor().executemany(
            "insert into grocery (item, quantity) values (?, ?)",
            rows_to_insert)

Copy

此示例指定以下绑定列表：[('milk', 2), ('apple', 3), ('egg', 2)]。应用程序指定绑定列表的方式取决于编程语言。

此代码在表中插入三行：

+-------+----+
| C1    | C2 |
|-------+----|
| milk  |  2 |
| apple |  3 |
| egg   |  2 |
+-------+----+

有关在应用程序中为特定驱动程序使用数组绑定的信息，请按照驱动程序的链接进行操作：

Go (https://pkg.go.dev/github.com/snowflakedb/gosnowflake#hdr-Batch_Inserts_and_Binding_Parameters)
JDBC
.NET (https://github.com/snowflakedb/snowflake-connector-net/blob/master/doc/QueryingData.md#bind-array-variables)
Node.js
ODBC
Python

备注

PHP 驱动程序不支持数组绑定。

使用数组绑定的限制¶

以下限制适用于数组绑定：

只有 INSERT INTO ... VALUES 语句可以包含数组绑定变量。
VALUES 子句必须是绑定变量的单行列表。例如，不允许出现以下 VALUES 子句：
```
VALUES (?,?), (?,?)
```
Copy

在不使用数组绑定的情况下插入多行¶

INSERT 语句可能会使用绑定变量插入多行，而不使用数组绑定。以下示例将值插入到两行中，但它不使用数组绑定。

INSERT INTO t VALUES (?,?), (?,?);

Copy

例如，应用程序可以按顺序为占位符指定一个绑定列表，该列表相当于以下值：[1,'String1',2,'String2']。因为 VALUES 子句指定多行时，语句仅插入确切的值数（在示例中为 4 个），而不是动态数量的行。

将绑定变量与半结构化数据结合使用¶

要将绑定变量与半结构化数据结合使用，请将变量绑定为字符串类型，并使用 PARSE_JSON 或 ARRAY_CONSTRUCT 等函数。

以下示例创建包含一个 VARIANT 列的表，然后调用 PARSE_JSON 函数将半结构化数据插入到带有绑定变量的表中：

CREATE TABLE t (a VARIANT);
-- Code that supplies a bind value for ? of '{'a': 'abc', 'x': 'xyz'}'
INSERT INTO t SELECT PARSE_JSON(a) FROM VALUES (?);

Copy

以下示例查询该表：

SELECT * FROM t;

Copy

该查询会返回以下输出：

+---------------+
| A             |
|---------------|
| {             |
|   "a": "abc", |
|   "x": "xyz"  |
| }             |
+---------------+

以下语句调用 ARRAY_CONSTRUCT 函数将半结构化数据数组插入到带有绑定变量的 VARIANT 列中：

INSERT INTO t SELECT ARRAY_CONSTRUCT(column1) FROM VALUES (?);

Copy

这两个示例都可以插入单行，也可以使用数组绑定在一个批处理中插入多行。您可以使用此技术插入 VARIANT 列中有效的任何类型的半结构化数据。

绑定变量的限制¶

以下限制适用于绑定变量：

SELECT 语句的限制：
- 绑定变量不能替换属于数据类型定义（例如 NUMBER(?)）或排序规则规范 <label-collation_specification>`（例如 ``COLLATE ?`）的数字。
- 在查询暂存区上的文件的 SELECT 语句中，绑定变量不能用于源代码。
DDL 命令的限制：
- 绑定变量不能在以下 DDL 命令中使用：
  - CREATE/ALTER INTEGRATION
  - CREATE/ALTER REPLICATION GROUP
  - CREATE/ALTER PIPE
  - CREATE TABLE ...USING TEMPLATE
- 绑定变量不能在以下子句中使用：
  - ALTER COLUMN
  - COMMENT ON CONSTRAINT
- 在 CREATE/ALTER 命令中，绑定变量不能用于以下参数的值：
  - CREDENTIALS
  - DIRECTORY
  - ENCRYPTION
  - IMPORTS
  - PACKAGES
  - REFRESH
  - TAG
  - 特定于外部表的参数
- 绑定变量不能用于属于 FILE FORMAT 值的属性。
在 COPY INTO 命令中，绑定变量不能用于以下参数的值：
- CREDENTIALS
- ENCRYPTION
- FILE_FORMAT
在 SHOW 命令中，绑定变量不能用于以下参数：
- LIKE
- LIMIT
- STARTS WITH
绑定变量不能在 EXECUTE IMMEDIATE FROM 命令中使用。
在以下内容中使用绑定变量时，绑定变量值无法自动从一种数据类型转换为另一种数据类型：
- 明确指定数据类型的 Snowflake Scripting 代码
- DDL 语句
- 暂存区名称

绑定变量的安全注意事项¶

绑定变量不会在所有情况下都对敏感数据进行掩码处理。例如，绑定变量的值可能会出现在错误消息和其他构件中。

绑定变量可以在构造带有用户输入的 SQL 语句时帮助防止 SQL 注入攻击。但是，绑定变量可能会带来潜在的安全风险。如果 SQL 语句的输入来自外部来源，请确保它们有效。有关更多信息，请参阅 SQL 注入。