# File These functions can be used to work with files. These functions can be used to work with files.

Function	Description
`file::bucket()`	Returns the bucket path from a file pointer
`file::copy()`	Copies the contents of a file
`file::copy_if_not_exists()`	Copies the contents of a file to a new file if the name is available
`file::delete()`	Deletes a file
`file::exists()`	Checks if a file already exists
`file::get()`	Loads a file
`file::head()`	Returns the metadata of a file
`file::key()`	Returns the key (the portion following the bucket) from a file pointer
`file::list()`	Returns a list of files inside a bucket
`file::put()`	Writes bytes to a file
`file::put_if_not_exists()`	Attempts to write bytes to a file
`file::rename()`	Renames a file
`file::rename_if_not_exists()`	Renames a file if the new name is not already in use

_(since v3.0.0)_ ## `file::bucket` ```surql title="API DEFINITION" file::bucket(file) -> string ``` The `file::bucket` function returns the name of the bucket in which a file is located. ```surql file::bucket(f"my_bucket:/file_name"); DEFINE PARAM $SOME_DATABASE_FILE VALUE f"my_bucket:/file_name"; file::bucket($SOME_DATABASE_FILE); ``` ```surql title="Output" 'my_bucket' ``` The counterpart to this function is `file::key`, which returns the latter part of a file pointer. ## `file::copy` The `file::copy` function copies the contents of a file to a new file, overwriting any existing file that has the same name as the new file. ```surql title="API DEFINITION" file::copy(string) ``` Example of a file `my_book.txt` being copied to a new location `lion_witch_wardrobe.txt`: ```surql f"my_bucket:/my_book.txt".copy("lion_witch_wardrobe.txt"); ```

## `file::copy_if_not_exists` The `file::copy_if_not_exists` function copies the contents of a file to a new file, returning an error if a file already exists that has the same name as that of the intended copy. ```surql title="API DEFINITION" file::copy_if_not_exists(string) ``` Example of a file `my_book.txt` attempting to copy to a new location `lion_witch_wardrobe.txt`: ```surql DEFINE BUCKET my_bucket BACKEND "memory"; f"my_bucket:/lion_witch_wardrobe.txt".put("Once there were four children whose names were Peter, Susan..."); f"my_bucket:/other_book.txt".put("Um meine Geschichte zu erzählen, muß ich weit vorn anfangen."); f"my_bucket:/other_book.txt".copy_if_not_exists("lion_witch_wardrobe.txt"); ``` ```surql title="Output" 'Operation for bucket `my_bucket` failed: Object at location lion_witch_wardrobe.txt already exists: Object already exists at that location: lion_witch_wardrobe.txt' ```

## `file::delete` The `file::delete` function deletes a file. ```surql title="API DEFINITION" file::delete(string) ``` Example of a file `my_book.txt` being deleted: ```surql f"my_bucket:/my_book.txt".delete(); ```

## `file::exists` The `file::exists` function checks to see if a file exists at the path and file name indicated. ```surql title="API DEFINITION" file::exists(string) -> bool ``` Example of an `IF` else `STATEMENT` used to check if a file exists before writing content to the location: ```surql IF f"my_bucket:/my_book.txt".exists() { THROW "Whoops, already there!" } ELSE { f"my_bucket:/my_book.txt".put("Some content") }; ```

## `file::get` The `file::get` function retrieves a file for use. ```surql title="API DEFINITION" file::get(string) -> bytes ``` A retrieved file will display as bytes. If valid text, these can be cast into a `string`. ```surql f"my_bucket:/my_book.txt".get(); f"my_bucket:/my_book.txt".get(); ``` ```surql title="Output" -------- Query -------- b"536F6D6520636F6E74656E74" -------- Query -------- 'Once there were four children whose names were Peter, Susan...' ```

## `file::head` The `file::head` function returns the metadata for a file. ```surql title="API DEFINITION" file::head() -> object ``` If a file is found, the metadata will be returned as an object with the following fields: * `e_data` (`option`): the unique identifier for the file. * `last_modified` (`datetime`) * `location` (`string`) * `size` (`int`) * `version` (`option`) An example of this function and its output: ```surql f"my_bucket:/my_book.txt".head(); ``` ```surql title="Output" { e_tag: '1', key: 'my_book.txt', last_modified: d'2025-03-26T06:29:18.988Z', size: 78, version: NONE } ```

## `file::key` ```surql title="API DEFINITION" file::key(file) -> string ``` The `file::key` function returns the key of a file: the part of a file pointer following the bucket name. ```surql file::key(f"my_bucket:/file_name"); DEFINE PARAM $SOME_DATABASE_FILE VALUE f"my_bucket:/file_name"; file::key($SOME_DATABASE_FILE); ``` ```surql title="Output" '/file_name' ``` The counterpart to this function is `file::bucket`, which returns the bucket name of a file pointer. ## `file::list` ```surql title="API DEFINITION" file::list(string, $list_options: option