snowflake.snowpark.FileOperation.copy_files¶

FileOperation.copy_files(source: Union[str, DataFrame], target_stage_location: str, *, files: Optional[List[str]] = None, pattern: Optional[str] = None, detailed_output: bool = True, statement_params: Optional[Dict[str, str]] = None) → Union[List[str], int][source]¶

Copy files from a source location to an output stage.

You can use either a stage location (str) or a DataFrame as the source:

  • DataFrame source: The DataFrame must have exactly one or two columns of string type. Column names are not significant; Snowflake interprets columns by position:

    • First column (required): The existing url of the source file location (scoped URL, stage name, or stage URL).

    • Second column (optional): Then new file name which is the relative output path from the target stage. The file is copied to @[<namespace>.]<stage_name>[/<path>]<new_filename>.

    If the second column is not provided, Snowflake uses the relative path of the first column’s value. Invalid input (for example, missing the first column, non-string values, or extra columns) is rejected by Snowflake and results in a server-side error.

  • Stage location source: Provide a stage location string for source. You can optionally use files or pattern to restrict which files are copied.

References: Snowflake COPY FILES command.

Parameters:

  • source – The source to copy from. Either a stage location string, or a DataFrame with 1–2 string columns where the first column is required (existing url) and the second column is optional (new file name).

  • target – The target stage and path where files will be copied.

  • files – Optional list of specific file names to copy; only applicable when source is a stage location string.

  • pattern – Optional regular expression pattern for filtering files to copy; only applicable when source is a stage location string.

  • detailed_output – If True, returns details for each file; if False, returns only the number of files copied. Defaults to True.

  • statement_params – Dictionary of statement level parameters to be set while executing this action.

Examples

>>> # Create a temp stage.
>>> _ = session.sql("create or replace temp stage source_stage").collect()
>>> _ = session.sql("create or replace temp stage target_stage").collect()
>>> # Upload a file to a stage.
>>> _ = session.file.put("tests/resources/testCSV.csv", "@source_stage", auto_compress=False)
>>> # Copy files from source stage to target stage.
>>> session.file.copy_files("@source_stage", "@target_stage")
['testCSV.csv']
>>> # Copy files from source stage to target stage using a DataFrame.
>>> df = session.create_dataframe(
...     [["@source_stage/testCSV.csv", "new_file_1"]],
...     schema=["existing_url", "new_file_name"],
... )
>>> session.file.copy_files(df, "@target_stage", detailed_output=False)
1
Copy
Returns:

If detailed_output is True, a list[str] of copied file paths. Otherwise, an int indicating the number of files copied.

Language: English