The examples in this guide use Named Volume (internal Volume), which requires no external storage mount and can be used immediately after creation:
Create a Named Volume (one-time operation)
session.sql("CREATE VOLUME IF NOT EXISTS my_named_vol").collect()
⚠️ After uploading files with session.file.put, run ALTER VOLUME my_named_vol REFRESH to refresh the directory index before session.read methods can see the new files.
💡 To mount existing OSS/S3/COS object storage, use an External Volume. See External Volume.
File Upload and Download
Upload a Local File to a Volume
Upload a single file
result = session.file.put(
"/local/path/data.csv",
"volume://my_named_vol/data/data.csv",
auto_compress=False
)
print(result)
User Volume is each user's personal storage space. session.file methods are not supported — use SQL commands instead:
Upload to User Volume
session.sql("PUT '/local/path/file.csv' TO USER VOLUME FILE 'subdir/file.csv'").collect()
List User Volume files
files = session.sql("SHOW USER VOLUME DIRECTORY").collect()
for f in files:
print(f["relative_path"], f["size"])
Read from User Volume (via SQL SELECT FROM VOLUME)
df = session.sql("""
SELECT * FROM USER VOLUME
USING CSV
OPTIONS('header'='true')
FILES('subdir/file.csv')
""")
df.show()
Download a User Volume file
session.sql("GET USER VOLUME FILE 'subdir/file.csv' TO '/local/output/'").collect()
Notes
Path format: Volume paths use volume://volume_name/path; @vol_name or relative paths are not supported
REFRESH required after upload: After uploading files with session.file.put, run ALTER VOLUME name REFRESH to refresh the directory index before session.read methods can see the new files
Wait after creating a new Volume: A newly created Named Volume needs approximately 1 minute to initialize before files can be uploaded and read
Parquet reads: Pass a directory path (ending with /) to read all Parquet files in that directory
Export paths: The copy_into_volume target path should end with /; file names are auto-generated by the system (e.g., part00001.csv)
