to_file function

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 18 LTS and above

Important

This feature is in Beta.

Returns a FILE value that references the file at path.

Syntax

to_file(path)

Arguments

  • path: A STRING expression specifying the path to a file. For example, a path in a Unity Catalog volume.

Returns

A FILE value that references the file at path.

To gather file metadata, Azure Databricks makes a remote call to the file's storage location. If the file doesn't exist or is inaccessible, Azure Databricks raises an error. To return NULL instead, use try_to_file function.

Common error conditions

  • TO_FILE_ERROR.FILE_NOT_EXISTS
  • TO_FILE_AUTHORIZATION_ERROR.READ_UNAUTHORIZED
  • TO_FILE_ILLEGAL_USAGE.NO_PATH_PROVIDED

For more information, see Error conditions in Azure Databricks.

Examples

To create a FILE reference from a path in a volume:

SELECT to_file('/Volumes/my_catalog/my_schema/my_volume/report.pdf');

If the path doesn't exist or the user lacks read permission, to_file raises an error:

SELECT to_file('/Volumes/my_catalog/my_schema/my_volume/ghost.csv');

Error: TO_FILE_ERROR.FILE_NOT_EXISTS
  • Last updated on