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. Workspace admins can control access to this feature from the Previews page. See Manage Azure Databricks previews.

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