Aller au contenu principal
Dernière mise à jour le

create_file function

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

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

Uploads string or binary content to a destination path and returns a FILE reference to the uploaded file.

Syntax​

create_file(content => content
  [, destination_path => path ]
  [, if_file_exists => mode ]
  [, content_type => content_type ])

You can pass arguments positionally or by name. After you pass an argument by name, all following arguments must also be passed by name. For more information, see named parameter invocation.

Arguments​

  • content: A STRING or BINARY expression with the content to store as a file. A STRING is stored as UTF-8 encoded bytes.
  • destination_path: An optional STRING path to upload the content to.
  • if_file_exists: An optional STRING that sets the behavior when a file already exists at the destination path. Applies only when using the destination_path argument. Accepted values (case insensitive) are:
    • 'error': Raises an error. This is the default value.
    • 'overwrite': Overwrites the existing file.
    • 'skip': Skips the upload and returns a FILE reference to the existing file.
  • content_type: An optional STRING that specifies the content type of the file. If not provided, the content type is inferred from the input bytes.

Returns​

A FILE value that references the uploaded file.

Notes​

  • If you use destination_path, the file is uploaded atomically to that path. You must have write access to the target location, which is typically a Unity Catalog volume.
  • If a file already exists at the destination path, Databricks raises an error by default unless you set if_file_exists to overwrite or skip.

Common error conditions​

  • CREATE_FILE_ERROR.FILE_ALREADY_EXISTS
  • CREATE_FILE_AUTHORIZATION_ERROR.WRITE_UNAUTHORIZED
  • CREATE_FILE_ILLEGAL_USAGE.CONTENT_REQUIRED
  • CREATE_FILE_ILLEGAL_USAGE.IF_FILE_EXISTS_WITHOUT_DESTINATION
  • CREATE_FILE_ILLEGAL_USAGE.IF_FILE_EXISTS_MODE

For more information, see Error conditions in Databricks.

Examples​

To store a string as a new file at a given path:

SQL
SELECT create_file(
  content => 'hello, world',
  destination_path => '/Volumes/my_catalog/my_schema/my_volume/greetings.txt'
);

To store raw bytes and set the content type explicitly:

SQL
SELECT create_file(
  content => my_binary_col,
  destination_path => '/Volumes/my_catalog/my_schema/my_volume/image.png',
  content_type => 'image/png'
)
FROM raw_uploads;

To skip the upload if a file already exists at the destination:

SQL
SELECT create_file(
  content => my_binary_col,
  destination_path => '/Volumes/my_catalog/my_schema/my_volume/report.pdf',
  if_file_exists => 'skip'
);

If destination_path isn't set, if_file_exists raises an error:

SQL
SELECT create_file(content => 'data', if_file_exists => 'overwrite');
Text
Error: CREATE_FILE_ILLEGAL_USAGE.IF_FILE_EXISTS_WITHOUT_DESTINATION
Sur cette page