TRY_TO_FILE¶
A version of TO_FILE that returns NULL instead of raising an error.
Syntax¶
Use one of the following:
TRY_TO_FILE( <stage_name>, <relative_path> ) TRY_TO_FILE( <file_url> ) TRY_TO_FILE( <metadata> )
Arguments¶
Specify the file by providing:
Both
stage_name
andrelative_path
file_url
metadata
Only one of these methods can be used at a time.
stage_name
The name of the stage where the file is located, as a string, in the form
'@stage_name'
.relative_path
The path to the file on the stage specified by
stage_name
as a string.file_url
A valid stage or scoped file URL as a string.
metadata
An OBJECT containing the required FILE attributes. A FILE must have CONTENT_TYPE, SIZE, ETAG, and LAST_MODIFIED fields. It must also specify the file’s location in one of the following ways:
Both STAGE and RELATIVE_PATH
STAGE_FILE_URL
SCOPED_FILE_URL
Returns¶
A FILE, or NULL.
Usage notes¶
Returns NULL when:
The supplied URL is not validL.
The file is on a stage that the user lacks privileges to access.
The supplied metadata doesn’t contain the required FILE fields.
Examples¶
Unlike TO_FILE, which raises an error on invalid arguments, TRY_TO_FILE returns NULL in this situation. It otherwise works exactly like TO_FILE.
The example below illustrates the behavior of TRY_TO_FILE when given an invalid file path, assuming that
the file image.png
exists on the stage but the other two files do not.
SELECT
TRY_TO_FILE('@mystage/image.png'),
TRY_TO_FILE('@mystage/incorrect_file1.jpg'),
TRY_TO_FILE('@mystage', 'incorrect_file2.png');
Result:
+-----------------------------------------------------+---------------------------------------------+------------------------------------------------+
| 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" | | |
| } | | |
+-----------------------------------------------------+---------------------------------------------+------------------------------------------------+
For more examples of creating FILE objects from valid inputs, see TO_FILE examples.