Categories:

ファイル関数 (AI Functions)

TRY_TO_FILE

エラーの代わりに NULL を返す TO_FILE のバージョン。

構文

次のいずれかを使用します。

TRY_TO_FILE( <stage_name>, <relative_path> )

TRY_TO_FILE( <file_url> )

TRY_TO_FILE( <metadata> )

引数

次を指定して、ファイルを指定します。

  • stage_name および :samp:`{relative_path}`の両方。

  • file_url

  • metadata

一度に使用できるメソッドは1つだけです。

stage_name

ファイルが文字列として '@stage_name' の形式で配置されているステージの名前。

relative_path

文字列として stage_name で指定されたステージ上のファイルへのパス。

file_url

有効なステージまたはスコープ付きファイル URL を文字列で指定します。

metadata

OBJECT に必要なFILE 属性を含むもの。FILE には CONTENT_TYPE、 SIZE、ETAGおよび LAST_MODIFIED フィールドが必要です。また、次のいずれかの方法でファイルの場所を指定する必要があります。

  • STAGE と RELATIVE_PATH の両方

  • STAGE_FILE_URL

  • SCOPED_FILE_URL

戻り値

FILE、または NULL。

使用上の注意

次の場合に NULL を返します。

  • 指定された URL は有効ではありません。

  • ファイルは、ユーザーにアクセス権限がないステージにあります。

  • 提供されたメタデータに必須である FILE フィールドが含まれていない。

例

TO_FILE無効な引数でエラーが発生するのとは異なり、 TRY_TO_FILE はこの状況で NULL を返します。それ以外の場合は、:doc:`TO_FILE</sql-reference/functions/to_file>`と同様に機能します。

次の例は、ファイル image.png はステージ上に存在するが、他の2つのファイルは存在しない場合、無効なファイルパスが指定された際のTRY_TO_FILE 動作を示しています。

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 オブジェクトの作成例については、:ref:`TO_FILE の例 <label-to_file_examples>`をご参照ください。