类别：: 表函数

TO_QUERY¶

返回基于 SQL 文本和一组可选实参的结果集，如果 SQL 文本已参数化，则这些参数将传递给该文本。该函数将 SQL 文本编译为 FROM 子句中子查询的定义。在编写应用程序或存储过程时，您可以调用此函数来构造 SQL 语句。

备注

此函数可以在查询语句中纳入用户输入，这具有潜在的安全风险，例如 SQL 注入。如果函数的输入来自外部来源，请确保它们有效。有关更多信息，请参阅 SQL 注入。

另请参阅:: 运行时构造 SQL

语法¶

TO_QUERY( SQL => '<string>' [ , <arg> => '<value>' [, <arg> => '<value>' ...] ] )

实参¶

必填

SQL => 'string': 子查询的字符串表示形式。

可选

arg => 'value': 传递给 SQL string 的绑定变量。

返回¶

返回通过执行指定的 SQL 文本或 NULL 所生成的结果集。如果任意实参为 NULL，则此函数返回 NULL 且不报告任何错误。

使用说明¶

所有实参都必须是以下项之一：
- 常量字符串。
- SQL 变量或解析为字符串的 Snowflake Scripting 变量。
如果需要将实参中传递的字符串转换为其他数据类型，可以在 SQL string 中使用转换函数将字符串转换为其他数据类型。
定义结果集的列集派生自编译后的 SQL 语句中的 SELECT 列表。
该函数仅 SQL 语句的 FROM 子句中有效。

示例¶

创建表并插入数据。

CREATE OR REPLACE TABLE to_query_example (
  deptno NUMBER(2),
  dname  VARCHAR(14),
  loc    VARCHAR(13))
AS SELECT
  column1,
  column2,
  column3
FROM
  VALUES
    (10, 'ACCOUNTING', 'NEW YORK'),
    (20, 'RESEARCH',   'DALLAS'  ),
    (30, 'SALES',      'CHICAGO' ),
    (40, 'OPERATIONS', 'BOSTON'  );

这些示例使用此表中的数据。

在 SQL 语句中使用 TO_QUERY¶

首先，为表名设置一个会话变量（SQL 变量）：

SET table_name = 'to_query_example';

这些示例使用会话变量和 IDENTIFIER() 以识别表。

Using IDENTIFIER() to identify database objects is a best practice because it can make code more reusable and help to prevent SQL injection risks.

以下示例使用 TO_QUERY 函数返回 to_query_example 表中的所有数据：

SELECT * FROM TABLE(TO_QUERY('SELECT * FROM IDENTIFIER($table_name)'));

+--------+------------+----------+
| DEPTNO | DNAME      | LOC      |
|--------+------------+----------|
|     10 | ACCOUNTING | NEW YORK |
|     20 | RESEARCH   | DALLAS   |
|     30 | SALES      | CHICAGO  |
|     40 | OPERATIONS | BOSTON   |
+--------+------------+----------+

以下示例使用 TO_QUERY 函数返回 to_query_example 表中 deptno 列的所有值：

SELECT deptno FROM TABLE(TO_QUERY('SELECT * FROM IDENTIFIER($table_name)'));

+--------+
| DEPTNO |
|--------|
|     10 |
|     20 |
|     30 |
|     40 |
+--------+

以下示例使用 TO_QUERY 函数将一个实参传递给 SQL 语句，使其返回 to_query_example 表中 deptno 等于 10 的行：

SELECT * FROM TABLE(
  TO_QUERY(
    'SELECT * FROM IDENTIFIER($table_name)
    WHERE deptno = TO_NUMBER(:dno)', dno => '10'
    )
  );

+--------+------------+----------+
| DEPTNO | DNAME      | LOC      |
|--------+------------+----------|
|     10 | ACCOUNTING | NEW YORK |
+--------+------------+----------+

以下示例与上一个示例相同，但它使用会话变量将 deptno 值传递至 TO_QUERY 函数：

SET dept = '10';

SELECT * FROM TABLE(
  TO_QUERY(
    'SELECT * FROM IDENTIFIER($table_name)
    WHERE deptno = TO_NUMBER(:dno)', dno => $dept
    )
  );

+--------+------------+----------+
| DEPTNO | DNAME      | LOC      |
|--------+------------+----------|
|     10 | ACCOUNTING | NEW YORK |
+--------+------------+----------+

以下示例使用 TO_QUERY 函数将两个实参传递给 SQL 语句，使其返回 to_query_example 表中 deptno 等于 10 或 dname 等于 SALES 的行：

SELECT * FROM TABLE(
  TO_QUERY(
    'SELECT * FROM IDENTIFIER($table_name)
    WHERE deptno = TO_NUMBER(:dno) OR dname = :dnm',
    dno => '10', dnm => 'SALES'
    )
  );

+--------+------------+----------+
| DEPTNO | DNAME      | LOC      |
|--------+------------+----------|
|     10 | ACCOUNTING | NEW YORK |
|     30 | SALES      | CHICAGO  |
+--------+------------+----------+

在存储过程中使用 TO_QUERY¶

下面的示例在存储过程中使用 TO_QUERY 函数：

CREATE OR REPLACE PROCEDURE get_num_results_tq(query VARCHAR)
RETURNS TABLE ()
LANGUAGE SQL
AS
DECLARE
  res RESULTSET DEFAULT (SELECT COUNT(*) FROM TABLE(TO_QUERY(:query)));
BEGIN
  RETURN TABLE(res);
END;

Note: If you use Snowflake CLI, SnowSQL, the Classic Console, or the execute_stream or execute_string method in Python Connector code, use this example instead (see Using Snowflake Scripting in Snowflake CLI, SnowSQL, and Python Connector):

CREATE OR REPLACE PROCEDURE get_num_results_tq(query VARCHAR)
RETURNS TABLE ()
LANGUAGE SQL
AS
$$
DECLARE
  res RESULTSET DEFAULT (SELECT COUNT(*) FROM TABLE(TO_QUERY(:query)));
BEGIN
  RETURN TABLE(res);
END;
$$
;

调用存储过程：

CALL get_num_results_tq('SELECT * FROM to_query_example');

+----------+
| COUNT(*) |
|----------|
|        4 |
+----------+

CALL get_num_results_tq('SELECT * FROM to_query_example WHERE deptno = 20');

+----------+
| COUNT(*) |
|----------|
|        1 |
+----------+

以下示例在存储过程中使用 TO_QUERY 函数，并配有绑定变量：

CREATE OR REPLACE PROCEDURE get_results_tqbnd(dno VARCHAR)
RETURNS TABLE ()
LANGUAGE SQL
AS
DECLARE
  res RESULTSET DEFAULT (SELECT * FROM TABLE(
    TO_QUERY(
      'SELECT * FROM to_query_example
      WHERE deptno = TO_NUMBER(:dnoval)', dnoval => :dno
    )
  ));
BEGIN
  RETURN TABLE(res);
END;

CREATE OR REPLACE PROCEDURE get_results_tqbnd(dno VARCHAR)
RETURNS TABLE ()
LANGUAGE SQL
AS
$$
DECLARE
  res RESULTSET DEFAULT (SELECT * FROM TABLE(
    TO_QUERY(
      'SELECT * FROM to_query_example
      WHERE deptno = TO_NUMBER(:dnoval)', dnoval => :dno
    )
  ));
BEGIN
  RETURN TABLE(res);
END;
$$
;

调用存储过程：

CALL get_results_tqbnd('40');

+--------+------------+--------+
| DEPTNO | DNAME      | LOC    |
|--------+------------+--------|
|     40 | OPERATIONS | BOSTON |
+--------+------------+--------+

使用会话变量调用存储过程：

SET dept = '20';

CALL get_results_tqbnd($dept);

+--------+----------+--------+
| DEPTNO | DNAME    | LOC    |
|--------+----------+--------|
|     20 | RESEARCH | DALLAS |
+--------+----------+--------+