Manage Volumes and Files

Upload caller-held bytes to a designated volume within a workspace, retaining the returned file resource. You can subsequently preview or download files using this resource, or create subfolders in the same volume.

Task workflow

  1. The caller provides workspace, catalog, database, volume name, file name, and file bytes.

  2. The SDK searches hierarchy layers (catalog, database, volume), creating any missing levels.

  3. The SDK uploads the bytes and attaches the file to the volume, returning a file resource.

  4. Use this file resource to preview or download content; close the response after stream consumption.

Prerequisites

Required item

Role on this page

Authenticated client and selected workspace

Determine the scope of the upload.

Catalog, database, and volume names

Select or create storage locations.

File name and byte contents

Data payload to upload.

Write permissions

Allow provisioning resources and attaching files.

This page does not automatically discover local files or deduce target paths from file names. The caller must explicitly select files and target workspaces beforehand.

Upload to a named volume

The following function prepares storage locations by name before uploading caller-held bytes. Preparing by name is not a read-only query; missing catalogs, databases, or volumes will be created.

def upload_orders(workspace, csv_bytes):
    volume = workspace.prepare_data_volume("analytics", "sales", "landing")
    file = volume.upload_bytes_handle("orders.csv", csv_bytes)
    return volume, file

import (
	"context"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func uploadOrders(ctx context.Context, workspace *sdk.WorkspaceHandle, csvBytes []byte) (*sdk.VolumeHandle, *sdk.FileHandle, error) {
	volume, err := workspace.PrepareDataVolume(ctx, "analytics", "sales", "landing")
	if err != nil {
		return nil, nil, err
	}
	file, err := volume.UploadBytesHandle(ctx, "orders.csv", csvBytes)
	if err != nil {
		return nil, nil, err
	}
	return volume, file, nil
}

Upon successful upload, the function returns the volume resource and file resource. Subsequent operations should continue using them rather than concatenating resource identifiers from display names or local paths.

Create folders and preview files

Use the volume resource obtained above to create a folder, and use the file resource to open a preview stream. Both preview and download are streaming responses; close them when read operations finish.

folder, _ = volume.create_folder("staging")
preview = file.preview()
try:
    content = preview.read()
finally:
    preview.close()
_ = folder, content

folder, _, err := volume.CreateFolder(ctx, "staging")
if err != nil {
	return err
}
preview, err := file.Preview(ctx)
if err != nil {
	return err
}
defer preview.Body.Close()
_ = folder

Result confirmation

Both folder and file resources remain scoped to the volume. When reacquiring resources by ID, use only identifiers from creation, listing, or explicit caller inputs. Reading preview streams does not imply that file contents have been processed by downstream tasks.

Limitations

  • Local path upload applies only to caller-selected local files; when bytes already reside in memory, use byte upload.

  • Renaming files does not persistently update names; do not treat rename calls as completion indicators.

  • Deleting files, volumes, or pruning folders permanently alters data. Verify ownership before executing deletion.

Next steps

Last updated on