Categories:

文件函数 (AI Functions)

TRY_TO_FILE

TO_FILE 的一个版本，遇到错误时返回 NULL 而不是引发错误。

语法

使用下列之一：

TRY_TO_FILE( <stage_name>, <relative_path> )

TRY_TO_FILE( <file_url> )

TRY_TO_FILE( <metadata> )

实参

通过提供以下内容来指定文件：

  • stage_name 和 relative_path

  • file_url

  • metadata

一次只能使用其中一种方法。

stage_name

文件所在暂存区的名称，以 '@stage_name' 形式的字符串表示。

relative_path

暂存区上文件的路径，由 stage_name 以字符串形式指定。

file_url

字符串形式的有效暂存区或作用域文件 URL。

metadata

包含所需的 FILE 属性的 OBJECT。FILE 必须有 CONTENT_TYPE、SIZE、ETAG 和 LAST_MODIFIED 字段。它还必须通过以下方式之一指定文件的位置：

  • STAGE 和 RELATIVE_PATH

  • STAGE_FILE_URL

  • SCOPED_FILE_URL

返回

:doc:` FILE </sql-reference/data-types-unstructured>` 或 NULL。

使用说明

在以下情况下返回 NULL：

  • 提供的 URL 无效。

  • 文件位于用户无权访问的暂存区。

  • 提供的元数据不包含必填 FILE 字段。

示例

与 TO_FILE 在遇到无效实参时会抛出错误不同，TRY_TO_FILE 在此种情况下会返回 NULL。除此之外，它的功能与 TO_FILE 完全一致。

下面的示例演示了当 TRY_TO_FILE 函数遇到无效文件路径时的行为，假设文件 image.png 存在于暂存区中，而另外两个文件不存在。

SELECT
    TRY_TO_FILE('@mystage/image.png'),
    TRY_TO_FILE('@mystage/incorrect_file1.jpg'),
    TRY_TO_FILE('@mystage', 'incorrect_file2.png');

结果：

+-----------------------------------------------------+---------------------------------------------+------------------------------------------------+
| TRY_TO_FILE('@MYSTAGE/IMAGE.PNG')                   | TRY_TO_FILE('@MYSTAGE/INCORRECT_FILE1.JPG') | TRY_TO_FILE('@MYSTAGE', 'INCORRECT_FILE2.PNG') |
|-----------------------------------------------------|---------------------------------------------|------------------------------------------------|
| {                                                   | NULL                                        | NULL                                           |
|   "CONTENT_TYPE": "image/png",                      |                                             |                                                |
|   "ETAG": "2859efde6e26491810f619668280a2ce",       |                                             |                                                |
|   "LAST_MODIFIED": "Thu, 18 Sep 2025 09:02:00 GMT", |                                             |                                                |
|   "RELATIVE_PATH": "image.png",                     |                                             |                                                |
|   "SIZE": 23698,                                    |                                             |                                                |
|   "STAGE": "@MYDB.MYSCHEMA.MYSTAGE"                 |                                             |                                                |
| }                                                   |                                             |                                                |
+-----------------------------------------------------+---------------------------------------------+------------------------------------------------+

有关从有效输入创建 FILE 对象的更多示例，请参阅 TO_FILE 示例。